SERP API overview

The native SERP API returns real-time Google Search results as clean JSON. It runs live (synchronous) or async (task-based) over the same engine.

Endpoints

Method	Path	Purpose
POST	/v1/serp/search	Live SERP — one request, one result, inline
POST	/v1/serp/tasks	Enqueue an async task
GET	/v1/serp/tasks	List your completed (ready) tasks
GET	/v1/serp/tasks/{id}	Fetch a task’s result
GET	/v1/serp/track	Rank-over-time for a tracked target
GET	/v1/locations	Supported locations
GET	/v1/locations/{country}	Locations for one ISO country
GET	/v1/languages	Supported languages

All endpoints require authentication.

Request shape

POST /v1/serp/search and POST /v1/serp/tasks share the same request body:

Field	Type	Required	Default	Notes
keyword	string	yes	—	1–700 chars. The search query.
location	object	yes	—	One of code, name, or coordinate.
language	object	yes	—	One of code or name.
device	desktop | mobile	no	desktop
os	windows | macos | android | ios	no	windows
depth	integer	no	100	Results to return, 10–700.
format	standard | advanced | html	no	advanced	Response detail.
search_engine_domain	string	no	google.com	e.g. google.co.uk.
url	string	no	—	Pre-built Google URL; overrides keyword/location/device.
stop_on_match	array	no	—	Stop crawling once a target is matched.
track	object	no	—	Rank tracking — { target, label? }.
webhook	object	no	—	Async webhooks (tasks only).
priority	standard | priority	no	standard	priority jumps the queue.
tag	string	no	—	Free-form label echoed back.

location

{ "code": 2840 }                              // by numeric code (recommended)
{ "name": "London,England,United Kingdom" }   // by canonical name
{ "coordinate": "51.5074,-0.1278,10" }        // lat,lng,radius(km)

language

{ "code": "en" }        // ISO code (recommended)
{ "name": "English" }   // human name

Look up valid values via /v1/locations and /v1/languages.

Response envelope

Every successful native response uses the same envelope:

{
  "request_id": "req_…",
  "status": "ok",
  "meta": { "api_version": "0.1.0", "time": 1.13, "cost": 0.005, "currency": "USD" },
  "data": { /* endpoint-specific payload */ }
}

Field	Meaning
request_id	Correlation id — echo to support.
status	ok (data present) or accepted (async task still processing).
meta.time	Server processing time (seconds).
meta.cost	Amount drawn from your balance (USD).
data	The result — shape depends on the endpoint and format.

Errors use a different shape — see Errors.