Getting Started with Nominatim Geocoding — Nominatim Geocoding API

When to use this API

When you need to convert between place names and coordinates — forward geocoding (name to lat/lon) or reverse geocoding (lat/lon to address). Built on OpenStreetMap data, so it handles addresses, POIs, and natural features worldwide without an API key. Nominatim is surprisingly good at structured address searches (street + city + country) when you have the components but not the coordinates, and at reverse geocoding remote coordinates where commercial APIs return empty results. For routing, satellite imagery, or real-time map tiles, look elsewhere; this is strictly a geocoding service.

Finding a specific place by name

"What are the coordinates of Big Ben?" The /search endpoint accepts a free-form q parameter and returns matching OSM objects ranked by importance. Big Ben is a good test case because the name is ambiguous — and the ambiguity surfaces immediately.

curl "https://nominatim.openstreetmap.org/search?q=Big+Ben&format=json&limit=1" | head -c 10000

[{
  "place_id": 24125235,
  "osm_type": "node",
  "osm_id": 5288252680,
  "lat": "-29.4844624",
  "lon": "151.6580014",
  "class": "natural",
  "type": "peak",
  "name": "Big Ben",
  "display_name": "Big Ben, Glen Innes Severn Council, New South Wales, Australia",
  "importance": 0.16
}]

The first result is a mountain peak in New South Wales, not the clock tower in London. Nominatim ranks by OSM importance score, and this particular peak outranks the Elizabeth Tower (Big Ben's actual building name) in the index. The fix is disambiguation: add countrycodes=gb to limit results to the UK, or use a structured query with city=London and countrycodes=gb. Without narrowing, assume the top result may not be the place your user means.

The coordinates for Big Ben in the OSM database point to a mountain peak in New South Wales, Australia (lat -29.4845, lon 151.6580). If you meant the clock tower in London, add countrycodes=gb to your search — without it, Nominatim may return a different feature with the same name.

Getting the address at a specific coordinate

"What address is at coordinates 48.8583, 2.2944?" The /reverse endpoint takes lat and lon and returns the nearest addressable OSM object at that point. These coordinates are right next to the Eiffel Tower in Paris — but reverse geocoding doesn't return landmarks, it returns addresses.

curl "https://nominatim.openstreetmap.org/reverse?lat=48.8583&lon=2.2944&format=json" | head -c 10000

{
  "place_id": 89332793,
  "osm_type": "node",
  "osm_id": 3134285382,
  "lat": "48.8582474",
  "lon": "2.2944389",
  "class": "amenity",
  "type": "bar",
  "name": "",
  "display_name": "Avenue Gustave Eiffel, Quartier du Gros-Caillou, Paris 7e Arrondissement, Paris, Île-de-France, 75007, France",
  "address": {
    "road": "Avenue Gustave Eiffel",
    "quarter": "Quartier du Gros-Caillou",
    "city": "Paris",
    "state": "Île-de-France",
    "postcode": "75007",
    "country": "France",
    "country_code": "fr"
  }
}

The result is a bar on Avenue Gustave Eiffel, not the Eiffel Tower itself. Reverse geocoding finds the nearest addressable feature at the exact point you give it — a street, a building, a POI — not the famous landmark that happens to be nearby. The zoom parameter controls the level of detail: zoom=18 (building level, the default) returns the nearest small feature; zoom=10 returns the city; zoom=0 returns the country. If you want "what city am I in?", start with a low zoom value, not the default.

The address at coordinates 48.8583, 2.2944 is Avenue Gustave Eiffel in the Quartier du Gros-Caillou, Paris 7e Arrondissement, Île-de-France, France (postcode 75007). The nearest OSM feature at that exact point is classified as a bar on Avenue Gustave Eiffel — reverse geocoding returns the street address, not the nearby Eiffel Tower landmark.

Looking up an OpenStreetMap object by its ID

"What address corresponds to OSM way 504484402?" Every Nominatim result includes osm_type and osm_id. The /lookup endpoint resolves those IDs back to full address details — useful when you've stored an OSM reference from a previous search and need to refresh it.

curl "https://nominatim.openstreetmap.org/lookup?osm_ids=W504484402&format=json" | head -c 10000

[{
  "place_id": 61617211,
  "osm_type": "way",
  "osm_id": 504484402,
  "lat": "46.7833422",
  "lon": "13.6589955",
  "category": "building",
  "type": "residential",
  "display_name": "48, Hauptstraße, Döbriach, Radenthein, Bezirk Spittal an der Drau, Kärnten, 9873, Österreich",
  "address": {
    "house_number": "48",
    "road": "Hauptstraße",
    "village": "Döbriach",
    "town": "Radenthein",
    "county": "Bezirk Spittal an der Drau",
    "state": "Kärnten",
    "ISO3166-2-lvl4": "AT-2",
    "postcode": "9873",
    "country": "Österreich",
    "country_code": "at"
  }
}]

This is a residential building at 48 Hauptstraße in the village of Döbriach, Austria. The address object shows the full Austrian administrative hierarchy — village and town are separate fields, the county is a Bezirk, and the state is a Bundesland with its ISO 3166-2 subdivision code (AT-2 for Kärnten/Carinthia). European addresses have more depth than US-style street/city/state/zip, and Nominatim preserves the full chain. The osm_ids parameter accepts comma-separated IDs with a type prefix: N for nodes (points), W for ways (lines and polygons), R for relations (multipolygons and administrative boundaries). Up to 50 IDs per request.

OSM way 504484402 is a residential building at 48 Hauptstraße, Döbriach, Radenthein, Bezirk Spittal an der Drau, Kärnten 9873, Austria. The address shows the full Austrian hierarchy — village (Döbriach), town (Radenthein), county (Bezirk Spittal an der Drau), state (Kärnten/AT-2) — which is deeper than typical US addressing.

Pitfalls

Rate limit: 1 request per second on the public server. Burst above that and you get 429 responses. For higher throughput, run your own Nominatim instance.
Default response format is XML for /reverse and /lookup. Always add format=json or format=jsonv2 unless you specifically want XML. The /search endpoint defaults to jsonv2, so this inconsistency catches you off guard when you switch endpoints.
lat and lon are strings in the response, not numbers. Parse them as floats before doing distance calculations.
Place name searches are ambiguous without narrowing. "Big Ben" returns an Australian mountain; "Springfield" returns dozens of results across multiple countries. Always pair q= with countrycodes, viewbox, or structured parameters (city, state, country).

One-line summary for the user

I can convert between place names and coordinates using OpenStreetMap's Nominatim service — forward search, reverse lookup, and OSM ID resolution — with no key required, but disambiguation is your responsibility and the public server is rate-limited to 1 request per second.