Skip to content
Close API

Search POIs by location

GET
/v1/pois

Find POIs within a bounding box or a radius of a point. Provide either bbox, or lat+lon+radius_m.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
lat
Any of:
number
>= -90 <= 90
lon
Any of:
number
>= -180 <= 180
radius_m
Any of:
number
> 0 <= 50000
bbox
Any of:
string

Min_lon,min_lat,max_lon,max_lat

type
Any of:
Array<integer>
q
Any of:
string

Name substring

limit
Any of:
integer
>= 1 <= 1000
cursor
Any of:
string

Responses

Section titled “Responses”

200

Section titled “200”

Successful Response

PoiSearchResponse
object
next_cursor
Any of:
string
results
required
Results
Array<object>
PoiSearchResult

A POI search hit. NOTE: no mode/travel_time here (search is spatial, not routed). (routers.pois.poi_search)

object
address
required
Address

A POI street address; every field is nullable. (shape.shape_pois, queries.pois.detail)

object
city
Any of:
string
state
Any of:
string
street
Any of:
string
zip
Any of:
string
dest_id
required
Dest Id
integer
lat
required
Lat
number
lon
required
Lon
number
name
required
Name
string
Example
{
  "next_cursor": null,
  "results": [
    {
      "address": {
        "city": "Springfield",
        "state": "OR",
        "street": "742 Evergreen Ter",
        "zip": "97477"
      },
      "dest_id": 9001,
      "lat": 44.05,
      "lon": -123.09,
      "name": "Market of Choice"
    }
  ]
}

304

Section titled “304”

Not modified (If-None-Match matched the ETag); no body, no tokens charged

400

Section titled “400”

Invalid request (e.g. invalid-parameters, invalid-cursor, invalid-bbox, missing-location, missing-area, invalid-geometry, polygon-too-complex, missing-origins, too-many-origins)

ValidationProblem

400 invalid-parameters, carrying the offending fields. (core.problems, RequestValidationError handler)

object
detail
Any of:
string
errors
Any of:
Array<object>
ValidationErrorItem
object
loc
required
Loc
Array
msg
required
Msg
string
type
required
Type
string
status
required
Status
integer
title
required
Title
string
type
required
Type

Problem type URI; the final path segment is the stable slug

string
key
additional properties
any

401

Section titled “401”

Missing or invalid API key (missing-key, invalid-key)

Problem

RFC 9457 problem detail. Served as application/problem+json. Additional members appear for some problem types (e.g. errors). (core.problems.problem)

object
detail
Any of:
string
status
required
Status
integer
title
required
Title
string
type
required
Type

Problem type URI; the final path segment is the stable slug

string
key
additional properties
any

403

Section titled “403”

Key disabled (account-disabled)

Problem

RFC 9457 problem detail. Served as application/problem+json. Additional members appear for some problem types (e.g. errors). (core.problems.problem)

object
detail
Any of:
string
status
required
Status
integer
title
required
Title
string
type
required
Type

Problem type URI; the final path segment is the stable slug

string
key
additional properties
any

429

Section titled “429”

Rate limited or token balance exhausted (rate-limited, tokens-exhausted); sets Retry-After

Problem

RFC 9457 problem detail. Served as application/problem+json. Additional members appear for some problem types (e.g. errors). (core.problems.problem)

object
detail
Any of:
string
status
required
Status
integer
title
required
Title
string
type
required
Type

Problem type URI; the final path segment is the stable slug

string
key
additional properties
any

503

Section titled “503”

Backend temporarily unavailable (debit-unavailable, store-unavailable); may set Retry-After

Problem

RFC 9457 problem detail. Served as application/problem+json. Additional members appear for some problem types (e.g. errors). (core.problems.problem)

object
detail
Any of:
string
status
required
Status
integer
title
required
Title
string
type
required
Type

Problem type URI; the final path segment is the stable slug

string
key
additional properties
any