Nominatim geocoder is a free, open-source address search engine that you can run on your own computer, even without an Internet connection! And this is one of few solutions which allows you to do high volume, batch geocoding for any address on our planet on budget.
Nominatim can do both forward and reverse geocoding and supports all countries, languages and address formats in the world. It is developed and maintained by the OpenStreetMap community and used as a default geocoding service for OSM data.
Nominatim pros and cons
Sounds good so far? Great!
But before you invest hours and days into getting Nominatim up and running, let’s have a quick overview of its strong and weak sides, and make sure it can be a good fit for your needs.
| PROS | CONS |
|---|---|
| Free! No license fees, and very few limitations (you need to adhere to ODBL license) | You need to invest your time and resources to get it up and running |
| Based on rich OSM and Wikipedia data, collected and updated by millions of volunteers, companies, and organizations around the world | Most address records are not authoritative, coverage can be spotty and some data can be obsolete or even incorrect |
| Community project - good activity and number of articles and configuration instructions in Internet | No guarantees, no support, no SLA; incomplete and often outdated instructions |
| Open source, you can extend or fix any part of it | Sometimes code is your only documentation |
| Works on your servers, also offline | You need (powerful) servers and somebody who can maintain them |
| Very configurable queries | You need to know which options to use to get results you want |
To be fair, all Nominatim weaknesses are common for any big, community-driven, open-source project. And we at Geoapify have extensive experience with Nominatim and will be happy to support you.
Geocoding addresses with Nominatim
Nominatim accepts geocoding requests on the /search endpoint, in one of two exclusive modes - free-form and structured search.
Free-form address search
Free-form address query requires “q” parameter, like
In that mode, Nominatim supports special phrases like “in”, “near”
Structured address search
Alternatively, you can use a structured search, where address defined by a combination of:
street=<number> <name>
city=<city>
county=<county>
state=<state>
postalcode=<code>
Nominatim structured geocoding is not as useful as it could be, because it doesn’t guarantee that search will be performed with requested granularity and prevents Nominatim from applying some internal geocoding heuristics. It also less flexible and does not support Nominatim's special phrases.
We can only recommend to use it as a workaround for scenarios where Nominatim cannot correctly parse the address.
Filtering by location
If you know that results should belong to a specific country or area, it is highly recommended to narrow down search results with countrycodes=<comma-separated list of country codes> and viewbox=<lon1>,<lat1>,<lon2>,<lat2> parameters.
By default "viewbox" parameter works as location bias and includes results both inside and outside of provided bounding box.
Adding "bounded=1" parameter instructs Nominatim to return only results included in viewbox.
Search by type and amenity
Nominatim has only very limited support for places search. In most cases, you will get better and more reliable results with other services, for instance, Geoapify Places API or Overpass. But for simple cases, Nominatim can be good enough.
There are three ways to perform a search by type and amenity in Nominatim:
- Using special phrases like "in" or "near",
for example
/search?q=pub+in+new+york - Using search bounded by the "viewbox" together with "amenity" parameter,
for example, searching for pubs in Manhattan area
/search?viewbox=-74.02631,40.73022,-73.96202,40.69769&bounded=1&amenity=pub - Using search bounded by the "viewbox" together with place type in square brackets,
for example /search?q=[pub]&viewbox=-74.02631,40.73022,-73.96202,40.69769&bounded=1
You can find an extensive list of supported place types and amenities on OpenStreetMap wiki.
Reverse geocoding with Nominatim
Nominatim can find and return addresses corresponding to a given latitude and longitude coordinate. For that, you need to use /reverse endpoint together with "lat" and "lon" parameters.
Results granularity
Nominatim currently does not support filtering by object type nor specific geocoding granularity like "city", "administrative area" or "street". But there are several workarounds.
First, Nominatim /search endpoint accepts the (undocumented) "featuretype" parameter with one of the following values: "country", "state", "city", and "settlement" (anything below country and above the street level).
Then, reverse geocoding supports "zoom" parameter and returns the results of different granularity depending on its value:
| ZOOM | RESULT GRANULARITY |
|---|---|
| 3 | country |
| 5 | state |
| 8 | county |
| 10 | city |
| 14 | suburb |
| 16 | major streets |
| 17 | major and minor streets |
| 18 | building |
In the case of forward geocoding, you will need to do the second call to reverse geocoding with previously looked up coordinates and desired zoom level.
Another alternative requires a call to /details endpoint together with addressdetails=1 parameter and “place_id” matching the id of the previously geocoded result. This way you get full hierarchy from given the place up to country level, including administrative and postal code boundaries.
Output formats
By default Nominatim returns a formatted HTML page, that is ready to be displayed in the browser. If you need a machine-readable response format, you will need to add the "format" parameter and set it to one of "xml", "json", "geojson" and "geocodejson" output formats.
We recommend using "geojson" as the only standard and widely supported format. The second favorite format is "geocodejson", which is generally compatible with GeoJSON specification and in the case of Nominatim includes the most complete and standartized address structure.
Example geocoding output for "/search?q=berlin&format=geojson&limit=1"
{
"type": "FeatureCollection",
"licence": "Data © OpenStreetMap contributors, ODbL 1.0. https://osm.org/copyright",
"features": [
{
"type": "Feature",
"properties": {
"place_id": 595794,
"osm_type": "node",
"osm_id": 240109189,
"display_name": "Berlin, 10117, Deutschland",
"place_rank": 15,
"category": "place",
"type": "city",
"importance": 0.887539028249136,
"icon": "https://nominatim.openstreetmap.org/images/mapicons/poi_place_city.p.20.png"
},
"bbox": [
13.2288599,
52.3570365,
13.5488599,
52.6770365
],
"geometry": {
"type": "Point",
"coordinates": [
13.3888599,
52.5170365
]
}
}
]
}Geometry and additional details
Nominatim can lookup and return some additional information
addressdetails=1
extratags=1
namedetails=1Geocoding example with additional fields
"/search?q=berlin&format=geojson&limit=1&addressdetails=1&extratags=1&namedetails=1"
{
"type": "FeatureCollection",
"licence": "Data © OpenStreetMap contributors, ODbL 1.0. https://osm.org/copyright",
"features": [
{
"type": "Feature",
"properties": {
"place_id": 595794,
"osm_type": "node",
"osm_id": 240109189,
"display_name": "Berlin, 10117, Deutschland",
"place_rank": 15,
"category": "place",
"type": "city",
"importance": 0.887539028249136,
"icon": "https://nominatim.openstreetmap.org/images/mapicons/poi_place_city.p.20.png",
"address": {
"city": "Berlin",
"state": "Berlin",
"postcode": "10117",
"country": "Deutschland",
"country_code": "de"
},
"extratags": {
"email": "[email protected]",
"capital": "yes",
"website": "https://www.berlin.de/",
"wikidata": "Q64",
"wikipedia": "de:Berlin",
"population": "3531201",
"name:prefix": "Land und Kreisfreie Stadt"
},
"namedetails": {
"name": "Berlin",
"name:ab": "Берлин",
"name:af": "Berlyn",
"name:am": "በርሊን",
"name:an": "Berlín",
"name:ar": "برلين",
"name:short": "BE",
"name:nds-nl": "Berlien",
"old_name:vi": "Bá Linh",
"name:bat-smg": "Berlīns",
"name:cbk-zam": "Berlín",
"name:fiu-vro": "Berliin",
"name:roa-rup": "Berlin",
"name:roa-tara": "Berline",
"name:be-tarask": "Бэрлін"
}
},
"bbox": [
13.2288599,
52.3570365,
13.5488599,
52.6770365
],
"geometry": {
"type": "Point",
"coordinates": [
13.3888599,
52.5170365
]
}
}
]
}It is also possible to return the original geometry of the results instead of the coordinate and bounding box. For that you need to specify one of the following parameters:
polygon_geojson=1
polygon_kml=1
polygon_svg=1
polygon_text=1Multilanguage support
By default, Nominatim uses “Accept-Language” HTTP header to choose the preferred language of the result. This can be changed by “accept-language” parameter, which can be set to one or multiple (comma-separated) language codes – in order of preference. If both the HTTP header and parameter are missing, Nominatim will return each geocoding result using the native language of the place.
Installation and hardware requirements
General installation instructions are very well documented in Nominatim Administration Guide, and there is no point in repeating the same information here.
You should plan that initial production-ready setup and configuration will take at least 2 days and up to several weeks of effort, depending on your situation, requirements, and level of expertise. You also need to have some level of confidence with Linux, Apache web server, PHP and PostgreSQL database to follow the instructions.
Hardware requirements depend on desired coverage (full planet, country, region or city) and if you plan to apply daily or hourly updates to the Nominatim database. For planet import, we recommend a server with at least 8 cores, 32 GB RAM and 700 GB of fast SSD/NVMe storage. With that, you can expect initial data import to take approximately 2-3 days. For smaller regional datasets your hardware requirements will be proportionally lower, but as a bare minimum, you need at least 2 CPUs, 4 GB memory and 50 GB of fast storage.
A possible alternative for testing and small non-profit projects you can use the free community-supported Nominatim instance. It is funded by the OpenStreetMap foundation and normally has the most up to date Nominatim version and data. As a downside, there are no up-time or performance guarantees, and your requests may be blocked without any further notice if you generate than 1 request per second, or send repetitive, systematic or batch queries.
Again, it is normally acceptable for testing and very small projects, but and serious business usage is discouraged. Please check the OSM Nominatim Acceptable Use Policy for more details.
As an alternative, we at Geoapify can offer you a full range of Nominatim support – from business-friendly, managed Nominatim instances, to dedicated installations, as well as consultation and assistance if you need help with configuration.
So, should I use Nominatim for geocoding?
You should definitely consider Nominatim if you need to do high-volume or batch geocoding with thousands and millions of addresses. It also can be very useful for scenarios when you need to do geocoding in secure environments or offline.
Another benefit comes from the open data that Nominatim uses. If something is missing or wrong in underlying OSM or Wikipedia data, you or anyone else can easily add or correct that information. It is normally much more challenging to do that with any alternative services.
But do not expect Nominatim to be as smart as e.g. Google Maps API, especially if you deal with manually entered addresses. On average Nominatim does great job and correctly geocodes around 70% of addresses, while best commercial services can geocode around 90%.
Also, full-text-search in Nominatim is somewhat limited. Elasticsearch based alternatives like Photon or Pelias can give better results if you need to lookup places by name instead of addresses.
And don’t forget about time and resources that need to be invested into configuring, running and maintaining Nominatim installations.
If that is too much for you and you just need smart geocoding that works well, we can recommend giving our Geocoding API and Reverse Geocoding API a try. It has very liberal pricing, generous free tier that is eligible for business usage and combines a number of technologies and know-how to deliver the best results as fast as possible.
