In this article, we'll explain the difference between sync and async requests, highlight the benefits of async API, and describe key parameters with examples.
How to send Asynchronous requests to a SERP API zone
There are 2 ways for us to handle your SERP API requests:
- Synchronous requests (default) - you send a request and get the response on demand within a few seconds
- Asynchronous requests - you send a request without waiting for the full response. A 'response ID' is returned immediately and we take care of the request behind the scenes, allowing you to collect your responses at a later more convenient time via a designated endpoint API command or webhook. We store responses for up to 48 hours from the time the request was sent.
Recommended for: those with high-volume requests as this mode has the best stability, flexibility, and 99.99% success rate.
Why to use Async:
- 99.99% success rate
- Stability
- Flexibility - the ability to retrieve your requests at a later time of your choosing (and not have to wait for the response immediately after sending the request)
- Most results come back within a few minutes
How to use Async:
- Enable Asynchronous requests within your SERP API zone
- Set up a webhook with POST or GET or alternatively, you can fetch the results manually (see the example below)
- Send a SERP API request
Note: The request syntax is slightly different from that of synchronous requests and requires an API token for authentication. See the example below:
curl -i --silent --compressed "https://api.brightdata.com/serp/req?customer=[ACCOUNT_ID]&zone=[ZONE_NAME]" -H "Content-Type: application/json" -H "Authorization: Bearer [API_TOKEN]" -d "{\"country\":\"us\",\"query\":{\"q\":\"pizza\",\"num\":\"100\",\"hl\":\"en\",\"gl\":\"au\"}}"The `x-response-id` header will contain the ID of the request. Use it in the collection request
- Collect the results via your webhook OR collect them manually like below:
curl -v --compressed "https://api.brightdata.com/serp/get_result?customer=[ACCOUNT_ID]&zone=[ZONE_NAME]&response_id=${[RESPONSE_ID]}" -H "Authorization: Bearer [API_TOKEN]"
Init job parameters overview
- url (optional): Defines the URL to which the request will be made. For Google SERP requests can be omitted.
- country (optional): Defines the country for peer. In Google SERP requests define the google domain, based on the country specified.
- webhook_url (optional): Defines the URL to which job status notification will be sent.
- webhook_method (optional): Defines the method with which job status notification will be delivered. Defaults to “GET”
- webhook_data (optional): Defines the data that will be sent with job status notification
- query (optional): Defines the query object for the request. Consists of query parameters for SERP requests. Learn more
- output (optional): could be one of the following: json, json_html. Defines the request output format. Learn more
- note: "query.brd_json" could be used instead of this parameter
Collect results parameters overview
- Response_id (mandatory): Defines the job id. (Received in init job request response)
How to run multiple ASYNC requests from the same IP and session
SERP API allows you to send 2 parallel requests with one API code.
These parallel requests use the same peer IP and session and can be used for collecting additional data, comparison tests, etc. – e.g., making a pair of requests with different parameters/values.
This feature is:
- Supported only for a zone with asynchronous requests enabled
- Supported only for Google Search
- Limited to 2 requests
- Billed as 2 requests
To run multiple requests, use the “multi” parameter with async requests code syntax.
Examples:
- Multiple requests with the same keyword but a different num parameter:
multi:[{"keyword":"pizza","num":20},{"keyword":"pizza","num":100}] - Multiple requests with different keywords:
multi:[{"keyword":"pizza"},{"keyword":"burger"}]
Step 1: Send a request – Shell example (get response ID):
curl -v --compressed "https://brightdata.com/api/serp/req" -H "Content-Type: application/json" -H "Authorization: Bearer {API_TOKEN}" -d "{\"country\":\"us\",\"multi\":[{\"keyword\":\"pizza\",\"num\":20},{\"keyword\":\"pizza\",\"num\":100}]}"
Step 2: Collect the result – Shell example (use the response ID to collect the result):
curl -k -v --compressed "https://brightdata.com/api/serp/get_result?customer={ACCOUNT_ID&zone={ASYNC_ZONE}&output={output_fomat_html/json}&response_id={response_id}" -H "Authorization: Bearer {API_Token}" -o {Your_result_ouput_file}
Categories