Home / GIS and Open Map Data for Beginners

OpenStreetMap Nominatim: The Geocoder, Its Endpoints, and Its House Rules

Street name signs at a Berlin intersection

Photo: Vinay Reddy Sama / Pexels

Every map search box has a geocoder behind it, translating the words people type, a street, a cafe, a town, into the coordinates machines need. For OpenStreetMap, that geocoder is Nominatim, the service that powers the search on openstreetmap.org and also runs as a public API at nominatim.openstreetmap.org, free for anyone to call within its rules. It is one of the most useful and most misused services in the open map world: useful because forward and reverse geocoding solve a hundred real problems, misused because its generosity invites scripts that hammer it like a private server. This guide explains what Nominatim actually offers, the three endpoints that cover nearly every job, and the usage policy that governs the public instance, because with Nominatim the etiquette is not decoration. It is the terms of your access.

Interactive tool

Ask the Geocoder Properly: The Nominatim Checklist

Check off each step as you finish it. Your progress stays on this page.

0 of 8 complete

0% done

What Nominatim Does: Words to Coordinates and Back

Nominatim reads the entire OpenStreetMap database, names, addresses, place hierarchies, and answers two directions of question. Forward geocoding takes a text query, "Brandenburg Gate, Berlin" or a structured address with street, city, and postcode, and returns the matching places with their coordinates, their type, and their full address breakdown. Reverse geocoding takes a coordinate pair and returns the address of the nearest mappable feature, the building, the street, the neighborhood, the city, assembled into the hierarchy a human would recite. Under the hood it is a ranking engine as much as a lookup: it parses your query into probable parts, searches the index for candidates, and orders them by match quality and place importance, which is why a famous landmark beats an obscure street of the same name. Knowing this shapes how you query it. Nominatim rewards specificity, the more of the address you supply, the fewer candidates it must rank, and it punishes vagueness exactly the way a human local would, by answering with the most prominent place that fits and leaving you to notice it is the wrong one. The service is maintained as part of the OpenStreetMap project, and its documentation, not any third-party tutorial, is the authority on its parameters.

The Three Endpoints That Matter

Nearly everything Nominatim does flows through three endpoints on the public service. /search is the forward geocoder: pass a free-form query in the q parameter, or structured fields like street, city, county, state, and country, and add format=jsonv2 to get machine-readable results with coordinates, bounding boxes, and address details. /reverse is the reverse geocoder: pass lat and lon, and receive the address at that point, with a zoom parameter that controls the granularity of the answer, from country level down to a specific building. /lookup fetches known objects directly: if you already hold OpenStreetMap IDs, node, way, or relation identifiers gathered from earlier searches or from the data itself, /lookup returns their geocoding details without a fresh search. Two habits make all three endpoints behave. First, ask for only what you need: limit parameters keep responses small, and addressdetails can be switched off when you only want coordinates. Second, respect the result as data with a license: Nominatim results derive from OpenStreetMap and carry its attribution obligations, which our guide to using OpenStreetMap data covers in full. An endpoint is a door, not a warehouse; if your application needs bulk geocoding of a million addresses, the answer is the next section's topic, your own instance, not a million polite requests.

Street signs at a street corner
Street signs at a street corner

The House Rules: Nominatim's Usage Policy

The public Nominatim service is a shared resource run on donated infrastructure, and its usage policy is short enough to memorize and strict enough to get violators blocked. The headline rule is an absolute maximum of one request per second per application; batch your work, space your calls, and never parallelize around the limit. No autocomplete: the service must not be called on every keystroke as a user types, because that multiplies requests beyond any reasonable reading of the limit; run searches when the user submits, not while they type. Cache your results: geocoding answers for named places change slowly, and caching on your side is both a courtesy and a requirement, with the policy asking you to avoid repeating identical queries against the service. Identify yourself: requests must carry a valid HTTP User-Agent or Referer that identifies your application; generic library defaults are not acceptable identification, and requests without them may be refused. And the policy draws the outer boundary plainly: heavy, systematic, or bulk use does not belong on the public instance at all. None of this is bureaucratic decoration. The service is free because its costs are carried by the OpenStreetMap community, and the policy is the mechanism that keeps a free public geocoder possible. Developers who treat the rules as the specification, designing around one request per second from the first sketch, never meet the enforcement side of them.

When to Run Your Own Nominatim

The escape hatch from every limit above is the software itself: Nominatim is open source, and running your own instance removes the public policy's caps because the costs become yours. Self-hosting is the documented path for bulk geocoding, for autocomplete-driven products, for high-volume applications, and for anyone whose usage would be a burden on the shared service. The honest price of that freedom is real infrastructure work: a Nominatim install consumes the full OpenStreetMap planet file or a regional extract, builds a large PostgreSQL index, and needs meaningful disk, memory, and update maintenance to stay current. For a project geocoding a fixed regional dataset, a country extract keeps that burden sane. The decision rule is straightforward. Occasional lookups, a search box with human-paced traffic, development and testing: use the public service, obey the policy, cache hard. Production volume, bulk datasets, anything that makes you think about the one-request-per-second limit as an obstacle rather than a fact: that thought is the signal to self-host, or to contract with a commercial geocoding provider who runs Nominatim or a comparable engine as a paid service. The OpenStreetMap ecosystem also offers other services for neighboring jobs, routing engines and the editing API among them, and our guide to the OpenStreetMap API maps which service owns which task so you stop asking the geocoder to do them all.

Asking Better Questions: Structured Queries and Result Fields

The difference between a geocoder that seems psychic and one that seems deaf is usually the query, not the engine. Nominatim parses free-form text into address parts, and it rewards queries that arrive pre-parsed. Where your application knows the parts, send them as parts: the structured form of /search accepts street, city, county, state, postal code, and country as separate fields, and a structured query removes the parser's guesswork about which "Springfield" and which "Main Street" you mean. Adding a country code limit to any query is the cheapest accuracy upgrade available, because it forbids the engine from answering with a same-named place on another continent. Read the results with the same care. Each result carries a class and type, a building, a highway, an administrative boundary, that tell you what kind of thing matched, an importance score reflecting the place's prominence, and a bounding box that describes the feature's extent, a point of knowledge in itself: a result whose bounding box spans a province is a province, however precisely its center coordinate is printed. The address breakdown, when you request it, decomposes the match into its hierarchy, and comparing that hierarchy against your expectation is the fastest sanity check in geocoding. A result can be a successful match and the wrong place; the fields are how you catch it before your user does.

What Nominatim Is Not: Boundaries of the Tool

Three neighboring jobs are constantly mistaken for Nominatim's, and naming them saves integrations. Nominatim does not route: it will happily geocode your start and destination, but the path between them belongs to the routing engines covered in our guide to OpenStreetMap routing. Nominatim is not an autocomplete service, and not only because the policy forbids keystroke querying: its ranking is built for considered searches, and products that need type-ahead geography use specialized providers or their own indexed instance tuned for it. And Nominatim is not a bulk data channel: downloading the map itself, in whole or in slices, belongs to the planet files and extracts, while questions across the whole dataset, every pharmacy in a region, belong to the Overpass API. Holding these boundaries is not pedantry. Each service in the OpenStreetMap ecosystem is shaped, and rate-limited, for its own job, and the integrations that survive are the ones that ask each tool only for what it is. Nominatim's job is translation between the world's words and its coordinates. Asked properly, within its rules, it does that job for free, at planetary scale, which remains one of the great bargains of the open web.

Debugging a Bad Result: A Short Field Guide

When Nominatim answers wrongly, the cause is findable, and the order of suspicion matters. First, suspect the query: read what you actually sent, including the limits and filters your code adds silently, because a country restriction inherited from another feature has "broken" more geocoders than any data fault. Second, suspect the match's identity: open the result's class, type, and address hierarchy, and confirm the thing found is the kind of thing sought. Third, suspect the data: look at the place on the map itself, read its tags, and check whether the name you searched exists there in the form you used; a business known locally by a name nobody has mapped cannot be found by that name, and the fix is a contribution, not a workaround. Fourth, suspect your expectations about ranking: importance rewards prominence, and the famous same-named place will outrank your obscure one until the query is bounded by area or country. Work the four in order and nearly every wrong answer resolves into a cause you can fix, in your query, your filters, or the map itself, where the fix improves the commons for everyone who geocodes after you.

Related Guides

Readers working through this topic usually need its closest companions too. These GIS and open map data guides cover the neighboring ground:

Frequently Asked Questions

What is Nominatim in OpenStreetMap?

Nominatim is OpenStreetMap's geocoding service. It powers the search box on openstreetmap.org and runs as a public API that converts addresses and place names into coordinates (forward geocoding) and coordinates back into addresses (reverse geocoding), using the OpenStreetMap database.

What are Nominatim's main endpoints?

Three cover most work: /search for forward geocoding from a text query or structured address fields, /reverse for the address at a given latitude and longitude, and /lookup for fetching geocoding details of OpenStreetMap objects whose IDs you already know.

How fast can I query the public Nominatim service?

At most one request per second, as an absolute maximum under its usage policy. The policy also forbids autocomplete-style querying, requires caching of results, and requires a valid User-Agent or Referer identifying your application. Bulk use belongs on your own instance.

Can I use Nominatim for bulk geocoding a large dataset?

Not on the public instance; the usage policy excludes heavy and systematic use. Nominatim is open source, so the supported route is to install your own instance, sized to a planet file or a regional extract, or to use a commercial provider.

Is Nominatim the same as the OpenStreetMap API?

No. Nominatim is the search and geocoding service. The OpenStreetMap API is the editing interface used to read and write the map data itself, with its own endpoints and limits. They are separate services that happen to share a project.

Photo credits: Vinay Reddy Sama (Pexels); Diogo Miranda (Pexels). Photos are served from this site; follow the credit to the library page for the original.