OpenStreetMap Geocoding Basics

OpenStreetMap is the largest openly licensed map database, and Nominatim is the geocoder built on it. Here is how the data is organised, how to query it well, and the rules that come with the public service.

OpenStreetMap (OSM) is a map of the world built by volunteers and released under an open database licence. It was not designed as a geocoding database: it is a general-purpose store of points, lines and tags. Turning it into something that answers "where is 10 Downing Street?" takes software that understands how OSM records places and addresses. The best-known example is Nominatim, which also powers the address search on openstreetmap.org. This guide explains the data model, the API, and the rules you agree to when you use the public service. If you are new to the topic, start with what geocoding is and come back.

How OSM stores places

Everything in OSM is one of three element types:

Nodes
A single point with a latitude and longitude. A shop, a post box, or a single address point on a building entrance is usually a node.
Ways
An ordered list of nodes. Open ways represent roads and rivers; closed ways represent building outlines, parks and land parcels.
Relations
Groups of nodes, ways and other relations with roles. Administrative boundaries, multipolygon buildings and bus routes are relations.

Meaning comes from tags, free-form key=value pairs. Three families matter most for geocoding:

  • addr:* tags describe a postal address: addr:housenumber, addr:street, addr:postcode, addr:city and others. They can sit on a building outline, on a separate node, or on an entrance. An addr:interpolation way can stand in for a run of house numbers along a street where individual addresses have not been mapped.
  • place=* tags mark named settlements and areas: place=city, town, village, suburb, neighbourhood, hamlet and so on. These are what you hit when you search for a town name rather than a street address.
  • Administrative boundaries are relations tagged boundary=administrative with an admin_level number. The levels mean different things in different countries (level 2 is always the national border; the rest are defined per country on the OSM wiki admin_level page).

A geocoder's main job is to stitch these together. A house number on a building does not normally carry the city or country; Nominatim works those out by finding which street the building belongs to and which boundary polygons contain it. That computed hierarchy is what you see in a result's display_name and address breakdown.

What Nominatim does

Nominatim is open-source software that imports an OSM extract (or the whole planet) into PostgreSQL/PostGIS, builds search indexes and the address hierarchy, and exposes an HTTP API. The OSM Foundation runs a public instance at nominatim.openstreetmap.org; anyone can also run their own.

Data flow from OpenStreetMap contributors through Nominatim to a client application, with a caching proxy in between OSM database nodes, ways, relations Nominatim import, index, rank HTTP API /search /reverse Your server proxy + cache, 1 req/s Client shows attribution JSON results edited by contributors
OSM edits flow into Nominatim's database; your application should talk to Nominatim through its own server-side cache rather than straight from every browser.

Forward search: /search

The search endpoint takes either a free-form query in q or structured fields (street, city, county, state, country, postalcode, amenity), not both. The parameters worth knowing:

ParameterWhat it does
format=jsonv2Machine-readable JSON. On the public server, omitting format sends you to the web UI instead.
countrycodesHard filter by ISO 3166-1 alpha-2 codes, comma-separated, e.g. gb,ie.
viewboxA box given as x1,y1,x2,y2 (longitude, latitude of two opposite corners). On its own it only boosts results inside it.
bounded=1Turns viewbox into a strict filter.
limitMaximum results; default 10, capped at 40.
addressdetails=1Adds an address object breaking the result into house number, road, suburb, city, postcode, country and so on.

A well-formed request for a single UK address looks like this:

https://nominatim.openstreetmap.org/search?q=10+Downing+Street,+London
  &countrycodes=gb&limit=1&addressdetails=1&format=jsonv2

To keep a search inside Greater London you could add viewbox=-0.51,51.29,0.33,51.69&bounded=1. That box is written west, south, east, north, the same order the bounding box explorer exports. Be careful in the other direction: each result's boundingbox array comes back as south, north, west, east (min lat, max lat, min lon, max lon), and lat/lon are strings, not numbers. Mixing up these orders is one of the most common Nominatim bugs; the bounding boxes guide covers the conventions in detail.

Reverse geocoding: /reverse

The reverse endpoint takes lat and lon in WGS84 and returns exactly one object: the closest suitable OSM feature, not a guaranteed postal address for that exact spot. The zoom parameter (0–18, default 18) sets the level of detail: 18 asks for a building, 16 for major streets, 10 for a city, 3 for a country. For the Eiffel Tower you would send:

https://nominatim.openstreetmap.org/reverse?lat=48.8584&lon=2.2945
  &zoom=18&format=jsonv2

If you only need "which city is this?", asking for zoom=10 is both faster to interpret and less likely to return a misleading nearby house number. The difference between the two directions is explained in forward vs reverse geocoding.

The public Nominatim usage policy

The public server runs on donated resources, and its usage policy is strict. The main points:

  • An absolute maximum of 1 request per second, counted per application, so the total across all your users must stay under it. Scripts that run for more than a day or on a regular schedule are held to 4 requests per minute.
  • Identify yourself with a valid HTTP User-Agent or Referer naming your application. A library's default user agent does not count.
  • No heavy or bulk use. Small one-off bulk jobs may be tolerated if they run single-threaded on one machine, and results must be cached. Systematic queries, such as reverse-geocoding a grid or compiling every postcode in a country, are banned; download the data instead.
  • Cache. Caching is required for bulk work and strongly recommended for apps, ideally behind your own proxy.
  • No client-side autocomplete. Search-as-you-type against the public server is explicitly forbidden.
  • No personal or confidential data in queries, and you must be able to switch the service off if asked.

Some quick arithmetic shows why these rules shape architecture. At 1 request per second, 1,000 uncached addresses take at least 1,000 seconds, about 17 minutes. Under the 4-per-minute rule for scheduled jobs, the same 1,000 take 250 minutes. Anything recurring or larger belongs on a self-hosted instance or a commercial provider.

Licence and attribution

OSM data is published under the Open Database License (ODbL). In practice that means two things for geocoding users. First, you must credit the source wherever results are shown, using the wording "© OpenStreetMap contributors" with a link to the OSM copyright page. Second, ODbL is share-alike: if you build and publicly use a database derived from OSM, that derived database must be offered under the same licence. Whether a particular set of geocoding results counts as a derivative database depends on how you use it, and the OSM Foundation publishes a community guideline on geocoding for exactly this question. Read them before you store geocodes at scale alongside other data.

Licensing was a deliberate design choice for the original 2012 OpenGeocoder. That project kept its data entirely separate from OSM so every record could stay in the public domain; as its creator noted, deriving the data from OSM would have carried OSM's share-alike licence rather than leaving it public domain. The roughly 1,890 place-to-bounding-box records it collected are preserved in the OpenGeocoder 2012 Archive, and the history is on the about page. Today's tools are different: their results come from Nominatim and are OSM data, so ODbL and the attribution requirement apply to them. This site is independent and is not affiliated with OpenStreetMap or the OSM Foundation.

Coverage gaps

OSM's road network and named places are very good in most of the world. Address points are another story. Their density depends on whether a government released open address data that was imported, or whether local mappers added house numbers by hand. In many countries a large share of buildings carry no addr:housenumber at all. When Nominatim cannot find the number, it falls back to the street or to an interpolation line, and the result can be tens or hundreds of meters from the real door.

Check what you got back before trusting it. The addresstype and type fields, and whether the address object includes a house_number, tell you whether you matched a building, a street or just a town. The place name search shows several candidates with type and importance, which helps you spot a weak match.

Alternatives to the public server

Several open-source projects geocode OSM data, each with different trade-offs:

  • Self-hosted Nominatim. Same software and API, no shared rate limit. A country extract runs on modest hardware; the full planet needs a large server and a long initial import.
  • Photon, built on a search engine index of Nominatim-processed data, is designed for search-as-you-type and typo tolerance. A public demo instance exists, with its own fair-use limits.
  • Pelias is a modular geocoder that can combine OSM with other open sources such as OpenAddresses, Who's On First and GeoNames, which can fill some address gaps.

Commercial geocoding APIs are a further option, often with proprietary address data and service guarantees. None of these choices is universally best; the right one depends on volume, required precision, licensing constraints and whether you can operate a server yourself. For a broader comparison of what to look for, see the geocoding API guide.

Key takeaways

  • OSM stores places as nodes, ways and relations; geocoding relies on addr:* tags, place=* tags and administrative boundary relations.
  • Nominatim's /search and /reverse endpoints cover most needs; use format=jsonv2, countrycodes, viewbox/bounded, limit and addressdetails to get tighter results.
  • The public server allows at most 1 request per second, requires an identifying User-Agent or Referer, forbids bulk use and client-side autocomplete, and expects caching.
  • Results are ODbL data: show "© OpenStreetMap contributors" and understand share-alike before storing them at scale.
  • Address coverage varies widely by country, so always check which level a result matched.