Geocode a place name or address
openstreetmap_search_placesRead-onlyIdempotent
Convert a place name or address to geographic coordinates and structured place data via Nominatim/OpenStreetMap. Accepts either a free-form query string (e.g., "Space Needle Seattle") or structured address fields (street, city, state, etc.) — the two modes are mutually exclusive. Returns results ordered by Nominatim relevance (importance score). Use countrycodes to restrict results to specific countries. For exhaustive POI lists in an area, use openstreetmap_query_nearby or openstreetmap_query_bbox instead — Nominatim search returns best matches, not all matching objects. Results are matched on name and address relevance, never on an OSM attribute tag: extratags decorates whichever object matched and cannot select one, so a named feature may resolve to a different OSM object than the one carrying the tags you want. To filter or enumerate by tag (surface, sac_scale, ele, access, amenity), use openstreetmap_query_nearby, openstreetmap_query_bbox, or openstreetmap_query_raw.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| city | No | City name (structured query). | |
| layer | No | Filter by data layer. Comma-separated values: address, poi, railway, natural, manmade. Default: no restriction. | |
| limit | No | Maximum results to return. Nominatim may return fewer when additional results do not sufficiently match. Max 40. | |
| query | No | Free-form search string (e.g., "Space Needle Seattle" or "1600 Pennsylvania Ave NW, Washington DC"). Cannot be combined with structured address fields. Keep the query to a POI name plus its city or region. Do not insert a parent institution, campus, or building name between the name and the locality: Nominatim reads commas as an address hierarchy and returns nothing when an intermediate token is not a matching containment level. For example, use "Beinecke Library, New Haven", not "Beinecke Library, Yale University, New Haven". | |
| state | No | State or province (structured query). | |
| county | No | County or district (structured query). | |
| street | No | House number and street name (structured query). Use with city/state/country fields. Cannot be combined with query. | |
| country | No | Country name or ISO 3166-1 alpha-2 code (structured query). | |
| language | No | Preferred language for result names (BCP 47 code or Accept-Language string, e.g., "en", "de", "fr,en"). Defaults to local OSM language. | |
| extratags | No | Include the extra OSM tags the matched object carries — contact and metadata tags (phone, website, opening_hours, wikidata) and physical attribute tags alike (surface, tracktype, sac_scale, ele, access). Opportunistic, not selective: it reports whatever the matched object happens to carry, so an absent tag describes that object rather than OpenStreetMap, and no value here can steer which object is matched. Increases response size. | |
| postalcode | No | Postal or ZIP code (structured query). | |
| featureType | No | Restrict results to a geographic feature type. Automatically implies the address layer. | |
| countrycodes | No | Restrict results to one or more countries. Comma-separated ISO 3166-1 alpha-2 codes (e.g., "us,ca"). Preferred over the structured country field when filtering. | |
| exclude_place_ids | No | OSM refs (N/W/R + id) or Nominatim place_ids to drop from results, forwarded as the exclude_place_ids parameter. Pass the nextExcludeIds value from a prior truncated response to page toward the next-best matches — it emits stable OSM refs when available, which page more reliably than volatile place_ids. When the walk runs out, the call succeeds with zero results and an exhaustion notice rather than failing — treat that as the loop-termination signal. Best-effort progressive retrieval, not a stable cursor — Nominatim ranking can reorder slightly between calls, so already-seen results may shift. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cap | No | The limit applied to this request. | |
| error | No | Present when the call failed. Absent on success. | |
| shown | No | Number of results returned. | |
| total | No | Number of results returned. | |
| notice | No | Guidance for this page, covering two cases: results were capped at limit (truncated is true — keep paging with nextExcludeIds), or an exclude_place_ids paging walk is exhausted and the page came back empty (the query matched, the walk simply ended, so no rewrite is needed). Tell them apart by truncated and the result count, not by this field being present. Absent when a page returns below the limit without being capped. Carries paging guidance only — the tag-selection caveat has its own field so neither message can overwrite the other. | |
| results | No | Geocoding results, ordered by Nominatim relevance (importance score descending). | |
| truncated | No | True if the result count equals the requested limit (Nominatim may have more). | |
| attribution | No | Required data attribution: Data © OpenStreetMap contributors, ODbL 1.0. | |
| effectiveQuery | No | The effective query sent to Nominatim — the free-form query string, or a reconstructed string from the provided structured address fields. | |
| nextExcludeIds | No | Accumulated exclude tokens (prior excludes plus this page) to pass as exclude_place_ids on the next call, retrieving the next-best matches. Each token is a stable OSM ref (N/W/R + osm_id) when the result carries one, falling back to the Nominatim place_id otherwise. Present only when results were truncated. Nominatim reports no total, so a truncated page is not proof that more matches exist — the following page may come back exhausted (zero results plus a notice). Best-effort: Nominatim ranking is not perfectly stable across calls. | |
| tagSelectionCaveat | No | Standing caveat: tag-based selection lives on the Overpass tools (openstreetmap_query_nearby, openstreetmap_query_bbox, openstreetmap_query_raw), never here. extratags decorates the returned objects rather than selecting them, so a missing tag is not evidence the tag is missing from OpenStreetMap. Present on every successful response. |