# Places search

`GET /v1/places` finds US businesses and points of interest (restaurants, shops, banks, clinics, parks and more) by name, by kind or near a point, and returns GeoJSON you can keep. It is on every plan, and each call counts 1 address lookup.

Not OpenStreetMap data, and no share-alike.

Places come from the Places data of the

Overture Maps Foundation

, whose providers publish it under permissive licences (CDLA-Permissive-2.0, Apache-2.0, CC0). We keep it in its own database, apart from our OpenStreetMap data, and every result names its providers and licences. On paid plans you may store results indefinitely.

## Try it without a key

```bash
curl "https://api.mapiron.com/v1/demo/places?q=coffee&near=30.2672,-97.7431"
```

The keyless demo returns up to 5 places and is limited per visitor. With a key, use `/v1/places`.

## Search by name, near a point, or both

```bash
curl "https://api.mapiron.com/v1/places?q=coffee&near=30.2672,-97.7431&radius=2000&limit=5&key=YOUR_KEY"
```

```bash
curl "https://api.mapiron.com/v1/places?q=whole+foods+austin+tx&key=YOUR_KEY"
```

```bash
curl "https://api.mapiron.com/v1/places?near=30.2672,-97.7431&radius=500&category=restaurant&key=YOUR_KEY"
```

| Parameter | What it does |
| --- | --- |
| `q` | A name or kind of place, optionally with a town, state or ZIP code: `coffee`, `whole foods austin tx`, `dentist 60543`. Every word must match. Up to 200 characters. |
| `near` | `lat,lon` to search around (or `lat=` and `lon=`). Results come back nearest first, with `distance_m`. |
| `radius` | Metres around `near`, 50 to 50000. Default 25000. |
| `category` | One of Overture's basic categories, such as `restaurant`, `cafe`, `gas_station`, `bank_or_credit_union` or `park`. Needs `q` or `near`. |
| `limit` | 1 to 50. Default 10. |
| `min_confidence` | Only places Overture scores at or above this, 0 to 1. The index holds places scored 0.7 or higher. |
| `autocomplete` | `1` treats the last word of `q` as unfinished, for type-ahead boxes. |

Pass at least `q` or `near`. A search that matches too many places to rank (one very common word with no location) answers 400 `query_too_broad`: add `near`, a town, state or ZIP code, or another word.

## Response

```
{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": { "type": "Point", "coordinates": [-122.44711, 37.78066] },
      "properties": {
        "name": "Epiphany Center",
        "category": "specialized_medical_facility",
        "taxonomy": "abuse_and_addiction_treatment_center",
        "address": "100 Masonic Ave", "city": "San Francisco", "state": "CA", "postcode": "94118", "country": "US",
        "phone": "+14155678370", "website": "http://www.theepiphanycenter.org/",
        "operating_status": "open",
        "gers_id": "d90ef93b-7d52-4d92-be0a-7f5e2eb6011b",
        "confidence": 0.999,
        "source": "overture", "source_datasets": ["meta"], "source_license": ["CDLA-Permissive-2.0"],
        "overture_release": "2026-10-21.0",
        "precision": "place", "keep_forever": true, "distance_m": 12
      }
    }
  ],
  "attribution": "Places: Overture Maps Foundation (overturemaps.org) and its data sources. Sources and licences: https://mapiron.com/attributions#places",
  "license": "You may store these results. No share-alike terms: each place lists its licence in source_license ...",
  "licenses": [ { "id": "CDLA-Permissive-2.0", "name": "Community Data License Agreement - Permissive, Version 2.0", "url": "https://cdla.dev/permissive-2-0/" } ],
  "release": "2026-10-21.0",
  "data_version": "20261112"
}
```

| Field | Meaning |
| --- | --- |
| `gers_id` | The place's id in Overture's Global Entity Reference System. Store it and look the place up again later. |
| `confidence` | Overture's score, 0 to 1, that the place exists as described. Listings come from third parties and can be out of date. |
| `source_datasets`, `source_license` | Who supplied the place, and under which licence. |
| `overture_release` | The Overture release the place came from. We load each monthly release. |
| `operating_status` | `open` or `temporarily_closed` when Overture knows it. Permanently closed places are left out. |
| `keep_forever` | `true`: the place's licence lets you keep it. Your plan sets how long you may store results (see below). |
| `licenses` | Name and link for each licence in this answer, with any notice a licence asks you to keep. |

## Look a place up by its id

```bash
curl "https://api.mapiron.com/v1/places/d90ef93b-7d52-4d92-be0a-7f5e2eb6011b?key=YOUR_KEY"
```

Returns the same shape with one place, or 404 when the current release no longer has that id. An id stays the same from release to release while Overture can match the place; it can change when a place is renamed, moves or is merged with another listing. 1 address lookup.

## Storing results and credit

- **Paid plans** may store places results indefinitely. **Free** may store them for up to 30 days. The `license` field of each answer says which applies.
- Show the `attribution` text near places you display. Places are not OpenStreetMap data, so they don't need the OpenStreetMap credit (your map still does).
- If you pass stored places on to others, keep the attribution and make the licence texts available: the links in `licenses` are enough. Foursquare-sourced places also carry Foursquare's copyright notice there.

| Provider | `source_datasets` value | Licence | Notice to keep |
| --- | --- | --- | --- |
| Meta | `meta` | [CDLA-Permissive-2.0](https://cdla.dev/permissive-2-0/) |  |
| Microsoft | `Microsoft` | [CDLA-Permissive-2.0](https://cdla.dev/permissive-2-0/) |  |
| BrightQuery | `BrightQuery` | [CDLA-Permissive-2.0](https://cdla.dev/permissive-2-0/) |  |
| DAC | `DAC` | [CDLA-Permissive-2.0](https://cdla.dev/permissive-2-0/) |  |
| Uberall | `Uberall` | [CDLA-Permissive-2.0](https://cdla.dev/permissive-2-0/) |  |
| Birdeye | `Birdeye` | [CDLA-Permissive-2.0](https://cdla.dev/permissive-2-0/) |  |
| PinMeTo | `PinMeTo` | [CDLA-Permissive-2.0](https://cdla.dev/permissive-2-0/) |  |
| RenderSEO | `RenderSEO` | [CDLA-Permissive-2.0](https://cdla.dev/permissive-2-0/) |  |
| Krick | `Krick` | [CDLA-Permissive-2.0](https://cdla.dev/permissive-2-0/) |  |
| OpenTravel Alliance | `OpenTravel` | [CDLA-Permissive-2.0](https://cdla.dev/permissive-2-0/) |  |
| Foursquare | `Foursquare` | [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0) | Copyright 2024 Foursquare Labs, Inc. All rights reserved. Foursquare Open Source Places data, transformed to the Overture Maps schema by the Overture Maps Foundation. [NOTICE](https://opensource.foursquare.com/places-notice-txt/) |
| AllThePlaces | `AllThePlaces` | [CC0-1.0](https://creativecommons.org/publicdomain/zero/1.0/) |  |

A place from any provider or licence that isn't in this table is left out of our index until we have read its terms. Full list: [Data sources and licences](https://mapiron.com/attributions#places).

## Coverage and limits

- United States only for now.
- Places data has duplicates and listings that are out of date. Treat `confidence` as a guide, and don't present a result as verified.
- Places search doesn't change `/v1/geocode`: geocoding answers still come only from OpenStreetMap and our address layer.
- Hard monthly caps apply as for geocoding: at the cap you get 429 `monthly_cap_reached`, and nothing is billed for overage.
- AI assistants can use the `place_search` tool on the [MCP server](https://mapiron.com/docs/mcp).

---
Source: https://mapiron.com/docs/places · Map data © OpenStreetMap contributors · Index: https://mapiron.com/llms.txt