---
title: "Google local results (places)"
method: POST
path: "/v1/places"
---

# Google local results (places)

`POST /v1/places`

## Request

- Base URL: `https://api.serpkite.com`
- URL: `https://api.serpkite.com/v1/places`
- Auth: HTTP bearer

## Request body

- SearchRequest
  - `q` string, required
  - `country` string: Country code (ISO 3166-1 alpha-2, case-insensitive; uk is accepted as gb). When omitted and location ends in a country name, that country is used. Russia (ru) is supported across all search verticals, including patents, using the shared proxy routes
  - `language` string: Interface language: a language code with an optional region (e.g. en, ru, de, pt-br, zh-tw, es-419). Russian (ru) is supported across all search verticals; language does not change the selected country. On patents, a non-English code restricts publication language (ar, zh, da, nl, fi, fr, de, it, ja, ko, no, pt, ru, es, sv)
  - `location` string: Free-text location, e.g. "Austin, Texas, United States"
  - `uule` string: Pre-encoded Google location (overrides ll and location; percent-encoded values are decoded)
  - `ll` string: Map point "@lat,lng,14z" (maps and places only; zoom optional): the search runs as a searcher at that point. Overrides location
  - `num` integer: 10, or up to 100 for the depth bundle on search and news (7 credits for 100; values between round up to whole pages). Other verticals return one page of 10
  - `page` integer
  - `time` 'hour' | 'day' | 'week' | 'month' | 'year': Only results from the last hour/day/… (search, news, images, videos, shopping). A fallback engine without that window is skipped, never answered unfiltered
  - `tbs` string: Advanced: raw Google tbs filter (e.g. qdr:d, qdr:w2, cdr:1,cd_min:1/1/2026,cd_max:1/31/2026); overrides time
  - `device` 'desktop' | 'mobile'
  - `safe` 'active' | 'off'
  - `autocorrect` boolean
  - `format` 'json' | 'markdown' | 'compact'
  - `fields` string: Comma-separated projection, e.g. "results.title,results.link,knowledge_graph"
  - `include_content` integer: Also fetch the top N organic pages as Markdown (+1 credit each fetched page)
  - `ads` boolean: Include sponsored results
  - `max_age` integer: Accept a cached result up to this many seconds old (50% of credits on a hit)
  - `engine` union: Which search providers may answer. `google` (the default) is Google only; within Google, SerpKite always fails over across its own proxy pools. `auto` allows falling back to other enabled providers, in route order, when Google is blocked or times out. A single other provider (`brave`) or a list (`["google","brave"]`, or `google,brave` in a query string) restricts the request to those providers. `meta.engine` always names the provider that answered and credits follow that provider's price. A key with "Allow fallback to other search engines" on treats a request without `engine` as `auto`. `consensus` (`/v1/search` only; 400 elsewhere, and it can't be combined with other names) queries several independent search indexes in parallel (at most one Bing-backed provider, so Yahoo or DuckDuckGo never count as agreeing with Bing), merges the results by URL and ranks them by how many providers returned each one. Each result lists its `sources`; `meta.engine` is `consensus` and `meta.route` lists every provider attempt. It stops once `num` unique results are in hand or after a few seconds, and costs the sum of one page at each provider that returned results (providers that failed, came back empty or were never started are free).
    - string
    - Provider[]
  - `include_domains` union: Domains as an array or a comma-separated string, at most 20: a host (`example.com`, subdomains match), a host with a path prefix (`github.com/org`) or a TLD (`.gov`).
    - string
    - string[]
  - `exclude_domains` union: Domains as an array or a comma-separated string, at most 20: a host (`example.com`, subdomains match), a host with a path prefix (`github.com/org`) or a TLD (`.gov`).
    - string
    - string[]
  - `boost_domains` union: Domains as an array or a comma-separated string, at most 20: a host (`example.com`, subdomains match), a host with a path prefix (`github.com/org`) or a TLD (`.gov`).
    - string
    - string[]
  - `start_date` string, date: Only results published on or after this date, YYYY-MM-DD (search, news, images, videos). Can't be combined with time or tbs. A fallback engine without date ranges is skipped
  - `end_date` string, date: Only results published on or before this date, YYYY-MM-DD. Can't be combined with time or tbs
  - `highlights` boolean: Return up to 3 query-ranked passages (`highlights`) of each page read by include_content instead of the whole page (search only; needs include_content; no extra credits)

## Response `200`

OK (text/markdown when format=markdown)

- PlacesResponse
  - `request` RequestEcho, required: The normalised request that produced this response (defaults filled in)
    - `endpoint` string, required
    - `engine` union, required: The engine policy as asked (google, auto, one provider or a list)
      - string
      - string[]
    - `q` string
    - `url` string
    - `country` string
    - `language` string
    - `location` string
    - `num` integer
    - `page` integer
    - `device` string
    - `autocorrect` boolean
    - `tbs` string
    - `start_date` string, date
    - `end_date` string, date
    - `safe` string
    - `place_id` string
    - `cid` string
    - `fid` string
    - `sort` string
    - `include_content` integer
    - `format` string
    - `include_domains` string[]
    - `exclude_domains` string[]
    - `boost_domains` string[]
    - `highlights` boolean
  - `results` PlaceResult[], required
    - `position` integer, required
    - `title` string, required
    - `address` string
    - `latitude` number
    - `longitude` number
    - `rating` number
    - `rating_count` integer
    - `price_level` string
    - `type` string
    - `types` string[]
    - `website` string
    - `phone_number` string
    - `opening_hours` object
    - `thumbnail_url` string
    - `place_id` string
    - `cid` string
    - `fid` string
  - `meta` Meta, required
    - `request_id` string, required
    - `credits_used` number, required
    - `engine` string: The provider that produced the result (`consensus` for a merged engine=consensus answer)
    - `route` RouteStep[]: Provider attempts in order (fresh results only; absent on cache hits). With engine=consensus, every provider started; ones stopped early are `canceled`, ones cut off by the deadline `timeout`
      - `provider` string, required
      - `outcome` 'ok' | 'partial' | 'empty' | 'soft_empty' | 'blocked' | 'timeout' | 'error' | 'unsupported' | 'bad_param' | 'bad_target' | 'canceled', required
      - `ms` integer, required: Duration of the attempt in milliseconds
    - `cached` boolean, required
    - `cached_at` string, date-time
    - `resolved_urls` boolean
    - `parse_quality` 'ok' | 'partial' | 'empty'
    - `latency_ms` integer

## Other responses

- `400`: Error
- `401`: Error
- `402`: Error
- `403`: Error
- `429`: Error
- `503`: Temporarily unavailable, not billed, safe to retry after `Retry-After`. Codes: `upstream_error` (the upstream page couldn't be fetched or parsed), `upstream_blocked` (the upstream is rate limiting us), `upstream_timeout` (the search took too long), `unavailable` (endpoint or dependency down). The API never sends 502 or 504.

---

[API](https://skmtc.dev/serpkite/apis/serpkite-serp-api.md) · [All operations](https://skmtc.dev/serpkite/apis/serpkite-serp-api/llms.txt) · [OpenAPI document](https://skmtc.dev/serpkite/apis/serpkite-serp-api/revisions/f2c6dd05cfc5?raw)