Common parameters

All search endpoints under /v1 share one parameter set, with snake_case names. You send it as a JSON object on POST, or as a query string on GET with the same names. Only q is required. Each endpoint’s reference page lists exactly the parameters it accepts; for example /v1/reviews takes place_id (or cid, fid) instead of q, and /v1/lens and /v1/webpage take url.

All parameters

ll (the map viewport) applies only to /v1/maps. engine defaults to google (Google only); auto, a single provider or a list allows fallback engines on search, news, images and videos. See Search providers.

Sending parameters

The two requests below are equivalent:

curl https://api.serpkite.com/v1/search \
  -H "Authorization: Bearer $SERPKITE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q":"coffee grinder","country":"de","language":"de","num":20,"time":"month"}'

Numbers and booleans are accepted either as JSON numbers and booleans or as strings ("num": "20", "autocorrect": "false"), so query strings and loosely typed clients both work. Invalid values return 400 invalid_request with a message naming the parameter, and are never billed.

The body must be a single JSON object. To run many queries at once, queue them with POST /v1/batches (up to 100 per call, at half price).

Strict validation

Unknown parameters are rejected, never silently ignored, so a typo can’t quietly fall back to a default (a misspelled country would otherwise search from the US). The API answers 400 invalid_request, names the parameter and, when it recognises a name used by other SERP APIs, tells you the replacement:

{
  "error": {
    "code": "invalid_request",
    "message": "unknown parameter \"gl\": use country",
    "request_id": "req_01J8ZK9W3HC2D"
  }
}

A JSON array body is rejected the same way (body must be a JSON object; to run many queries use POST /v1/batches). None of these errors is billed.

Query

q is the search query, 1 to 2,048 characters. Google operators work as they do on google.com: site:, -exclude, "exact phrase", filetype:, intitle: and so on.

Location and language

country picks the country Google searches from and language the interface language. location narrows results to a city or region, which matters for local packs, maps and anything with local intent. uule is the pre-encoded form of a location if you already have one. See Localization for the full list of codes and how they interact.

Paging and depth

page walks through result pages, one credit each. num above 10 fetches deeper results in one call on /v1/search and /v1/news, and num=100 is a bundle of 10 pages for 7 credits. See Pagination and depth.

Filters

time is a friendly shorthand for recency. tbs passes Google’s raw filter string through when you need something time doesn’t cover, like a custom date range. If you send both, tbs wins.

A custom date range uses tbs directly, for example cdr:1,cd_min:1/1/2026,cd_max:3/31/2026.

Output

These parameters change the shape and size of the response, not the search itself. See Output formats and Page content.

Cost and delivery

max_age lets you accept a recent cached result for half the credits. For work that doesn’t need an answer right now, send the same request bodies to POST /v1/batches, also at half price, and get the results by polling or webhook. See Caching.

Reviews, Lens and Webpage

These endpoints take an identifier or URL instead of q. Reviews page with a cursor: pass next_page_token from the previous response as page_token. See Pagination and depth.

Which endpoint takes what

Each endpoint page lists exactly the parameters it supports: