Getting Started with Nominatim

← Nominatim API

When to use this API

When you need to turn a place name into coordinates, or coordinates into a place name — geocoding and reverse geocoding over OpenStreetMap data. Nominatim is surprisingly good at disambiguation: it handles the "which Springfield?" problem with structured queries, country filters, and viewport biasing, all in a single unauthenticated call. For routing, elevation profiles, or tile rendering, look elsewhere — this is a geocoder, not a general-purpose map service.

Finding a specific place by name

"Where exactly is Svalbard?" Svalbard is a good first example because it sits at an extreme latitude (78 N), its OSM record crosses the place_rank boundary between "territory" and "island" depending on how you query it, and its address object has an unusual structure — no state field, no postcode, just country and country_code. That's a signal you're dealing with a territory that doesn't fit the normal administrative hierarchy.

curl "https://nominatim.openstreetmap.org/search?q=Svalbard&format=jsonv2&addressdetails=1&limit=1" | head -c 10000

[
  {
    "place_id": 253394,
    "osm_type": "relation",
    "osm_id": 1339791,
    "lat": "77.5536042",
    "lon": "23.6705311",
    "name": "Svalbard",
    "display_name": "Svalbard, Norge",
    "category": "place",
    "type": "archipelago",
    "place_rank": 12,
    "importance": 0.54,
    "addresstype": "archipelago",
    "address": {
      "country": "Norge",
      "country_code": "no"
    },
    "boundingbox": ["74.0", "81.0", "10.0", "35.0"]
  }
]

The type is archipelago — a classification most geocoding APIs don't surface. The addresstype mirrors it, which means the address object won't have the usual city / state / postcode keys you'd expect from a typical result; it collapses to just country and country_code. The country_code is no (Norway) despite Svalbard having a separate treaty status — the API follows OSM's administrative tagging, not geopolitical nuance. The boundingbox spans 7 degrees of latitude (74 to 81 N), which is enormous — a clue that "Svalbard" as an OSM entity covers the entire archipelago, not just the main island.

Svalbard is at roughly 77.55 N, 23.67 E — well above the Arctic Circle. It's classified as an archipelago under Norway (country code no), though it has a separate international treaty status. Its bounding box spans from 74 to 81 degrees north latitude, covering the entire island group.

Reverse geocoding a remote coordinate

"What's at 64.14 N, 21.94 E?" Reverse geocoding is where Nominatim shines for "where am I?" questions. This coordinate lands in Iceland, but not in Reykjavik — it's in Selfoss, a town most people outside Iceland have never heard of, despite being the largest town in South Iceland.

curl "https://nominatim.openstreetmap.org/reverse?lat=64.14&lon=21.94&format=jsonv2&addressdetails=1" | head -c 10000

{
  "place_id": 185427,
  "osm_type": "node",
  "osm_id": 8496388,
  "lat": "64.13925",
  "lon": "21.93886",
  "name": "Selfoss",
  "display_name": "Selfoss, 800 Árnessýsla, Suðurland, Ísland",
  "category": "place",
  "type": "town",
  "place_rank": 18,
  "importance": 0.375,
  "addresstype": "town",
  "address": {
    "town": "Selfoss",
    "county": "Árnessýsla",
    "state_district": "Suðurland",
    "state": "Suðurland",
    "postcode": "800",
    "country": "Ísland",
    "country_code": "is"
  },
  "boundingbox": ["64.12925", "64.14925", "21.92886", "21.94886"]
}

Icelandic addresses have a county field (Árnessýsla) that most European addresses lack — Iceland still uses the old sýsla (county) division. The postcode is just three digits (800), unlike the four- or five-digit postcodes common elsewhere. The state and state_district are both Suðurland here, which means the OSM data doesn't differentiate between those two administrative levels for this location. The display_name concatenates everything in Icelandic (Ísland, not "Iceland"), which is correct — Nominatim returns local-language names unless you pass accept-language.

The coordinate 64.14 N, 21.94 E is in Selfoss, a town in the Árnessýsla county of South Iceland (Suðurland). Its postcode is 800. The name and address are returned in Icelandic — the local language — by default.

Looking up a place by its OSM ID

"What is OpenStreetMap relation R2963542?" The /lookup endpoint resolves OSM object IDs directly — no text search, no coordinates. It's the fastest path when you already have an OSM ID (from a map click, a URL, or a previous response's osm_type+osm_id). The prefix is N for nodes, W for ways, R for relations.

curl "https://nominatim.openstreetmap.org/lookup?osm_ids=R2963542&format=jsonv2&addressdetails=1" | head -c 10000

[
  {
    "place_id": 193655,
    "osm_type": "relation",
    "osm_id": 2963542,
    "lat": "5.3526251",
    "lon": "-4.0087676",
    "name": "Abidjan",
    "display_name": "Abidjan, Abidjan, Côte d'Ivoire",
    "category": "boundary",
    "type": "administrative",
    "place_rank": 14,
    "importance": 0.7,
    "addresstype": "city",
    "address": {
      "city": "Abidjan",
      "state": "Abidjan",
      "country": "Côte d'Ivoire",
      "country_code": "ci"
    },
    "boundingbox": ["5.25", "5.48", "-4.22", "-3.85"]
  }
]

The category is boundary and type is administrative — not place/city. That's because this OSM relation defines the administrative boundary of the city of Abidjan, not a point label. The addresstype field (city) is the bridge: it tells you that despite being a boundary/administrative object, the address-level role is "city." This distinction matters — category and type describe the OSM geometry, while addresstype describes the human-facing role. When the user asks "what is this place?", trust addresstype and name, not category.

OSM relation R2963542 is Abidjan, the economic capital of Côte d'Ivoire, located at approximately 5.35 N, 4.01 W. It's classified as an administrative boundary in OSM terms but functions as a city in address context.

Pitfalls

One-line summary for the user

I can geocode place names to coordinates, reverse-geocode coordinates to addresses, and look up OpenStreetMap objects by ID using Nominatim — all unauthenticated, one call per second, and it returns local-language names by default.