Connector Details
Type
SaaS & APIs
Runs on
Google Compute Engine
Last Update
24 October, 2024
Category
SERP API
Overview
The SerpAPI Connector enables seamless access to SerpAPI services, providing search results, location data, account information, and archived search results. It supports endpoints for querying search results, retrieving supported locations, fetching account details, and accessing archived searches. This documentation outlines each endpoint, its purpose, parameters, and expected outputs.
SerpAPI offers various pricing plans based on search usage, throughput, and features.
Integration Overview
This document provides a detailed guide for each endpoint, its purpose, configuration, and workflow support using the SerpAPI Connector. The connector forwards HTTP GET requests to the SerpAPI service, handling query parameters and headers, and optionally appending an API key from environment variables.
Supported Integration Action Points:
- get_search_results: Retrieves search results based on a query and optional parameters.
- get_locations: Retrieves a list of supported locations for geolocation-based searches.
- get_account_info: Retrieves account details for a given API key.
- get_search_archive: Retrieves archived search results for a specific search ID.
Detailed Integration Documentation
Search Results Retrieval
Action
get_search_results
Purpose
Retrieves search results from SerpAPI based on a query string and optional parameters such as search engine, location, language, and pagination settings.
Parameters
- Required
- q: Search query (string, e.g., “coffee shops Stockholm”).
- api_key: SerpAPI API key for authentication (string, can be provided via environment variable CONNECTOR_ENV_SERPAPI_API_KEY).
- Optional:
- engine: Search engine or platform (string, e.g., “google”).
- location: Geolocated location (string, e.g., “Stockholm, Sweden”).
- google_domain: Google domain for search (string, e.g., “google.se”).
- hl: Language code (string, e.g., “sv” for Swedish).
- gl: Country code (string, e.g., “se” for Sweden).
- tbm: Google search type (string, e.g., “lcl” for local results).
- num: Number of results to return (integer, e.g., 10).
- start: Result offset for pagination (integer, e.g., 0).
- async: Enable asynchronous search (string, e.g., “true”).
Configuration
- Ensure the Flask application is running with the correct base URL.
- Set the environment variable CONNECTOR_ENV_SERPAPI_BASE_URL if using a custom SerpAPI endpoint.
- Optionally set CONNECTOR_ENV_SERPAPI_API_KEY to automatically include the API key in requests.
- Configure the port using CONNECTOR_ENV_PORT (default: 8081).
Output
- Successful: Returns a JSON object with search results as provided by SerpAPI, including organic results, related searches, or local business data, depending on the query and parameters.
- Failure: Returns error codes (e.g., 400: Bad Request, 401: Unauthorized, 500: Internal Server Error).
Workflow Example
1. Configure the Flask app with CONNECTOR_ENV_SERPAPI_API_KEY and CONNECTOR_ENV_PORT.
2. Execute a GET request to /search with q=coffee shops Stockholm and api_key=.
3. Process the JSON response to display search results in a web or mobile application.
Locations Retrieval
Action
get_locations
Purpose
Retrieves a list of supported locations for geolocation-based searches, filtered by a location query and result limit.
Parameters
- Optional:
- q: Location query (string, e.g., “Stockholm”).
- limit: Number of location results to return (integer, e.g., 5).
- api_key: SerpAPI API key for authentication (string, can be provided via environment variable CONNECTOR_ENV_SERPAPI_API_KEY).
Configuration
- Ensure the Flask application is running with the correct base URL.
- Set the environment variable CONNECTOR_ENV_SERPAPI_BASE_URL if using a custom SerpAPI endpoint.
- Optionally set CONNECTOR_ENV_SERPAPI_API_KEY to automatically include the API key.
- Configure the port using CONNECTOR_ENV_PORT (default: 8081).
Output
- Successful: Returns a JSON object with a list of supported locations, including city, country, and geolocation details.
- Failure: Returns error codes (e.g., 400: Bad Request, 401: Unauthorized, 500: Internal Server Error).
Workflow Example
1. Configure the Flask app with CONNECTOR_ENV_SERPAPI_API_KEY.
2. Execute a GET request to /locations.json with q=Stockholm and limit=5.
3. Use the response to populate a location selection dropdown in a search interface.
get_account_info
Action
get_search_results
Purpose
Retrieves account details for a given SerpAPI API key, including usage limits and account status.
Parameters
- Required
- q: Search query (string, e.g., “coffee shops Stockholm”).
- api_key: SerpAPI API key for authentication (string, can be provided via environment variable CONNECTOR_ENV_SERPAPI_API_KEY).
Configuration
- Ensure the Flask application is running with the correct base URL.
- Set the environment variable CONNECTOR_ENV_SERPAPI_BASE_URL if using a custom SerpAPI endpoint.
- Optionally set CONNECTOR_ENV_SERPAPI_API_KEY to automatically include the API key.
- Configure the port using CONNECTOR_ENV_PORT (default: 8081).
Output
- Successful: Returns a JSON object with account details, such as remaining searches, plan type, and account status.
- Failure: Returns error codes (e.g., 400: Bad Request, 401: Unauthorized, 500: Internal Server Error).
Workflow Example
1. Configure the Flask app with CONNECTOR_ENV_SERPAPI_API_KEY.
2. Execute a GET request to /account with api_key=.
3. Display account details in an admin dashboard to monitor API usage.
Archived Search Results Retrieval
Action
get_search_archive
Purpose
Retrieves archived search results for a specific search ID, allowing access to previously executed searches.
Parameters
- Required
- search_id: Unique identifier of the archived search (string, e.g., “12345”).
- api_key: SerpAPI API key for authentication (string, can be provided via environment variable CONNECTOR_ENV_SERPAPI_API_KEY).
Configuration
- Ensure the Flask application is running with the correct base URL.
- Set the environment variable CONNECTOR_ENV_SERPAPI_BASE_URL if using a custom SerpAPI endpoint.
- Optionally set CONNECTOR_ENV_SERPAPI_API_KEY to automatically include the API key.
- Configure the port using CONNECTOR_ENV_PORT (default: 8081).
Output
- Successful: Returns a JSON object with the archived search results, including the original query, results, and metadata.
- Failure: Returns error codes (e.g., 400: Bad Request, 401: Unauthorized, 500: Internal Server Error).
Workflow Example
1. Configure the Flask app with CONNECTOR_ENV_SERPAPI_API_KEY.
2. Execute a GET request to /searches/12345.json with api_key=.
3. Use the response to display historical search data for analysis or reporting.
Workflow Creation with the SerpAPI Connector
Example Workflow: Search and Location Integration
Retrieve Supported Locations
- Execute the get_locations action with q=Stockholm and limit=5.
- Use the response to populate a location picker in a search interface.
Perform Search Query
- Execute the get_search_results action with q=coffee shops Stockholm, location=Stockholm, Sweden, and api_key=.
- Process the response to display search results, such as local business listings, in a web or mobile application.
Monitor Account Status
- Execute the get_account_info action with api_key=.
- Display account details to ensure sufficient API quota for continued operation.
Access Archived Searches
- Execute the get_search_archive action with search_id=12345 and api_key=.
- Use the response to analyze historical search data for trends or reporting.
Pricing
iSolution logo - white - transparent 250 px