Comment on page
Delivery methods
The Nimble SERP API supports three delivery methods:
- Real-time - the collected data is returned immediately to the user.
- Cloud Storage - the collected data is delivered to your preferred cloud storage repository.
- Push/Pull - the collected data is stored on Nimble's servers, and can be downloaded via a provided URL.
For real-time delivery, see our page on performing a real-time search request. To use Cloud or Push/Pull delivery, use an asynchronous request instead. Asynchronous requests also have the added benefit of running in the background, so you can continue working without waiting for the job to complete.
To send an asynchronous request, use the /async/serp endpoint with the following syntax:
Nimble APIs requires that a base64 encoded credential string be sent with every request to authenticate your account. For detailed examples, see SERP API Authentication.
cURL
Python
Node.js
Go
curl -X POST 'https://api.webit.live/api/v1/async/serp' \
--header 'Authorization: Basic <credential string>' \
--header 'Content-Type: application/json' \
--data-raw '{
"search_engine": "google_search",
"country": "FR",
"locale": "fr",
"query": "Sample search phrase",
"storage_type": "s3",
"storage_url": "s3://sample-bucket",
"callback_url": "https://my.callback/path"
}'
import requests
url = 'https://api.webit.live/api/v1/async/serp'
headers = {
'Authorization': 'Basic <credential string>',
'Content-Type': 'application/json'
}
data = {
"search_engine": "google_search",
"country": "FR",
"locale": "fr",
"query": "Sample search phrase",
"storage_type": "s3",
"storage_url": "s3://sample-bucket",
"callback_url": "https://my.callback/path"
}
response = requests.post(url, headers=headers, json=data)
print(response.status_code)
print(response.json())
const axios = require('axios');
const url = 'https://api.webit.live/api/v1/async/serp';
const headers = {
'Authorization': 'Basic <credential string>',
'Content-Type': 'application/json'
};
const data = {
"search_engine": "google_search",
"country": "FR",
"locale": "fr",
"query": "Sample search phrase",
"storage_type": "s3",
"storage_url": "s3://sample-bucket",
"callback_url": "https://my.callback/path"
};
axios.post(url, data, { headers })
.then(response => {
console.log(response.status);
console.log(response.data);
})
.catch(error => {
console.error(error);
});
package main
import (
"bytes"
"fmt"
"net/http"
"encoding/json"
)
func main() {
url := "https://api.webit.live/api/v1/async/serp"
payload := []byte(`{
"search_engine": "google_search",
"country": "FR",
"locale": "fr",
"query": "Sample search phrase",
"storage_type": "s3",
"storage_url": "s3://sample-bucket",
"callback_url": "https://my.callback/path"
}`)
headers := map[string]string{
"Authorization": "Basic <credential string>",
"Content-Type": "application/json",
}
req, err := http.NewRequest("POST", url, bytes.NewBuffer(payload))
if err != nil {
fmt.Println(err)
return
}
for key, value := range headers {
req.Header.Set(key, value)
}
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
fmt.Println(err)
return
}
defer resp.Body.Close()
fmt.Println(resp.StatusCode)
// Read the response body if needed
// body, err := ioutil.ReadAll(resp.Body)
// fmt.Println(string(body))
}
Asynchronous requests share the same parameters as real-time requests, but also include storage and callback parameters.
Parameter | Required | Type | Description |
---|---|---|---|
query | Required | String | The term or phrase to search for. |
search_engine | Required | Enum: google_search | bing_search | yandex_search | The search engine from which to collect results. |
domain | Optional | String | Search through a custom top-level domain of Google. eg: "co.uk" |
country | Optional (default = all) | String | Country used to access the target URL, use ISO Alpha-2 Country Codes i.e. US, DE, GB |
locale | Optional (default = en) | String | LCID standard locale used for the URL request. |
location | Optional | String | Search Google through a custom geolocation, regardless of country or proxy location. eg: "London,Ohio,United States". See Getting local data for more information. |
parse | Optional (default = true) | Enum: true | false | Instructs Nimble whether to structure the results into a JSON format or return the raw HTML. |
storage_type | Required | ENUM: s3 | gs | Use s3 for Amazon S3 and gs for Google Cloud Platform |
storage_url | Required | String | Repository URL: s3://Your.Bucket.Name/your/object/name/prefix/ | Output will be saved to TASK_ID.json |
callback_url | Optional | String | A url to callback once the data is delivered. Nimble APIs will send a POST request to the callback_url with the task details once the task is complete (this “notification” will not include the requested data). |
In order to use Google Cloud Storage as your destination repository, please add Nimble’s system user as a principal to the relevant bucket. To do so, navigate to the “bucket details” page in your GCP console, and click on “Permission” in the submenu.

Next, past our system user [email protected] into the “New Principals” box, select Storage Object Creator as the role, and click save.