SERP Async

curl --request POST \
  --url https://sdk.nimbleway.com/v2/serp/async \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "search_engine": "google_search",
  "country": "US",
  "device": "desktop",
  "domain": "com",
  "locale": "en",
  "location": "New York, New York, United States",
  "num_results": 10,
  "page": 1,
  "parse": true,
  "query": "nimble web data",
  "render": false,
  "resolve_url": false,
  "show_hidden_results": false,
  "callback_url": "https://example.com/webhook/callback",
  "storage_compress": true,
  "storage_object_name": "result-2024-01-15.json",
  "storage_type": "s3",
  "storage_url": "s3://bucket-name/path/to/object"
}
'

import requests

url = "https://sdk.nimbleway.com/v2/serp/async"

payload = {
    "search_engine": "google_search",
    "country": "US",
    "device": "desktop",
    "domain": "com",
    "locale": "en",
    "location": "New York, New York, United States",
    "num_results": 10,
    "page": 1,
    "parse": True,
    "query": "nimble web data",
    "render": False,
    "resolve_url": False,
    "show_hidden_results": False,
    "callback_url": "https://example.com/webhook/callback",
    "storage_compress": True,
    "storage_object_name": "result-2024-01-15.json",
    "storage_type": "s3",
    "storage_url": "s3://bucket-name/path/to/object"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    search_engine: 'google_search',
    country: 'US',
    device: 'desktop',
    domain: 'com',
    locale: 'en',
    location: 'New York, New York, United States',
    num_results: 10,
    page: 1,
    parse: true,
    query: 'nimble web data',
    render: false,
    resolve_url: false,
    show_hidden_results: false,
    callback_url: 'https://example.com/webhook/callback',
    storage_compress: true,
    storage_object_name: 'result-2024-01-15.json',
    storage_type: 's3',
    storage_url: 's3://bucket-name/path/to/object'
  })
};

fetch('https://sdk.nimbleway.com/v2/serp/async', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://sdk.nimbleway.com/v2/serp/async",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'search_engine' => 'google_search',
    'country' => 'US',
    'device' => 'desktop',
    'domain' => 'com',
    'locale' => 'en',
    'location' => 'New York, New York, United States',
    'num_results' => 10,
    'page' => 1,
    'parse' => true,
    'query' => 'nimble web data',
    'render' => false,
    'resolve_url' => false,
    'show_hidden_results' => false,
    'callback_url' => 'https://example.com/webhook/callback',
    'storage_compress' => true,
    'storage_object_name' => 'result-2024-01-15.json',
    'storage_type' => 's3',
    'storage_url' => 's3://bucket-name/path/to/object'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://sdk.nimbleway.com/v2/serp/async"

	payload := strings.NewReader("{\n  \"search_engine\": \"google_search\",\n  \"country\": \"US\",\n  \"device\": \"desktop\",\n  \"domain\": \"com\",\n  \"locale\": \"en\",\n  \"location\": \"New York, New York, United States\",\n  \"num_results\": 10,\n  \"page\": 1,\n  \"parse\": true,\n  \"query\": \"nimble web data\",\n  \"render\": false,\n  \"resolve_url\": false,\n  \"show_hidden_results\": false,\n  \"callback_url\": \"https://example.com/webhook/callback\",\n  \"storage_compress\": true,\n  \"storage_object_name\": \"result-2024-01-15.json\",\n  \"storage_type\": \"s3\",\n  \"storage_url\": \"s3://bucket-name/path/to/object\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://sdk.nimbleway.com/v2/serp/async")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"search_engine\": \"google_search\",\n  \"country\": \"US\",\n  \"device\": \"desktop\",\n  \"domain\": \"com\",\n  \"locale\": \"en\",\n  \"location\": \"New York, New York, United States\",\n  \"num_results\": 10,\n  \"page\": 1,\n  \"parse\": true,\n  \"query\": \"nimble web data\",\n  \"render\": false,\n  \"resolve_url\": false,\n  \"show_hidden_results\": false,\n  \"callback_url\": \"https://example.com/webhook/callback\",\n  \"storage_compress\": true,\n  \"storage_object_name\": \"result-2024-01-15.json\",\n  \"storage_type\": \"s3\",\n  \"storage_url\": \"s3://bucket-name/path/to/object\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://sdk.nimbleway.com/v2/serp/async")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"search_engine\": \"google_search\",\n  \"country\": \"US\",\n  \"device\": \"desktop\",\n  \"domain\": \"com\",\n  \"locale\": \"en\",\n  \"location\": \"New York, New York, United States\",\n  \"num_results\": 10,\n  \"page\": 1,\n  \"parse\": true,\n  \"query\": \"nimble web data\",\n  \"render\": false,\n  \"resolve_url\": false,\n  \"show_hidden_results\": false,\n  \"callback_url\": \"https://example.com/webhook/callback\",\n  \"storage_compress\": true,\n  \"storage_object_name\": \"result-2024-01-15.json\",\n  \"storage_type\": \"s3\",\n  \"storage_url\": \"s3://bucket-name/path/to/object\"\n}"

response = http.request(request)
puts response.read_body

{
  "status": "success",
  "task": {
    "_query": "<unknown>",
    "created_at": "2024-01-15T10:30:00Z",
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "input": "<unknown>",
    "state": "pending",
    "status_url": "https://api.webit.live/api/v2/tasks/123e4567-e89b-12d3-a456-426614174000",
    "account_name": "<string>",
    "api_type": "web",
    "batch_id": "4b0a90bf-c951-42e4-95b3-a95a65ba69fc",
    "download_url": "https://api.webit.live/api/v2/tasks/123e4567-e89b-12d3-a456-426614174000/results",
    "error": "Connection timeout",
    "error_type": "timeout_error",
    "modified_at": "2024-01-15T10:35:00Z",
    "output_url": "<string>",
    "queue": "<string>",
    "status_code": 200
  }
}

POST

serp

async

SERP Async

curl --request POST \
  --url https://sdk.nimbleway.com/v2/serp/async \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "search_engine": "google_search",
  "country": "US",
  "device": "desktop",
  "domain": "com",
  "locale": "en",
  "location": "New York, New York, United States",
  "num_results": 10,
  "page": 1,
  "parse": true,
  "query": "nimble web data",
  "render": false,
  "resolve_url": false,
  "show_hidden_results": false,
  "callback_url": "https://example.com/webhook/callback",
  "storage_compress": true,
  "storage_object_name": "result-2024-01-15.json",
  "storage_type": "s3",
  "storage_url": "s3://bucket-name/path/to/object"
}
'

import requests

url = "https://sdk.nimbleway.com/v2/serp/async"

payload = {
    "search_engine": "google_search",
    "country": "US",
    "device": "desktop",
    "domain": "com",
    "locale": "en",
    "location": "New York, New York, United States",
    "num_results": 10,
    "page": 1,
    "parse": True,
    "query": "nimble web data",
    "render": False,
    "resolve_url": False,
    "show_hidden_results": False,
    "callback_url": "https://example.com/webhook/callback",
    "storage_compress": True,
    "storage_object_name": "result-2024-01-15.json",
    "storage_type": "s3",
    "storage_url": "s3://bucket-name/path/to/object"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    search_engine: 'google_search',
    country: 'US',
    device: 'desktop',
    domain: 'com',
    locale: 'en',
    location: 'New York, New York, United States',
    num_results: 10,
    page: 1,
    parse: true,
    query: 'nimble web data',
    render: false,
    resolve_url: false,
    show_hidden_results: false,
    callback_url: 'https://example.com/webhook/callback',
    storage_compress: true,
    storage_object_name: 'result-2024-01-15.json',
    storage_type: 's3',
    storage_url: 's3://bucket-name/path/to/object'
  })
};

fetch('https://sdk.nimbleway.com/v2/serp/async', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://sdk.nimbleway.com/v2/serp/async",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'search_engine' => 'google_search',
    'country' => 'US',
    'device' => 'desktop',
    'domain' => 'com',
    'locale' => 'en',
    'location' => 'New York, New York, United States',
    'num_results' => 10,
    'page' => 1,
    'parse' => true,
    'query' => 'nimble web data',
    'render' => false,
    'resolve_url' => false,
    'show_hidden_results' => false,
    'callback_url' => 'https://example.com/webhook/callback',
    'storage_compress' => true,
    'storage_object_name' => 'result-2024-01-15.json',
    'storage_type' => 's3',
    'storage_url' => 's3://bucket-name/path/to/object'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://sdk.nimbleway.com/v2/serp/async"

	payload := strings.NewReader("{\n  \"search_engine\": \"google_search\",\n  \"country\": \"US\",\n  \"device\": \"desktop\",\n  \"domain\": \"com\",\n  \"locale\": \"en\",\n  \"location\": \"New York, New York, United States\",\n  \"num_results\": 10,\n  \"page\": 1,\n  \"parse\": true,\n  \"query\": \"nimble web data\",\n  \"render\": false,\n  \"resolve_url\": false,\n  \"show_hidden_results\": false,\n  \"callback_url\": \"https://example.com/webhook/callback\",\n  \"storage_compress\": true,\n  \"storage_object_name\": \"result-2024-01-15.json\",\n  \"storage_type\": \"s3\",\n  \"storage_url\": \"s3://bucket-name/path/to/object\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://sdk.nimbleway.com/v2/serp/async")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"search_engine\": \"google_search\",\n  \"country\": \"US\",\n  \"device\": \"desktop\",\n  \"domain\": \"com\",\n  \"locale\": \"en\",\n  \"location\": \"New York, New York, United States\",\n  \"num_results\": 10,\n  \"page\": 1,\n  \"parse\": true,\n  \"query\": \"nimble web data\",\n  \"render\": false,\n  \"resolve_url\": false,\n  \"show_hidden_results\": false,\n  \"callback_url\": \"https://example.com/webhook/callback\",\n  \"storage_compress\": true,\n  \"storage_object_name\": \"result-2024-01-15.json\",\n  \"storage_type\": \"s3\",\n  \"storage_url\": \"s3://bucket-name/path/to/object\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://sdk.nimbleway.com/v2/serp/async")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"search_engine\": \"google_search\",\n  \"country\": \"US\",\n  \"device\": \"desktop\",\n  \"domain\": \"com\",\n  \"locale\": \"en\",\n  \"location\": \"New York, New York, United States\",\n  \"num_results\": 10,\n  \"page\": 1,\n  \"parse\": true,\n  \"query\": \"nimble web data\",\n  \"render\": false,\n  \"resolve_url\": false,\n  \"show_hidden_results\": false,\n  \"callback_url\": \"https://example.com/webhook/callback\",\n  \"storage_compress\": true,\n  \"storage_object_name\": \"result-2024-01-15.json\",\n  \"storage_type\": \"s3\",\n  \"storage_url\": \"s3://bucket-name/path/to/object\"\n}"

response = http.request(request)
puts response.read_body

{
  "status": "success",
  "task": {
    "_query": "<unknown>",
    "created_at": "2024-01-15T10:30:00Z",
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "input": "<unknown>",
    "state": "pending",
    "status_url": "https://api.webit.live/api/v2/tasks/123e4567-e89b-12d3-a456-426614174000",
    "account_name": "<string>",
    "api_type": "web",
    "batch_id": "4b0a90bf-c951-42e4-95b3-a95a65ba69fc",
    "download_url": "https://api.webit.live/api/v2/tasks/123e4567-e89b-12d3-a456-426614174000/results",
    "error": "Connection timeout",
    "error_type": "timeout_error",
    "modified_at": "2024-01-15T10:35:00Z",
    "output_url": "<string>",
    "queue": "<string>",
    "status_code": 200
  }
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Request body model for the /serp endpoint

search_engine

enum<string>

required

The search engine to query.

Available options:

google_search,

google_sge,

google_aio,

google_maps_search,

google_maps_reviews,

google_maps_place,

google_news,

google_images,

bing_search,

yandex_search

Example:

"google_search"

country

string

ISO Alpha-2 country code used to access the target search engine (e.g. US, DE, GB).

Example:

"US"

device

enum<string>

Device type used for the search request.

Available options:

desktop,

mobile

Example:

"desktop"

domain

string

default:com

Top-level domain for the search engine (e.g. "com", "co.uk", "de").

Example:

"com"

locale

string

Locale used for the search request.

Example:

"en"

location

string

Geo-location for the search (canonical Google location name).

Example:

"New York, New York, United States"

num_results

integer

Number of results to return (1–100).

Required range: 1 <= x <= 100

Example:

10

page

integer

The result page number for pagination.

Required range: 1 <= x <= 9007199254740991

Example:

1

parse

boolean

default:true

When true, the SERP response is parsed into structured JSON.

Example:

true

query

string

The search keyword or phrase to query.

Example:

"nimble web data"

render

boolean

default:false

Whether to render the page in a browser before extracting.

Example:

false

resolve_url

boolean

default:false

Resolves redirect or broken URLs to their real destination. Adds a small increase in latency. If an individual result can't be resolved, that result falls back to the raw URL instead of failing the whole request.

Example:

false

show_hidden_results

boolean

When true, disables Google result filtering (filter=0) so omitted/duplicate and highly similar pages are also returned. Applies to Google search engines.

Example:

false

callback_url

string

URL to call back when async operation completes

Example:

"https://example.com/webhook/callback"

storage_compress

boolean

Whether to compress stored data

Example:

true

storage_object_name

string

Custom name for the stored object

Example:

"result-2024-01-15.json"

storage_type

string

Type of storage to use for results

Example:

"s3"

storage_url

string

URL for storage location

Example:

"s3://bucket-name/path/to/object"

Response

200 - application/json

Task created successfully

Response when an async SERP task is created successfully.

status

string

required

Status indicating the async SERP task was created successfully.

Allowed value: "success"

task

object

required

The created async task details.

Show child attributes

Search API

Agents API

Extract API

Extract Templates API

Map API

Crawl API

SERP API

Media API

Domain Knowledge API

Domain Health API

Jobs API

Tasks & Batches API

SERP Async

Authorizations

Body

Response