Common parameters
Every request parameter the SerpKite search endpoints accept, with types, defaults and allowed values, grouped by what they control.
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/place and /v1/reviews take place_id (or cid, fid) instead of q, and /v1/webpage takes url.
All parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
q required | string | The search query. Required. Up to 2,048 characters. | |
country | string | us | Country to search from, as a two-letter ISO code (us, gb, de, in…). Defaults to the country a location ends in. |
language | string | en | Interface language, as a language code with an optional region (en, de, pt-BR, zh-TW…). |
location | string | Canonical location for local results, e.g. "Austin, Texas, United States". Ending in a country name also sets country. | |
uule | string | Google-encoded location string. Use instead of location if you already have it. | |
ll | string | Maps and places: search the map at a point and zoom, as "@lat,lng,zoomz", e.g. "@52.52,13.40,14z" (zoom defaults to 14z), wherever the request comes from. Overrides location. | |
num | integer | 10 | Results per call, 1–100. Up to 10 returns one page of 10 (1 credit); above 10 on search and news fetches whole pages as a depth bundle, and 100 costs 7 credits instead of 10. On images a page holds up to 100 images and num (default all) is how many of them come back. |
page | integer | 1 | Results page, 1–10. Each page is billed separately. |
time | string | Restrict to recent results. Shorthand for tbs=qdr:*. One of: hour, day, week, month, year. |
|
tbs | string | Raw Google tbs filter, e.g. qdr:w2 or cdr:1,cd_min:1/1/2026,cd_max:1/31/2026. Overrides time. | |
device | string | desktop | Which SERP layout to fetch. One of: desktop, mobile. |
safe | string | off | SafeSearch filtering. One of: off, active. |
autocorrect | boolean | true | Let Google correct misspelled queries. Set false to search the exact text. |
format | string | json | Response format. markdown is LLM-ready prose; compact is JSON with only the fields agents need. One of: json, compact, markdown. |
fields | string | Comma-separated projection, e.g. results.title,results.link,knowledge_graph. Cuts tokens. | |
include_content | integer | 0 | Also fetch the top N result pages (0–5) as Markdown. +1 credit per page. |
ads | boolean | false | Include sponsored results in ads. |
max_age | integer | Accept a cached result up to this many seconds old. Cache hits cost 50% of the credits. | |
engine | string or array | google | Which search providers may answer. google is Google only (SerpKite still retries Google internally); auto falls back to other providers when Google is blocked or times out; consensus (search only) asks several independent indexes in parallel, merges the results by URL, ranks them by agreement and lists each result's sources, at the sum of one page per provider that returned results; a provider name or a list (e.g. google,brave) restricts the request to those. meta.engine names the provider that answered. One of: google, auto, consensus, brave, bing, yahoo, duckduckgo, mojeek, wikipedia, yandex. |
place_id | string | Place and reviews: Google place ID (from maps/places results). Or pass cid or fid instead. | |
cid | string | Place and reviews: Google customer ID of the place (decimal). | |
fid | string | Place and reviews: Google feature ID of the place ("0x…:0x…"). | |
oid | string | Place: Yandex Maps organisation ID (digits, the number in yandex.ru/maps/org/…/<oid>/). Implies engine=yandex; not combined with place_id, cid or fid. | |
sort | string | most_relevant | Reviews: sort order. Only most_relevant is served: Google shows other orders only to signed-in visitors, so they return 400 (not charged). One of: most_relevant, newest, highest_rating, lowest_rating. |
page_token | string | Reviews: next_page_token from the previous page, unchanged (bound to the place and sort). Paging reaches the first 10 reviews of a place (what Google shows logged-out visitors). | |
url | string | Webpage: page URL to fetch. | |
include_html | boolean | false | Webpage: also return the raw HTML. |
domain | string | Rank: domain to find, e.g. example.com (subdomains match). | |
include_links | boolean | false | Webpage: also return the page's outbound links (url, text). |
include_images | boolean | false | Webpage: also return the page's image URLs. Shopping: data: thumbnails on cards with no image URL. |
include_domains | string[] | Only results from these sources, up to 20: a domain (example.com, subdomains match), a path prefix (github.com/org) or a TLD (.gov). Compiled to site: operators and enforced on the results. Search, news, images, videos. | |
exclude_domains | string[] | Drop results from these sources, up to 20, same formats as include_domains. Search, news, images, videos. | |
boost_domains | string[] | Move results from these sources to the top without filtering out the rest, up to 20. Search and news. | |
start_date | string | Only results published on or after this date (YYYY-MM-DD). Google's custom date range; can't be combined with time or tbs. | |
end_date | string | Only results published on or before this date (YYYY-MM-DD). | |
highlights | boolean | false | With include_content: return up to 3 query-ranked passages (~600 characters each) per fetched page in results[].highlights instead of the whole page. No extra credits. |
include_answer | boolean | false | Add a short answer written by Claude over the results, with [n] citations, in answer.text and answer.citations. +2 credits (+4 with include_content, when it reads the pages), refunded (with a meta.warnings entry) when the model fails. Search and news. |
ll (a map point and zoom) applies only to /v1/maps and /v1/places. 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"
}
}| If you send | Use instead |
|---|---|
gl |
country |
hl |
language |
placeId |
place_id |
sortBy |
sort |
nextPageToken |
page_token |
mode |
POST /v1/batches |
type |
The endpoint path, e.g. /v1/news instead of "type": "news" |
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.
| Parameter | Type | Default | Description |
|---|---|---|---|
q required | string | The search query. Required. Up to 2,048 characters. |
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.
| Parameter | Type | Default | Description |
|---|---|---|---|
country | string | us | Country to search from, as a two-letter ISO code (us, gb, de, in…). Defaults to the country a location ends in. |
language | string | en | Interface language, as a language code with an optional region (en, de, pt-BR, zh-TW…). |
location | string | Canonical location for local results, e.g. "Austin, Texas, United States". Ending in a country name also sets country. | |
uule | string | Google-encoded location string. Use instead of location if you already have it. | |
ll | string | Maps and places: search the map at a point and zoom, as "@lat,lng,zoomz", e.g. "@52.52,13.40,14z" (zoom defaults to 14z), wherever the request comes from. Overrides location. |
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.
| Parameter | Type | Default | Description |
|---|---|---|---|
num | integer | 10 | Results per call, 1–100. Up to 10 returns one page of 10 (1 credit); above 10 on search and news fetches whole pages as a depth bundle, and 100 costs 7 credits instead of 10. On images a page holds up to 100 images and num (default all) is how many of them come back. |
page | integer | 1 | Results page, 1–10. Each page is billed separately. |
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.
| Parameter | Type | Default | Description |
|---|---|---|---|
time | string | Restrict to recent results. Shorthand for tbs=qdr:*. One of: hour, day, week, month, year. |
|
tbs | string | Raw Google tbs filter, e.g. qdr:w2 or cdr:1,cd_min:1/1/2026,cd_max:1/31/2026. Overrides time. | |
device | string | desktop | Which SERP layout to fetch. One of: desktop, mobile. |
safe | string | off | SafeSearch filtering. One of: off, active. |
autocorrect | boolean | true | Let Google correct misspelled queries. Set false to search the exact text. |
time |
Equivalent tbs |
|---|---|
hour |
qdr:h |
day |
qdr:d |
week |
qdr:w |
month |
qdr:m |
year |
qdr:y |
A custom date range is easiest with start_date and end_date (YYYY-MM-DD), which build that tbs for you; raw tbs such as cdr:1,cd_min:1/1/2026,cd_max:3/31/2026 works too.
time works on search, news, images, videos and shopping; scholar, maps, places, patents and autocomplete reject it with a 400 instead of returning unfiltered results. When a request falls back from Google to another engine (engine), the time window goes along: an engine without that window (Bing web search has no past hour, Yahoo no past year) is skipped rather than answering unfiltered. With an explicit engine=bing that combination is a 400.
Domain filters (include_domains, exclude_domains, boost_domains) and the date range are described in Search filters.
| Parameter | Type | Default | Description |
|---|---|---|---|
include_domains | string[] | Only results from these sources, up to 20: a domain (example.com, subdomains match), a path prefix (github.com/org) or a TLD (.gov). Compiled to site: operators and enforced on the results. Search, news, images, videos. | |
exclude_domains | string[] | Drop results from these sources, up to 20, same formats as include_domains. Search, news, images, videos. | |
boost_domains | string[] | Move results from these sources to the top without filtering out the rest, up to 20. Search and news. | |
start_date | string | Only results published on or after this date (YYYY-MM-DD). Google's custom date range; can't be combined with time or tbs. | |
end_date | string | Only results published on or before this date (YYYY-MM-DD). |
Output
These parameters change the shape and size of the response, not the search itself. See Output formats and Page content.
| Parameter | Type | Default | Description |
|---|---|---|---|
format | string | json | Response format. markdown is LLM-ready prose; compact is JSON with only the fields agents need. One of: json, compact, markdown. |
fields | string | Comma-separated projection, e.g. results.title,results.link,knowledge_graph. Cuts tokens. | |
include_content | integer | 0 | Also fetch the top N result pages (0–5) as Markdown. +1 credit per page. |
highlights | boolean | false | With include_content: return up to 3 query-ranked passages (~600 characters each) per fetched page in results[].highlights instead of the whole page. No extra credits. |
ads | boolean | false | Include sponsored results in ads. |
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.
| Parameter | Type | Default | Description |
|---|---|---|---|
max_age | integer | Accept a cached result up to this many seconds old. Cache hits cost 50% of the credits. | |
engine | string or array | google | Which search providers may answer. google is Google only (SerpKite still retries Google internally); auto falls back to other providers when Google is blocked or times out; consensus (search only) asks several independent indexes in parallel, merges the results by URL, ranks them by agreement and lists each result's sources, at the sum of one page per provider that returned results; a provider name or a list (e.g. google,brave) restricts the request to those. meta.engine names the provider that answered. One of: google, auto, consensus, brave, bing, yahoo, duckduckgo, mojeek, wikipedia, yandex. |
Place, Reviews and Webpage
These endpoints take an identifier or URL instead of q. /v1/place and /v1/reviews need one of place_id, cid or fid, taken from a maps or places result. Reviews page with a cursor: pass next_page_token from the previous response as page_token. See Pagination and depth.
| Parameter | Type | Default | Description |
|---|---|---|---|
place_id | string | Place and reviews: Google place ID (from maps/places results). Or pass cid or fid instead. | |
cid | string | Place and reviews: Google customer ID of the place (decimal). | |
fid | string | Place and reviews: Google feature ID of the place ("0x…:0x…"). | |
sort | string | most_relevant | Reviews: sort order. Only most_relevant is served: Google shows other orders only to signed-in visitors, so they return 400 (not charged). One of: most_relevant, newest, highest_rating, lowest_rating. |
page_token | string | Reviews: next_page_token from the previous page, unchanged (bound to the place and sort). Paging reaches the first 10 reviews of a place (what Google shows logged-out visitors). | |
url | string | Webpage: page URL to fetch. | |
include_html | boolean | false | Webpage: also return the raw HTML. |
include_links | boolean | false | Webpage: also return the page's outbound links (url, text). |
include_images | boolean | false | Webpage: also return the page's image URLs. Shopping: data: thumbnails on cards with no image URL. |
Which endpoint takes what
Each endpoint page lists exactly the parameters it supports:
| Endpoint | Method and path | Credits | Returns |
|---|---|---|---|
| Google Search | POST /v1/search | 1 | request, results, answer_box, ai_overview, knowledge_graph, people_also_ask, related_searches, top_stories, places, ads, meta |
| Google News | POST /v1/news | 1 | request, results, meta |
| Google Images | POST /v1/images | 1 | request, results, meta |
| Google Videos | POST /v1/videos | 1 | request, results, meta |
| Google Maps | POST /v1/maps | 1 | request, results, meta |
| Google Places | POST /v1/places | 1 | request, results, meta |
| Google Place Details | POST /v1/place | 1 | request, results, meta |
| Google Reviews | POST /v1/reviews | 1 | request, results, next_page_token, meta |
| Google Shopping | POST /v1/shopping | 1 | request, results, meta |
| Google Scholar | POST /v1/scholar | 1 | request, results, meta |
| Google Patents | POST /v1/patents | 1 | request, results, meta |
| Google Autocomplete | POST /v1/autocomplete | 0.5 | request, results, meta |
| Webpage to Markdown | POST /v1/webpage | 1 | request, url, status_code, markdown, text, metadata, meta |
| Custom Search (CSE-compatible) | GET /customsearch/v1 | 1 | kind, searchInformation, items, queries |
| Answer | POST /v1/answer | 3–10 | answer, citations, results |
| Extract | POST /v1/extract | 1 | results |
| Map | POST /v1/map | 1 | results |
| Crawl | POST /v1/crawl | 1 | a task (202, poll or webhook) |
| Research | POST /v1/research | 30–200 | a task (202, poll or webhook) |
| Monitors | POST /v1/monitors | 1 | results |
| ChatGPT | POST /v1/chatgpt | 4 | text, markdown, sources, search_queries, products, mentions |
| Gemini | POST /v1/gemini | 3 | text, markdown, sources, search_queries, products, mentions |
| Copilot Search | POST /v1/copilot | 3 | text, markdown, sources, search_queries, products, mentions |
| Google AI Mode | POST /v1/ai_mode | 2 | text, markdown, sources, search_queries, products, mentions |
| Brave AI | POST /v1/brave_ai | 2 | text, markdown, sources, search_queries, products, mentions |
Last updated: 2026-10-21