Skip to main content
POST
Place search

Authorizations

x-api-key
string
header
required

Body

application/json

Place search request: places matching query in or near a location.

query
string
required

What to find, e.g. ramen, 24 hour pharmacy or a place's name.

Required string length: 1 - 200
location
string | null

Where to search: a city, neighborhood, address or postal code. Set this, latitude and longitude, or both; a request with neither is rejected.

Required string length: 2 - 200
Example:

"Shibuya, Tokyo"

latitude
number | null

Search center latitude; set with longitude.

Required range: -90 <= x <= 90
longitude
number | null

Search center longitude; set with latitude.

Required range: -180 <= x <= 180
max_distance_km
number | null

Only places within this many km of the search center. Defaults to the size of location when it is a city or postal code, else 25.

Required range: 0 < x <= 200
open_now
boolean
default:false

Only places open at request time, in each place's own time zone. Places whose open state is unknown are left out.

max_results
integer | null

Upper bound on results. Defaults to 10; values above the mode's maximum are reduced to it, with a warning.

Required range: x >= 1
mode
enum<string> | null

fast: lowest latency, with fewer results. advanced (default): slower, with more complete results.

Available options:
fast,
advanced
session_id
string | null

Session identifier that groups related calls made as part of a larger task. Echoed back in the response when nonempty; generated by the server if omitted, null, or empty.

Maximum string length: 1000
client_model
string | null

The model generating this request and consuming the results.

Example:

"claude-opus-4-7"

Response

Successful Response

Place search response.

search_id
string
required

Search ID. Example: search_cad0a6d2dec046bd95ae900527d880e7

session_id
string
required

Session identifier, echoed back from the request when nonempty; otherwise generated by the server. Pass it to later calls made as part of the same task.

Example:

"session_8a911eb27c7a4afaa20d0d9dc98d07c0"

results
PlaceSearchResult · object[]
required

A list of places, ordered by decreasing relevance.

warnings
Warning · object[] | null

Warnings for the search request, if any.

usage
UsageItem · object[] | null

Usage metrics for the search request.