Nominatim Explained

This article extends the Geocoding sub-hub with a focused dive on the dominant open-source geocoder. Companion to /learn/what-is-geocoding (the pillar) and /learn/forward-vs-reverse-geocoding.

What Nominatim is

Nominatim is the open-source geocoder for OSM data. It accepts:

• Forward geocoding (search): input a human-readable place description ("123 Main St, Anytown" or "Eiffel Tower"); return coordinates plus structured metadata.
• Reverse geocoding: input latitude/longitude; return the address or place name at that location.

It returns results as JSON, XML (legacy), or GeoJSON. A simple REST API (e.g., GET /search?q=... or GET /reverse?lat=...&lon=...) is the standard interface.

The name Nominatim is Latin for “by name” — appropriate for a service that finds places by their names.

Origin and stewardship

Brian Quinion (2010–ish)

Brian Quinion built the initial Nominatim around 2010 as the search engine behind OSM.org's search box. Before Nominatim, OSM.org used external services (Google search initially) for geocoding, which was awkward and not aligned with OSM's open philosophy.

Quinion's Nominatim was a substantial engineering contribution: it required custom database schemas (beyond what raw OSM data provided), token-based matching, and place-ranking algorithms. The code was C and PHP — a typical web-server stack of the era.

Sarah Hoffmann and OSMF stewardship

Sarah Hoffmann took over primary maintenance in the late 2010s and is now the principal maintainer. She works under the OSMF (OpenStreetMap Foundation) with substantial contribution from the broader community.

Hoffmann led the 2024 Python rewrite (see below), modernizing the codebase. She also writes extensively about Nominatim at her technical blog.

The OSMF connection

The OpenStreetMap Foundation provides:

• Public service hosting at nominatim.openstreetmap.org.
• Funding for development work.
• Legal framework (GPL-2.0 licensing).
• Community standards (usage policies, quality).

The OSMF Nominatim Usage Policy (operations.osmfoundation.org/policies/nominatim/) governs the public service.

Architecture

Nominatim consists of:

PostgreSQL/PostGIS database

The data foundation. Nominatim doesn't use the raw OSM database — it transforms OSM data into search-optimized schemas:

• placex: the canonical place table, with hierarchical relationships (a building is in a street, which is in a city, which is in a state).
• location_property: searchable place properties.
• address_* tables: address components indexed for fast lookup.
• search_name tables: tokenized place names for full-text search.

The transformation is the import step — a one-time process that takes hours to days depending on data size.

Import workflow

OSM Planet (PBF format)
  ↓ osm2pgsql
PostgreSQL with OSM tables
  ↓ Nominatim import script
PostgreSQL with Nominatim-specific tables
  ↓
REST API server

The import script applies hundreds of SQL transformations to build the search index. Common options:

• Global Planet import: 1-3 days on commodity hardware (32-64 GB RAM).
• Regional extract: hours.
• City extract: minutes.

REST API

The public-facing service. Operates on top of the database with endpoints:

• GET /search?q=... — forward geocoding.
• GET /reverse?lat=X&lon=Y — reverse geocoding.
• GET /lookup?osm_ids=... — OSM-ID-based lookup.
• GET /status — health check.

Optional request parameters:

• format — JSON / XML / GeoJSON.
• addressdetails=1 — include structured address.
• extratags=1 — include OSM tags.
• polygon_geojson=1 — include polygon geometry.
• bounded=1, viewbox=... — restrict results to a bounding box.
• accept-language — preferred result language.

Updates

Once the initial import is done, diff updates keep the database current:

• Download daily or hourly diffs from planet.openstreetmap.org.
• Apply via Nominatim's update scripts.
• Reindex the affected places.
• Re-tokenize names where changed.

Daily updates are typical; hourly or minutely is possible with more operational effort.

How the geocoder works

A simplified pipeline for a forward-geocoding query:

1. Tokenization

The input query is split into tokens (words, numbers). “123 Main Street, Springfield IL” becomes [“123”, “Main”, “Street”, “Springfield”, “IL”].

2. Token classification

Each token is classified:

• House number (numeric).
• Street prefix/suffix (“Street”, “Avenue”, “Boulevard”).
• Place name (“Springfield”).
• Administrative code (state abbreviation “IL” → Illinois).

3. Place lookup

Nominatim queries the indexed name tables for matches. The hierarchical structure helps: “IL” → Illinois (admin level 4); “Springfield” in Illinois (vs other Springfields); “Main Street” within Springfield IL; house number 123 within Main Street.

4. Ranking

Multiple candidate matches are ranked by:

• Place importance (Springfield IL is more important than smaller Springfields).
• Match quality (how completely the query matches the place).
• Address-component match (matching all parts beats matching only some).

5. Address composition

The top result is returned with structured address components (house number, street, city, state, country) and a bounding polygon if available.

The algorithm has many refinements (synonym handling, typo tolerance via trigram matching, language support); the sketch above is the conceptual flow.

The 2024 Python rewrite (Nominatim 5)

For most of its life, Nominatim was implemented in C and PHP:

• C for the import processing (performance- critical).
• PHP for the REST API server.
• SQL stored procedures for the search logic.

This worked but constrained development:

• C/PHP expertise is increasingly rare among open-source contributors.
• Debugging across languages was painful.
• Adding features required cross-language coordination.
• Modern Python ecosystem (async I/O, type hints, testing tools) was missing.

Nominatim 5.0, released in 2024, is a full Python rewrite:

• Python for the search backend and API.
• SQL (no longer stored procedures, but application-level queries).
• API-compatible with previous versions.
• Comparable performance after optimization.

The rewrite makes Nominatim easier to extend, contribute to, and debug. Sarah Hoffmann led the work over 2022–2024.

For users, the upgrade is transparent (API unchanged). For developers wanting to contribute or extend Nominatim, the Python codebase is dramatically more accessible.

The public service

The OSM Foundation operates nominatim.openstreetmap.org as a free public service. Usage policy:

• Maximum 1 request per second per IP.
• User-Agent header required identifying the application.
• HTTP referer encouraged (helps OSMF understand usage).
• Result caching encouraged (don't repeat queries).
• No bulk geocoding (don't scrape).
• No commercial production use without explicit arrangement.
• Attribution required (“Powered by Nominatim” or similar).

The service is intended for development, testing, hobby projects, small-scale tools. Production traffic must use self-hosted Nominatim or a commercial provider.

Violators face IP-level blocking. The OSMF's operations team actively monitors for abuse.

Self-hosting

For production use, self-hosting is the standard path:

Hardware

| Scope | RAM | SSD | CPU | | ----- | --- | --- | --- | | Global Planet | 64 GB | 1.5 TB | 8 cores | | Regional (e.g., Europe) | 32 GB | 400 GB | 4 cores | | Single country | 16 GB | 200 GB | 4 cores | | Single city | 8 GB | 50 GB | 2 cores |

Modern servers (cloud instances or dedicated boxes) easily meet these specs. The cost: $200-1000/month for global; less for regional.

Software

• PostgreSQL 14+ with PostGIS 3+.
• Nominatim 5.0+ (latest Python version).
• Optional: Docker (mediagis/nominatim-docker is widely used).

Setup workflow

# 1. Provision hardware, install OS

# 2. Install PostgreSQL + PostGIS
apt install postgresql-14 postgresql-14-postgis-3

# 3. Install Nominatim
pip install nominatim-api

# 4. Download OSM data
wget https://planet.openstreetmap.org/pbf/planet-latest.osm.pbf

# 5. Run import (takes 1-3 days for global)
nominatim import --osm-file planet-latest.osm.pbf

# 6. Start the REST API server
nominatim serve

# 7. Schedule daily diff updates
crontab -e
# Add: 0 4 * * * nominatim update

Detailed guides at nominatim.org/release-docs/latest/.

Docker

For most users, Docker is the easiest path:

docker run -it -p 8080:8080 -e PBF_URL=... mediagis/nominatim:5.0

The container handles the entire workflow. Persistent volumes hold the database; the container runs the API.

Commercial Nominatim hosting

Several companies offer commercial Nominatim hosting — Nominatim with SLAs, support, and sometimes additional features:

Geoapify

Hosted Nominatim with rate-limited free tier (3,000 req/day) and paid plans for production.

LocationIQ

Hosted Nominatim with free tier (5,000 req/day) and paid plans up to enterprise.

MapTiler Geocoding

MapTiler offers Nominatim-based geocoding as part of its broader mapping services.

Self-hosted SaaS

Some companies offer fully managed Nominatim installations: you specify the region/Planet extract, they host it and provide an API endpoint.

The commercial options are convenient if you want Nominatim's open-source ethos without operating the infrastructure.

Quality and limitations

Strengths

• Open source end-to-end (software + data).
• Globally available wherever OSM is mapped.
• Free at scale (when self-hosted).
• Comprehensive in well-mapped regions (Western Europe, North America, Australia, parts of Asia).
• No vendor lock-in.
• Customizable — you can modify the import pipeline, add custom layers, integrate with enterprise data.

Weaknesses

• POI coverage is variable; commercial geocoders with proprietary POI databases (Google, Mapbox, HERE) often beat OSM POI completeness in some countries.
• Autocomplete UX is less polished than Mapbox or Google's commercial offerings.
• Sparse-region quality — geocoding in sub-Saharan Africa, some Central Asian regions, parts of Latin America is limited by OSM coverage.
• Operational complexity — self-hosting requires PostgreSQL administration, monitoring, updates.
• Address parsing is good but not as sophisticated as specialist services like SmartyStreets (US) or libpostal.

When to choose Nominatim

• Open-source/open-data projects.
• Cost-sensitive production (high volumes where per-query commercial pricing adds up).
• Privacy-sensitive (no third-party API involvement).
• Custom geocoding requirements (custom data layers, modified algorithms).
• Mainstream-region focus (Western Europe, North America, well-mapped countries).

When to choose alternatives

• Best-in-class accuracy in all regions: Google, Mapbox.
• Premium POI database: Google.
• Strong autocomplete UX: Mapbox v6.
• US address-parsing specialty: SmartyStreets.
• Logistics use case: HERE.

Licensing

Nominatim is dual-licensed:

• Software (Nominatim itself): GPL-2.0 — a copyleft license. You can use, modify, and redistribute; modifications must be GPL-2.0 too.
• Data (OSM): ODbL — share-alike for derivative databases (see /learn/openstreetmap-explained).

For most users, the licensing is unproblematic:

• Using Nominatim as a service (REST API client): no licensing concerns; just attribute.
• Embedding Nominatim in a server: GPL-2.0 applies to the server modifications; the API consumers don't inherit GPL.
• Modifying Nominatim: modifications must be GPL-2.0; redistribute or open-source them.

The combination of GPL software + ODbL data makes Nominatim truly open end-to-end — no vendor can take it proprietary; no upstream license change can remove your rights.

Comparison with the broader landscape

The geocoder landscape:

| Geocoder | License | Data source | Use case | | -------- | ------- | ----------- | -------- | | Nominatim | GPL-2.0 + ODbL | OSM | Open source, self-host | | Mapbox Geocoding | Proprietary | Mapbox-curated (OSM + others) | Production-grade with v6 confidence | | Google Geocoding | Proprietary | Google maps data | Best global accuracy, premium price | | HERE Geocoding | Proprietary | HERE proprietary | Strong in EU, logistics-focused | | Esri World Geocoding | Proprietary | Esri-curated | ArcGIS ecosystem | | Amazon Location | Proprietary | HERE + Esri backends | AWS-integrated | | SmartyStreets | Proprietary | US-specific data | US address validation | | Geoapify, LocationIQ | Proprietary services | Hosted Nominatim + commercial | Hosted open-source |

Nominatim is the only fully open option; the others are commercial services with various data sources.

Common misconceptions

“Nominatim is the same as nominatim.openstreetmap.org.” They're related but distinct. Nominatim is the software; nominatim.openstreetmap.org is one (free, restricted) hosted instance run by OSMF. You can run your own instance with no restrictions.

“Nominatim only works for OSM data.” Primarily, but you can augment OSM data with custom layers in your Nominatim installation. For example, add a private address database alongside OSM data; Nominatim's queries can include both sources.

“Nominatim is slow.” Self-hosted Nominatim is fast — typically 10-100 requests per second on commodity hardware. The OSMF's 1 req/ sec public-service limit is a policy not a technical limit.

“The 2024 Python rewrite broke compatibility.” No — Nominatim 5.0 maintains REST API compatibility with 4.x. Application code calling Nominatim 4.x continues working with 5.0. Internal changes (database schema, configuration) require migration.

“Nominatim requires constant tuning.” After initial setup and import, Nominatim runs with minimal tuning. Daily diff updates are automated; the API is stable. The operational burden is comparable to running a PostgreSQL database, which it essentially is.

“Self-hosting Nominatim violates licenses.” No — both GPL-2.0 (software) and ODbL (data) explicitly permit self-hosting, modifications, and any non-violating distribution. The licenses are designed to encourage exactly this use.

“Nominatim and Photon are the same.” Photon is a separate geocoder built on Elasticsearch rather than PostgreSQL, also using OSM data. Photon focuses on autocomplete and “starts with” matching; Nominatim is more general-purpose. Both are open-source and OSM-based but architecturally distinct. For autocomplete-heavy applications, Photon is often preferred; for general geocoding, Nominatim.

“You can't use OSM Nominatim commercially.” You can for the software (GPL-2.0 allows commercial use as long as modifications are open) and for the data (ODbL allows commercial use with attribution and share- alike for derivative databases). The public OSMF service has commercial-use restrictions; your own self-hosted Nominatim has no such restrictions.

“Nominatim doesn't support modern features like autocomplete.” Modern Nominatim does support autocomplete via specific endpoints and parameters. Photon offers better-tuned autocomplete UX, but Nominatim is functional. For production autocomplete on OSM data, Photon + Nominatim hybrid is a common pattern.

“Geocoding is privacy-neutral.” It's not always — sending user-typed queries to a third-party API can expose sensitive information (medical addresses, personal locations). Self-hosted Nominatim keeps queries on-premises, eliminating that third-party exposure. For privacy-sensitive applications, this is a major advantage of self-hosting.

“Nominatim is only for OSM project internal use.” Not anymore — Nominatim is used by countless external projects: open-source applications, research projects, commercial services, government applications. The nominatim.openstreetmap.org service is the internal-OSM-project use; self-hosted Nominatim is for everyone else.