Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: SerpKite SERP Place API
version: 1.12.4
description: 'Public search API (api.serpkite.com). Google results as clean JSON or Markdown
for AI agents, plus a Google Custom Search–compatible endpoint. Official SDKs:
`serpkite` on npm and PyPI, `github.com/serpkite/serpkite-go`. **Auth:** `Authorization: Bearer skt_live_…`. A bare `Authorization: skt_live_…`
(no scheme) is also accepted, for MCP hosts that can''t add one. GET requests
may pass `?api_key=` instead. `/customsearch/v1` also accepts Google''s `?key=`. **Bodies:** every vertical accepts `POST` with a JSON object or `GET` with the
same parameters in the query string (only `GET /v1/search` is spelled out
here). Unknown parameters are rejected with 400, and so is a parameter the
endpoint would ignore (e.g. `time` on `/v1/scholar`, `ll` on `/v1/search`). To run many queries at once,
use `POST /v1/batches`. **Formats:** `format=json` (default) returns the schemas below. `format=markdown` returns `text/markdown` for every vertical. `format=compact` and `fields=` return a reduced JSON object (same top-level
keys, fewer item fields, `meta` always kept), so required item fields may be
absent there. **Responses** share one envelope: `request` (the normalised request),
`results` (the vertical''s primary list), vertical-specific extras and `meta`. All keys are snake_case. **Credits** are decimal numbers (e.g. `0.5`). Failed, empty and blocked
responses are refunded. Every billed response carries `X-Credits-Used`,
`X-Credits-Remaining`, `X-Cost-USD`, `X-Cache` (`HIT`|`MISS`), `X-Latency-Ms`,
`X-Tokens-Estimate` and `X-Request-Id`. **Errors** share one body: `{"error":{"code","message","request_id"}}`. Upstream failures (`upstream_error`, `upstream_blocked`, `upstream_timeout`)
are `503` with `Retry-After`, never billed and safe to retry. The API never
returns `502` or `504`. `429` also carries `Retry-After`: `rate_limited` is
the per-second limit; `daily_limit_reached` is the free daily limit of an
account that never bought a pack, which resets at 00:00 UTC (the message
names the limit and the billing page; buying any pack removes it). `403 account_restricted` means the account''s free use is paused because it
appears to be one of several accounts run by the same person (same device
or network, or requests in step with other accounts) or uses a disposable
email address; buying any pack lifts it. **CORS:** `Access-Control-Allow-Origin: *` without credentials; the `X-*`
headers above are exposed, so a browser playground can call the API with a key. The keyless `/playground/search` is the exception: it only answers serpkite.com
and app.serpkite.com (other `Origin`s get 403). Credit table: search/news/images/videos/maps/places/shopping/scholar/patents/
webpage/customsearch = 1 per page; place details = 1; `num=100` depth bundle = 7; reviews = 1 per 10;
autocomplete = 0.5; `include_content` = +1 per fetched page;
batches ×0.5 (from 2026-11-23 a batch depth request is 0.5 per page with
results, without the bundle cap: `num=100` = 5); cache hit via `max_age` ×0.5. `engine=consensus` (search only) =
the sum of one page per provider that returned results. **AI** (Claude writes, OpenAI''s Decisions API runs typed checks; a failed
model step is never billed): an answer (`include_answer` on `/v1/search` and
`/v1/news`, the model part of `/v1/answer`) = +2 over the result page, +4
when it read pages (`include_content`, `/v1/answer` depth=standard);
`/v1/extract` `summary` = +4 and `output_schema` = +4 per page;
`/v1/research` = lite 30, standard 75, deep 200. Responses that used a
model carry `meta.llm`. **AI assistants** (`/v1/chatgpt`, `/v1/gemini`, `/v1/copilot`,
`/v1/ai_mode`, `/v1/brave_ai`): a `prompt` sent to the public assistant
as a logged-out user; the response is its answer
(`text`, `markdown`) with the `sources` it cited or listed,
`search_queries`, `products` and `places` where the assistant shows them,
and `mentions` for the brands and domains in `track`.'
servers:
- url: https://api.serpkite.com
- url: http://localhost:8080
security:
- bearer: []
tags:
- name: Place
paths:
/v1/place:
post:
summary: Details of one place (by `place_id`, `cid`, `fid` or Yandex `oid`); 1 credit
operationId: place
description: 'The full Google Maps listing of one place: address, country, coordinates, time zone,
categories, opening hours (as text and as structured `weekly_hours`), website, phone,
rating, description and photos, in `language`. `results` holds the place, or is empty
(not charged) when no place has that identifier.
With `oid` (a Yandex Maps organisation id, e.g. from an `engine=yandex` maps result or
`yandex.ru/maps/org///`) the listing comes from Yandex Maps, where the
deployment enables it: `oid` implies `engine=yandex` and can''t be combined with Google''s
identifiers. Closed listings (temporarily or permanently) carry no hours.'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PlaceRequest'
responses:
'200':
$ref: '#/components/responses/PlacesOK'
'400':
$ref: '#/components/responses/Error'
'401':
$ref: '#/components/responses/Error'
'402':
$ref: '#/components/responses/Error'
'403':
$ref: '#/components/responses/Error'
'429':
$ref: '#/components/responses/Error'
'503':
$ref: '#/components/responses/Unavailable'
tags:
- Place
components:
headers:
RetryAfter:
description: Seconds to wait before retrying
schema:
type: integer
CreditsRemaining:
schema:
type: number
TokensEstimate:
schema:
type: integer
LatencyMs:
schema:
type: integer
CreditsUsed:
schema:
type: number
CostUSD:
schema:
type: number
Cache:
schema:
type: string
enum:
- HIT
- MISS
schemas:
PlacePhoto:
type: object
required:
- url
properties:
url:
type: string
description: Image URL (at most 1600 px on the long side)
width:
type: integer
height:
type: integer
source:
type: string
enum:
- business
- visitor
description: Who uploaded it, when Google says (Google shows no contributor names to logged-out visitors)
HoursInterval:
type: object
required:
- open
- close
properties:
open:
type: string
pattern: ^[0-2][0-9]:[0-5][0-9]$
examples:
- 08:00
close:
type: string
pattern: ^[0-2][0-9]:[0-5][0-9]$
examples:
- '22:00'
next_day:
type: boolean
description: The interval closes after midnight, on the next day
PlaceResult:
type: object
required:
- position
- title
properties:
position:
type: integer
title:
type: string
address:
type: string
latitude:
type: number
longitude:
type: number
rating:
type: number
rating_count:
type: integer
price_level:
type: string
type:
type: string
types:
type: array
items:
type: string
website:
type: string
phone_number:
type: string
international_phone_number:
type: string
examples:
- +44 20 7232 3010
opening_hours:
type: object
additionalProperties:
type: string
description: 'Hours as the provider displays them, keyed by English weekday (Monday … Sunday), in `language`, e.g. {"Monday": "7:30 am–6 pm", "Sunday": "Closed"}; Yandex Maps: 24-hour times ("08:00–22:00"), "Closed"/"выходной", "Open 24 hours"/"круглосуточно"'
weekly_hours:
$ref: '#/components/schemas/WeeklyHours'
country:
type: string
description: ISO 3166-1 alpha-2 country code of the place, upper case (RU, GB)
timezone:
type: string
description: IANA time zone of the place (Europe/Moscow)
description:
type: string
description: Google's short description of the place, or the owner's, when Google shows one; Yandex Maps' summary of the place when it has one
photos:
type: array
description: Photos of the place (/v1/place; up to 10). The URLs are public and can be fetched server-side without cookies
items:
$ref: '#/components/schemas/PlacePhoto'
google_maps_url:
type: string
description: The place on Google Maps
thumbnail_url:
type: string
place_id:
type: string
cid:
type: string
fid:
type: string
oid:
type: string
description: Yandex Maps organisation id (engine=yandex), for /v1/place
yandex_maps_url:
type: string
description: 'The place on Yandex Maps (engine=yandex): https://yandex.ru/maps/org/<oid>/'
PlacesResponse:
type: object
required:
- request
- results
- meta
properties:
request:
$ref: '#/components/schemas/RequestEcho'
results:
type: array
items:
$ref: '#/components/schemas/PlaceResult'
meta:
$ref: '#/components/schemas/Meta'
Meta:
type: object
required:
- request_id
- credits_used
- cached
properties:
request_id:
type: string
credits_used:
type: number
engine:
type: string
description: The provider that produced the result (`consensus` for a merged engine=consensus answer)
examples:
- google
- brave
- consensus
- stub
route:
type: array
description: 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`
items:
$ref: '#/components/schemas/RouteStep'
cached:
type: boolean
cached_at:
type: string
format: date-time
resolved_urls:
type: boolean
parse_quality:
type: string
enum:
- ok
- partial
- empty
latency_ms:
type: integer
llm:
$ref: '#/components/schemas/LLMUsage'
warnings:
type: array
items:
type: string
description: Non-fatal problems, e.g. an include_answer that failed (and was refunded)
Provider:
type: string
description: A search provider (docs/providers). Which verticals each serves depends on the deployment.
enum:
- google
- brave
- bing
- yahoo
- duckduckgo
- mojeek
- wikipedia
- yandex
PlaceRequest:
type: object
description: One of place_id, cid or fid (Google; place_id wins, then fid, then cid) or oid (Yandex Maps) is required
properties:
place_id:
type: string
description: Google place id ("ChIJ…"), e.g. `place_id` of a /v1/maps result
cid:
type: string
description: Decimal customer id (`cid` of a result)
fid:
type: string
description: Feature id "0x…:0x…" (`fid` of a result)
oid:
type: string
pattern: ^[0-9]{1,20}$
examples:
- '1045821788'
description: Yandex Maps organisation id (`oid` of an `engine=yandex` maps result). Implies `engine=yandex`; not with place_id, cid or fid
country:
type: string
default: us
description: Country code (ISO 3166-1 alpha-2); Google's regional view of the listing
language:
type: string
default: en
description: Language of the address, categories, hours and description (e.g. en, ru, de)
format:
type: string
enum:
- json
- markdown
- compact
default: json
fields:
type: string
max_age:
type: integer
minimum: 0
description: Accept a cached result up to this many seconds old (50% of credits on a hit)
engine:
$ref: '#/components/schemas/EngineParam'
HoursIntervals:
type: array
items:
$ref: '#/components/schemas/HoursInterval'
EngineParam:
description: 'Which search providers may answer. `google` (the default) is Google only; Google requests are retried internally before failing. `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. Up to three providers answer: a provider that fails or comes back empty hands its turn to the next one in the route. 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). `yandex` serves `/v1/search` from Yandex web search (no `time` filter or `safe: active`: a request naming it gets a 400 with them) and `/v1/maps`, `/v1/places` and `/v1/place` from Yandex Maps, where the deployment enables it (otherwise a 503 `unavailable`, not charged); with `auto` it is the last fallback there.'
oneOf:
- type: string
default: google
examples:
- google
- auto
- consensus
- brave
- google,brave
- type: array
items:
$ref: '#/components/schemas/Provider'
minItems: 1
WeeklyHours:
type: object
description: 'Opening hours per weekday, from the provider''s listing, as local times (`timezone`) in 24-hour HH:MM.
A day that is closed is an empty list; a day open 24 hours is `[{"open": "00:00", "close": "24:00"}]`;
a day with a break has several intervals. `close` is "24:00" at midnight, and an interval that
ends after midnight has `next_day: true` (e.g. 17:30–03:00). Days Google doesn''t list are absent;
Yandex Maps lists all seven or none.
'
properties:
monday:
$ref: '#/components/schemas/HoursIntervals'
tuesday:
$ref: '#/components/schemas/HoursIntervals'
wednesday:
$ref: '#/components/schemas/HoursIntervals'
thursday:
$ref: '#/components/schemas/HoursIntervals'
friday:
$ref: '#/components/schemas/HoursIntervals'
saturday:
$ref: '#/components/schemas/HoursIntervals'
sunday:
$ref: '#/components/schemas/HoursIntervals'
RouteStep:
type: object
description: One provider attempt behind this answer.
required:
- provider
- outcome
- ms
properties:
provider:
type: string
examples:
- google
- brave
outcome:
type: string
enum:
- ok
- partial
- empty
- soft_empty
- blocked
- timeout
- error
- unsupported
- bad_param
- bad_target
- canceled
ms:
type: integer
description: Duration of the attempt in milliseconds
LLMUsage:
type: object
description: The model that wrote this response's AI part and the tokens it used
properties:
provider:
type: string
examples:
- anthropic
- openai
model:
type: string
examples:
- claude-haiku-5-5
- gpt-6-luna
input_tokens:
type: integer
output_tokens:
type: integer
Error:
type: object
required:
- error
properties:
error:
type: object
required:
- code
- message
properties:
code:
type: string
description: '403: spend_cap_reached, key_limit_reached, account_restricted, forbidden. 409/422: idempotency_key_reused. 422: target_unavailable (the URL you asked for failed: its site answered 404, its domain doesn''t resolve; resending won''t help), no_pages. 429: rate_limited, daily_limit_reached. 503: upstream_error, upstream_blocked, upstream_timeout, unavailable (the API never sends 502 or 504)'
examples:
- unauthorized
- invalid_request
- insufficient_credits
- rate_limited
- daily_limit_reached
- spend_cap_reached
- key_limit_reached
- account_restricted
- idempotency_key_reused
- forbidden
- not_found
- upstream_error
- upstream_blocked
- upstream_timeout
- unavailable
- internal
message:
type: string
request_id:
type: string
RequestEcho:
type: object
description: The normalised request that produced this response (defaults filled in)
required:
- endpoint
- engine
additionalProperties: true
properties:
endpoint:
type: string
examples:
- search
- news
- webpage
- chatgpt
engine:
description: The engine policy as asked (google, auto, one provider or a list)
oneOf:
- type: string
- type: array
items:
type: string
q:
type: string
url:
type: string
country:
type: string
language:
type: string
location:
type: string
num:
type: integer
page:
type: integer
device:
type: string
autocorrect:
type: boolean
tbs:
type: string
start_date:
type: string
format: date
end_date:
type: string
format: date
safe:
type: string
place_id:
type: string
cid:
type: string
fid:
type: string
oid:
type: string
sort:
type: string
include_content:
type: integer
format:
type: string
include_domains:
type: array
items:
type: string
exclude_domains:
type: array
items:
type: string
boost_domains:
type: array
items:
type: string
highlights:
type: boolean
include_answer:
type: boolean
prompt:
type: string
description: AI assistant endpoints
web_search:
type: boolean
description: /v1/chatgpt
include_html:
type: boolean
responses:
PlacesOK:
description: OK (text/markdown when format=markdown)
headers:
X-Credits-Used:
$ref: '#/components/headers/CreditsUsed'
X-Credits-Remaining:
$ref: '#/components/headers/CreditsRemaining'
X-Cost-USD:
$ref: '#/components/headers/CostUSD'
X-Cache:
$ref: '#/components/headers/Cache'
X-Latency-Ms:
$ref: '#/components/headers/LatencyMs'
X-Tokens-Estimate:
$ref: '#/components/headers/TokensEstimate'
content:
application/json:
schema:
$ref: '#/components/schemas/PlacesResponse'
text/markdown:
schema:
type: string
Unavailable:
description: '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 or refused the query), `upstream_timeout`
(the search took too long), `unavailable` (endpoint or dependency down).
The API never sends 502 or 504.
'
headers:
Retry-After:
$ref: '#/components/headers/RetryAfter'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Error:
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
securitySchemes:
bearer:
type: http
scheme: bearer
oauth:
type: oauth2
description: OAuth 2.1 for the remote MCP server only (authorization code + PKCE S256; app-api.serpkite.com is the authorization server).
flows:
authorizationCode:
authorizationUrl: https://app-api.serpkite.com/oauth/authorize
tokenUrl: https://app-api.serpkite.com/oauth/token
refreshUrl: https://app-api.serpkite.com/oauth/token
scopes:
mcp: Use the SerpKite MCP tools, billed to your account
offline_access: Stay connected with refresh tokens