API Reference

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.

In the default mode=all, when category is not supplied and q names a kind of place, the search also covers the matching categories. Top-level groups such as shopping or food_and_drink are never read from q.

A whole-q category phrase such as pharmacy, chemist, fire station, or pizza near me lists places in the category first (primary-category and subcategory matches before alternate-category matches; within each, confidence bands of at least 0.9, at least 0.6 but below 0.9, then below 0.6 (including missing confidence), nearest first within each band), then other places whose name matches q. Address-only matches are dropped. A category phrase plus other words, such as boots pharmacy, keeps full-text matches first, then adds places in the category whose names match the other words.

meta.interpreted_as reports the reading (type, categories, text, and a message), or is null when q was searched as plain text. Each result can carry match: name, address, category, or name_and_category. Use mode=name to match a literal name, and an explicit category with offset to page through a category, up to the first 1,000 places per query area.

If a search with q finds nothing, it is retried once with a relaxed q: trailing legal suffixes such as LLC or GmbH, parenthesized asides, and the words and, the, and of are dropped. Relaxed results must contain the remaining words as whole words of the place name and carry a query_relaxed warning. If that still finds nothing, q may be read as the closest category by meaning (for example tienda de computadoras as computer_store): the results are nearby places in that category, with match: category and a category_inferred warning.

Only requests with an explicit category can page. Follow meta.next_offset; each page is one billed search. It can be null because the next page would cross the 1,000-place window even when more places match; check pagination_limit_reached in meta.warnings.

const apiKey = process.env.OPA_KEY;
if (!apiKey) throw new Error("OPA_KEY is required");
let offset = 0;
do {
  const url = new URL("https://api.openplacesapi.com/v1/places");
  url.search = new URLSearchParams({
    category: "cafe", lat: "40.7128", lon: "-74.0060",
    limit: "50", offset: String(offset),
  }).toString();
  const response = await fetch(url, {
    headers: { Authorization: `Bearer ${apiKey}` },
  });
  if (!response.ok) throw new Error(`Search failed: ${response.status}`);
  const body = await response.json();
  console.log(body.results);
  offset = body.meta.next_offset;
} while (offset !== null);

The rate limit is 120 requests per minute per account for everyone, with at most 8 searches in flight per account at once. Purchases add searches and extend the whole balance for 12 months. X-Quota-Limit describes the current balance allocation; X-Quota-Remaining is the number left. There is no reset header. Every error body includes a docs_url linking to its entry on the errors page.

{
  "results": [
    {
      "place_id": "overture:08f2c...",
      "name": "Devocion",
      "lat": 40.688838,
      "lon": -73.979914,
      "distance_mi": 2.15,
      "category": "cafe",
      "categories": ["cafe", "coffee_shop"],
      "category_hierarchy": ["food_and_drink", "casual_eatery", "cafe"],
      "address": {
        "locality": "Brooklyn",
        "country_code": "US"
      },
      "phone": "+17185551212",
      "website": "https://www.devocion.com",
      "confidence": 0.92,
      "operating_status": "operational",
      "match": "category"
    }
  ],
  "meta": {
    "request_id": "00000000-0000-4000-8000-000000000000",
    "data_source": "overture",
    "data_release": "2026-10-21.0",
    "data_releases": ["2026-10-21.0"],
    "q": "coffee",
    "category": null,
    "min_confidence": 0.85,
    "sort": "relevance",
    "mode": "all",
    "lat": 40.7128,
    "lon": -74.006,
    "radius_mi": 25,
    "limit": 10,
    "offset": 0,
    "next_offset": null,
    "interpreted_as": {
      "type": "category",
      "categories": ["coffee_shop", "cafe"],
      "text": null,
      "message": "Read \"coffee\" as the category coffee_shop (also cafe): places in that category come first, then other name matches. Use mode=name to match names only, or category=coffee_shop with offset to page through every match."
    },
    "warnings": [],
    "layer_selection": {
      "source": "default",
      "preset": null,
      "layers": [{ "type": "overture_base" }, { "type": "open" }]
    }
  }
}

Successful responses can carry warnings. On an empty first page, unknown_category lists the closest known categories in suggestions, and no_results_within_radius reports nearest_match_distance_mi and a nearest_match object (public id, name, distance_mi, and locality and country when available) when a match is found within 100 miles. That place stays outside results, with a message naming the radius_mi to retry with. query_relaxed means q had no exact matches and the results are for the relaxed text named in the message. category_inferred means nothing matched by name, so the results are nearby places in the closest category by meaning. pagination_limit_reached means more places match than a category browse can page through, so next_offset is null before the end of the results. See search warnings for every code.

Lists valid category values from the Overture category taxonomy, including parent groups. It is public, needs no API key, does not count against quota, and is cacheable for an hour. Without q it returns every category alphabetically; with q (1 to 64 characters) it returns the best matches, 20 by default. limit accepts 1 to 100. Unknown parameters return validation_error.

curl "https://api.openplacesapi.com/v1/categories?q=coffee&limit=3"

{
  "categories": [
    {
      "category": "coffee_shop",
      "label": "Coffee shop",
      "parent": "non_alcoholic_beverage_venue",
      "hierarchy": [
        "food_and_drink",
        "non_alcoholic_beverage_venue",
        "coffee_shop"
      ]
    },
    {
      "category": "coffee_roastery",
      "label": "Coffee roastery",
      "parent": "coffee_shop",
      "hierarchy": [
        "food_and_drink",
        "non_alcoholic_beverage_venue",
        "coffee_shop",
        "coffee_roastery"
      ]
    },
    {
      "category": "coffee_and_tea_supplies",
      "label": "Coffee and tea supplies",
      "parent": "food_and_beverage_store",
      "hierarchy": [
        "shopping",
        "food_and_beverage_store",
        "coffee_and_tea_supplies"
      ]
    }
  ],
  "meta": {
    "request_id": "00000000-0000-4000-8000-000000000000",
    "q": "coffee",
    "count": 3,
    "total": 2201
  }
}