Operation

`GET /v1/places`

Searches place names and scoped addresses near a latitude/longitude point, or lists a category in an area when category is supplied. The source contract has a readable preview at OpenAPI YAML.

GET https://api.openplacesapi.com/v1/places

Authenticated public search endpoint for server-side integrations.

Query parameters

Inputs accepted by the search endpoint.

Name	Type	Required	Details
`q`	string	Usually	Search text, 3 to 128 characters after normalization. Required unless `category` is supplied.
`category`	string	No	Exact Overture category string. Enables category browse and makes `q` optional.
`lat`	number	Yes	Latitude from `-90` to `90`.
`lon`	number	Yes	Longitude from `-180` to `180`.
`radius_mi`	number	No	Defaults to `25`; maximum is `50`.
`mode`	enum	No	`all`, `name`, or `address`. Defaults to `all`.
`limit`	integer	No	Defaults to `10`; text search maximum is `20`, category browse maximum is `50`.
`offset`	integer	No	Category-browse pagination offset from `0` to `950`. Each page is one billed search.
`min_confidence`	number	No	Minimum confidence from `0` to `1`. Omit for no confidence filter.
`layer_preset`	string	No	Account-owned preset slug. Mutually exclusive with `layers`.
`layers`	string	No	Explicit ordered selection such as `base,open,account:client-a`.

Responses

Success, quota, and error responses are explicit.

Status	Response
`200`	Search completed, including zero-result searches.
`400`, `422`	Validation or unsupported query shape.
`401`, `403`	Authentication or layer authorization failure.
`402`, `429`, `503`	Quota exhausted, per-account rate limit exceeded, or temporarily unavailable.

The rate limit is 120 requests per minute per account on every plan. Top-ups raise X-Quota-Limit for the current period.

JSON SearchResponse

{
  "results": [
    {
      "place_id": "overture:08f2c...",
      "name": "Devocion",
      "lat": 40.688838,
      "lon": -73.979914,
      "distance_mi": 0.4,
      "categories": ["cafe"],
      "address": {
        "locality": "Brooklyn",
        "country_code": "US"
      },
      "phone": "+17185551212",
      "website": "https://www.devocion.com",
      "confidence": 0.92,
      "operating_status": "operational"
    }
  ],
  "meta": {
    "request_id": "00000000-0000-4000-8000-000000000000",
    "q": "coffee",
    "category": null,
    "min_confidence": 0.85,
    "mode": "all",
    "lat": 40.7128,
    "lon": -74.006,
    "radius_mi": 25,
    "limit": 10,
    "offset": 0,
    "next_offset": null,
    "warnings": []
  }
}

Preview OpenAPI YAML Review the source contract visually before downloading the YAML file. Error details Review machine-readable codes, quota headers, and retry metadata.