# 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/reviews`](https://serpkite.com/docs/endpoints/reviews) takes `place_id` (or `cid`, `fid`) instead of `q`, and [`/v1/lens`](https://serpkite.com/docs/endpoints/lens) and [`/v1/webpage`](https://serpkite.com/docs/endpoints/webpage) take `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…). |
| `language` | string | `en` | Interface language, as a language code (en, de, fr, pt-BR…). |
| `location` | string |  | Canonical location for local results, e.g. "Austin, Texas, United States". Overrides country for geo. |
| `uule` | string |  | Google-encoded location string. Use instead of location if you already have it. |
| `ll` | string |  | Maps only: viewport as "@lat,lng,zoom", e.g. "@52.52,13.40,14z". |
| `num` | integer | `10` | Results per call. 10 per page; 100 fetches the top 100 as a depth bundle for 7 credits instead of 10. One of: `10`, `20`, `30`, `50`, `100`. |
| `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:w or cdr:1,cd_min:… |
| `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 fails over across its own proxy pools); 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`. |
| `place_id` | string |  | Reviews: Google place ID (from maps/places results). Or pass cid or fid instead. |
| `cid` | string |  | Reviews: Google customer ID of the place. |
| `fid` | string |  | Reviews: Google feature ID of the place. |
| `sort` | string | `most_relevant` | Reviews: sort order. 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 100 reviews per sort order. |
| `url` | string |  | Lens: image URL. 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). |

`ll` (the map viewport) applies only to [/v1/maps](https://serpkite.com/docs/endpoints/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](https://serpkite.com/docs/providers).

## Sending parameters

The two requests below are equivalent:

POST (JSON):

```bash
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"}'
```

GET (query string):

```bash
curl "https://api.serpkite.com/v1/search?q=coffee+grinder&country=de&language=de&num=20&time=month" \
  -H "Authorization: Bearer $SERPKITE_API_KEY"
```

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`](https://serpkite.com/docs/batch) (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:

400 Bad Request:

```json
{
  "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`](https://serpkite.com/docs/batch) |
| `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](https://serpkite.com/docs/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…). |
| `language` | string | `en` | Interface language, as a language code (en, de, fr, pt-BR…). |
| `location` | string |  | Canonical location for local results, e.g. "Austin, Texas, United States". Overrides country for geo. |
| `uule` | string |  | Google-encoded location string. Use instead of location if you already have it. |
| `ll` | string |  | Maps only: viewport as "@lat,lng,zoom", e.g. "@52.52,13.40,14z". |

## 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](https://serpkite.com/docs/pagination-and-depth).

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `num` | integer | `10` | Results per call. 10 per page; 100 fetches the top 100 as a depth bundle for 7 credits instead of 10. One of: `10`, `20`, `30`, `50`, `100`. |
| `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:w or cdr:1,cd_min:… |
| `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 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](https://serpkite.com/docs/output-formats) and [Page content](https://serpkite.com/docs/include-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. |
| `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`](https://serpkite.com/docs/batch), also at half price, and get the results by polling or [webhook](https://serpkite.com/docs/webhooks). See [Caching](https://serpkite.com/docs/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 fails over across its own proxy pools); 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`. |

## 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](https://serpkite.com/docs/pagination-and-depth#paging-through-reviews).

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `place_id` | string |  | Reviews: Google place ID (from maps/places results). Or pass cid or fid instead. |
| `cid` | string |  | Reviews: Google customer ID of the place. |
| `fid` | string |  | Reviews: Google feature ID of the place. |
| `sort` | string | `most_relevant` | Reviews: sort order. 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 100 reviews per sort order. |
| `url` | string |  | Lens: image URL. Webpage: page URL to fetch. |
| `include_html` | boolean | `false` | Webpage: also return the raw HTML. |

## Which endpoint takes what

Each endpoint page lists exactly the parameters it supports:

| Endpoint | Method and path | Credits | Returns |
| --- | --- | --- | --- |
| [Google Search](https://serpkite.com/docs/endpoints/search) | `POST /v1/search` | 1 | `request`, `results`, `answer_box`, `knowledge_graph`, `people_also_ask`, `related_searches`, `top_stories`, `places`, `ads`, `meta` |
| [Google News](https://serpkite.com/docs/endpoints/news) | `POST /v1/news` | 1 | `request`, `results`, `meta` |
| [Google Images](https://serpkite.com/docs/endpoints/images) | `POST /v1/images` | 1 | `request`, `results`, `meta` |
| [Google Videos](https://serpkite.com/docs/endpoints/videos) | `POST /v1/videos` | 1 | `request`, `results`, `meta` |
| [Google Maps](https://serpkite.com/docs/endpoints/maps) | `POST /v1/maps` | 1 | `request`, `results`, `meta` |
| [Google Places](https://serpkite.com/docs/endpoints/places) | `POST /v1/places` | 1 | `request`, `results`, `meta` |
| [Google Reviews](https://serpkite.com/docs/endpoints/reviews) | `POST /v1/reviews` | 1 | `request`, `results`, `next_page_token`, `meta` |
| [Google Shopping](https://serpkite.com/docs/endpoints/shopping) | `POST /v1/shopping` | 1 | `request`, `results`, `meta` |
| [Google Scholar](https://serpkite.com/docs/endpoints/scholar) | `POST /v1/scholar` | 1 | `request`, `results`, `meta` |
| [Google Patents](https://serpkite.com/docs/endpoints/patents) | `POST /v1/patents` | 1 | `request`, `results`, `meta` |
| [Google Autocomplete](https://serpkite.com/docs/endpoints/autocomplete) | `POST /v1/autocomplete` | 0.5 | `request`, `results`, `meta` |
| [Google Lens](https://serpkite.com/docs/endpoints/lens) | `POST /v1/lens` | 2 | `request`, `results`, `meta` |
| [Webpage to Markdown](https://serpkite.com/docs/endpoints/webpage) | `POST /v1/webpage` | 1 | `request`, `url`, `status_code`, `markdown`, `text`, `metadata`, `meta` |
| [Custom Search (CSE-compatible)](https://serpkite.com/docs/endpoints/customsearch) | `GET /customsearch/v1` | 1 | `kind`, `searchInformation`, `items`, `queries` |