Nominatim
Nominatim (from the Latin, 'by name') is a tool to search OSM data by name and address (geocoding) and to generate synthetic addresses of OSM points (reverse geocoding). It can be found at nominatim.openstreetmap.org.
Nominatim is also used as one of the sources for the search box on the OpenStreetMap home page. Several companies provide hosted instances of Nominatim that you can query via an API, see section Alternatives below.
This page provides usage instructions. For details of how Nominatim works please see the Development Overview and there is a short FAQ. There is also a list of language mappings per country, some experimental address formats per country and a list of abbreviations.
Contents
Search
Nominatim indexes named (or numbered) features with the OSM data set and a subset of other unnamed features (pubs, hotels, churches, etc)
Search terms are processed first left to right and then right to left if that fails.
Both searches will work: pilkington avenue, birmingham birmingham, pilkington avenue
(Commas are optional, but improve performance by reducing the complexity of the search.)
Where house numbers have been defined for an area they should be used: 135 pilkington avenue, birmingham
Special Keywords
Various keywords are translated into searches for specific osm tags (e.g. Pub => amenity=pub). A current list of special phrases processed is available.
Parameters
https://nominatim.openstreetmap.org/search?<params> https://nominatim.openstreetmap.org/search/<query>?<params>
format=[html|xml|json|jsonv2]
- Output format
json_callback=<string>
- Wrap json output in a callback function (JSONP) i.e. <string>(<json>)
accept-language=<browser language string>
- Preferred language order for showing search results, overrides the value specified in the "Accept-Language" HTTP header.
- Either uses standard rfc2616 accept-language string or a simple comma separated list of language codes.
q=<query>
- Query string to search for. Alternatively can be entered as:
street=<housenumber> <streetname>
city=<city>
county=<county>
state=<state>
country=<country>
postalcode=<postalcode>
- (experimental) Alternative query string format for structured requests.
- Structured requests are faster and require fewer server resources.
- For North American addresses, use the full name for state to improve the results.
- DO NOT COMBINE WITH q=<query> PARAMETER.
countrycodes=<countrycode>[,<countrycode>][,<countrycode>]...
- Limit search results to a specific country (or a list of countries).
- <countrycode> should be the ISO 3166-1alpha2 code, e.g. gb for the United Kingdom, de for Germany, etc.
viewbox=<x1>,<y1>,<x2>,<y2>
- The preferred area to find search results. Any two corner points of the box are accepted in any order as long as they span a real box.
bounded=[0|1]
- Restrict the results to only items contained with the viewbox (see above).
- Restricting the results to the bounding box also enables searching by amenity only.
- For example a search query of just "[pub]" would normally be rejected but with bounded=1 will result in a list of items matching within the bounding box.
polygon=[0|1]
- Output polygon outlines for items found
- (deprecated, use one of the polygon_* parameters instead)
addressdetails=[0|1]
- Include a breakdown of the address into elements
email=<valid email address>
- If you are making large numbers of request please include a valid email address or alternatively include your email address as part of the User-Agent string.
- This information will be kept confidential and only used to contact you in the event of a problem, see Usage Policy for more details.
exclude_place_ids=<place_id,[place_id],[place_id]>
- If you do not want certain openstreetmap objects to appear in the search result, give a comma separated list of the place_id's you want to skip. This can be used to broaden search results. For example, if a previous query only returned a few results, then including those here would cause the search to return other, less accurate, matches (if possible)
limit=<integer>
- Limit the number of returned results. Default is 10.
dedupe=[0|1]
- Sometimes you have several objects in OSM identifying the same place or object in reality. The simplest case is a street being split in many different OSM ways due to different characteristics.
- Nominatim will attempt to detect such duplicates and only return one match; this is controlled by the dedupe parameter which defaults to 1. Since the limit is, for reasons of efficiency, enforced before and not after de-duplicating, it is possible that de-duplicating leaves you with less results than requested.
debug=[0|1]
- Output assorted developer debug information. Data on internals of nominatim "Search Loop" logic, and SQL queries. The output is (rough) HTML format. This overrides the specified machine readable format.
polygon_geojson=1
- Output geometry of results in geojson format.
polygon_kml=1
- Output geometry of results in kml format.
polygon_svg=1
- Output geometry of results in svg format.
polygon_text=1
- Output geometry of results as a WKT.
extratags=1
- Include additional information in the result if available, e.g. wikipedia link, opening hours.
namedetails=1
- Include a list of alternative names in the results.
- These may include language variants, references, operator and brand.
Examples
https://nominatim.openstreetmap.org/search?q=135+pilkington+avenue,+birmingham&format=xml&polygon=1&addressdetails=1 https://nominatim.openstreetmap.org/search/135%20pilkington%20avenue,%20birmingham?format=xml&polygon=1&addressdetails=1 https://nominatim.openstreetmap.org/search/gb/birmingham/pilkington%20avenue/135?format=xml&polygon=1&addressdetails=1
<searchresults timestamp="Sat, 07 Nov 09 14:42:10 +0000" querystring="135 pilkington, avenue birmingham" polygon="true">
<place
place_id="1620612" osm_type="node" osm_id="452010817"
boundingbox="52.548641204834,52.5488433837891,-1.81612110137939,-1.81592094898224"
polygonpoints="[['-1.81592098644987','52.5487429714954'],['-1.81592290792183','52.5487234624632'],...]"
lat="52.5487429714954" lon="-1.81602098644987"
display_name="135, Pilkington Avenue, Wylde Green, City of Birmingham, West Midlands (county), B72, United Kingdom"
class="place" type="house">
<house_number>135</house_number>
<road>Pilkington Avenue</road>
<village>Wylde Green</village>
<town>Sutton Coldfield</town>
<city>City of Birmingham</city>
<county>West Midlands (county)</county>
<postcode>B72</postcode>
<country>United Kingdom</country>
<country_code>gb</country_code>
</place>
</searchresults>
https://nominatim.openstreetmap.org/search/Unter%20den%20Linden%201%20Berlin?format=json&addressdetails=1&limit=1&polygon_svg=1
[
{
"address": {
"city": "Berlin",
"city_district": "Mitte",
"construction": "Unter den Linden",
"continent": "European Union",
"country": "Deutschland",
"country_code": "de",
"house_number": "1",
"neighbourhood": "Scheunenviertel",
"postcode": "10117",
"public_building": "Kommandantenhaus",
"state": "Berlin",
"suburb": "Mitte"
},
"boundingbox": [
"52.5170783996582",
"52.5173187255859",
"13.3975105285645",
"13.3981599807739"
],
"class": "amenity",
"display_name": "Kommandantenhaus, 1, Unter den Linden, Scheunenviertel, Mitte, Berlin, 10117, Deutschland, European Union",
"importance": 0.73606775332943,
"lat": "52.51719785",
"licence": "Data \u00a9 OpenStreetMap contributors, ODbL 1.0. https://www.openstreetmap.org/copyright",
"lon": "13.3978352028938",
"osm_id": "15976890",
"osm_type": "way",
"place_id": "30848715",
"svg": "M 13.397511 -52.517283599999999 L 13.397829400000001 -52.517299800000004 13.398131599999999 -52.517315099999998 13.398159400000001 -52.517112099999999 13.3975388 -52.517080700000001 Z",
"type": "public_building"
}
]
https://nominatim.openstreetmap.org/?format=json&addressdetails=1&q=bakery+in+berlin+wedding&format=json&limit=1
[
{
"address": {
"bakery": "B\u00e4cker Kamps",
"city_district": "Mitte",
"continent": "European Union",
"country": "Deutschland",
"country_code": "de",
"footway": "Bahnsteig U6",
"neighbourhood": "Sprengelkiez",
"postcode": "13353",
"state": "Berlin",
"suburb": "Wedding"
},
"boundingbox": [
"52.5460929870605",
"52.5460968017578",
"13.3591794967651",
"13.3591804504395"
],
"class": "shop",
"display_name": "B\u00e4cker Kamps, Bahnsteig U6, Sprengelkiez, Wedding, Mitte, Berlin, 13353, Deutschland, European Union",
"icon": "https://nominatim.openstreetmap.org/images/mapicons/shopping_bakery.p.20.png",
"importance": 0.201,
"lat": "52.5460941",
"licence": "Data \u00a9 OpenStreetMap contributors, ODbL 1.0. https://www.openstreetmap.org/copyright",
"lon": "13.35918",
"osm_id": "317179427",
"osm_type": "node",
"place_id": "1453068",
"type": "bakery"
}
]
Reverse Geocoding
Reverse geocoding generates an address from a latitude and longitude. The optional zoom parameter specifies the level of detail required in terms of something suitable for a Leaflet.js/OpenLayers/etc. zoom level.
Parameters
https://nominatim.openstreetmap.org/reverse?<query>
format=[xml|html|json|jsonv2]
- Output format, default = xml.
jsonv2adds the next fields to response:place_rank
- The place_rank is based on a rather complex algorithm taking the place type and various other attributes into account. For example it seems checks whether this object is a village, a city, a country, a continent, a highway, a lake and similar other properties. [1]
categorytypeimportance
- The importance is used for ordering search results according to their relevance. The importance value is calculated/estimated using various attributes including the place's popularity on Wikipedia and its place_rank.[2]
addresstype
json_callback=<string>
- Wrap json output in a callback function (JSONP) i.e. <string>(<json>)
accept-language=<browser language string>
- Preferred language order for showing search results, overrides the value specified in the "Accept-Language" HTTP header.
- Either uses standard rfc2616 accept-language string or a simple comma separated list of language codes.
osm_type=[N|W|R]
osm_id=<value>
- A specific osm node / way / relation to return an address for
- Please use this in preference to lat/lon where possible
lat=<value> lon=<value>
- The location to generate an address for
zoom=[0-18]
- Level of detail required where 0 is country and 18 is house/building
addressdetails=[0|1]
- Include a breakdown of the address into elements
email=<valid email address>
- If you are making large numbers of request please include a valid email address
- or alternatively include your email address as part of the User-Agent string.
- This information will be kept confidential and only used to contact you in the
- event of a problem, see Usage Policy for more details.
polygon_geojson=1
- Output geometry of result in geojson format.
polygon_kml=1
- Output geometry of result in kml format.
polygon_svg=1
- Output geometry of result in svg format.
polygon_text=1
- Output geometry of result as a WKT.
extratags=1
- Include additional information in the result if available, e.g. wikipedia link, opening hours.
namedetails=1
- Include a list of alternative names in the results.
- These may include language variants, references, operator and brand.
Example
https://nominatim.openstreetmap.org/reverse?format=xml&lat=52.5487429714954&lon=-1.81602098644987&zoom=18&addressdetails=1
<reversegeocode timestamp="Fri, 06 Nov 09 16:33:54 +0000" querystring="...">
<result place_id="1620612" osm_type="node" osm_id="452010817">
135, Pilkington Avenue, Wylde Green, City of Birmingham, West Midlands (county), B72, United Kingdom
</result>
<addressparts>
<house_number>135</house_number>
<road>Pilkington Avenue</road>
<village>Wylde Green</village>
<town>Sutton Coldfield</town>
<city>City of Birmingham</city>
<county>West Midlands (county)</county>
<postcode>B72</postcode>
<country>United Kingdom</country>
<country_code>gb</country_code>
</addressparts>
</reversegeocode>
Example with format=jsonv2
https://nominatim.openstreetmap.org/reverse?format=jsonv2&lat=-34.44076&lon=-58.70521
{
"place_id":"134140761",
"licence":"Data © OpenStreetMap contributors, ODbL 1.0. http:\/\/www.openstreetmap.org\/copyright",
"osm_type":"way",
"osm_id":"280940520",
"lat":"-34.4391708",
"lon":"-58.7064573",
"place_rank":"26",
"category":"highway",
"type":"motorway",
"importance":"0.1",
"addresstype":"road",
"display_name":"Autopista Pedro Eugenio Aramburu, El Triángulo, Partido de Malvinas Argentinas, Buenos Aires, 1.619, Argentina",
"name":"Autopista Pedro Eugenio Aramburu",
"address":{
"road":"Autopista Pedro Eugenio Aramburu",
"village":"El Triángulo",
"state_district":"Partido de Malvinas Argentinas",
"state":"Buenos Aires",
"postcode":"1.619",
"country":"Argentina",
"country_code":"ar"
},
"boundingbox":["-34.44159","-34.4370994","-58.7086067","-58.7044712"]
}
Hierarchy
| Admin level | XML entity |
|---|---|
| 2 | <country> |
| 4 | <state> |
| 5 | <state_district> |
| 6 | |
| 7 | <county> |
| 8 | <village> |
| 9 | <city_district> |
| 10 | <suburb> |
Address lookup
Lookup the address of one or multiple OSM objects like node, way or relation.
Parameters
https://nominatim.openstreetmap.org/lookup?<query>
format=[xml|json]
- Output format
json_callback=<string>
- Wrap json output in a callback function (JSONP) i.e. <string>(<json>)
accept-language=<browser language string>
- Preferred language order for showing search results, overrides the value specified in the "Accept-Language" HTTP header.
- Either uses standard rfc2616 accept-language string or a simple comma separated list of language codes.
osm_ids=[N|W|R]<value>,…,[N|W|R]<value>
- A list of up to 50 specific osm node, way or relations ids to return the addresses for
addressdetails=[0|1]
- Include a breakdown of the address into elements
email=<valid email address>
- If you are making large numbers of request please include a valid email address or alternatively include your email address as part of the User-Agent string.
- This information will be kept confidential and only used to contact you in the event of a problem, see Usage Policy for more details.
extratags=1
- Include additional information in the result if available, e.g. wikipedia link, opening hours.
namedetails=1
- Include a list of alternative names in the results.
- These may include language variants, references, operator and brand.
Example
https://nominatim.openstreetmap.org/lookup?osm_ids=R146656,W104393803,N240109189
<lookupresults timestamp="Mon, 29 Jun 15 18:01:33 +0000" attribution="Data © OpenStreetMap contributors, ODbL 1.0. https://www.openstreetmap.org/copyright" querystring="R146656,W104393803,N240109189" polygon="false">
<place place_id="127761056" osm_type="relation" osm_id="146656" place_rank="16" lat="53.4791466" lon="-2.2447445" display_name="Manchester, Greater Manchester, North West England, England, United Kingdom" class="boundary" type="administrative" importance="0.704893333438333">
<city>Manchester</city>
<county>Greater Manchester</county>
<state_district>North West England</state_district>
<state>England</state>
<country>United Kingdom</country>
<country_code>gb</country_code>
</place>
<place place_id="77769745" osm_type="way" osm_id="104393803" place_rank="30" lat="52.5162024" lon="13.3777343363579" display_name="Brandenburg Gate, 1, Pariser Platz, Mitte, Berlin, 10117, Germany" class="tourism" type="attraction" importance="0.443472858361592">
<attraction>Brandenburg Gate</attraction>
<house_number>1</house_number>
<pedestrian>Pariser Platz</pedestrian>
<suburb>Mitte</suburb>
<city_district>Mitte</city_district>
<city>Berlin</city>
<state>Berlin</state>
<postcode>10117</postcode>
<country>Germany</country>
<country_code>de</country_code>
</place>
<place place_id="2570600569" osm_type="node" osm_id="240109189" place_rank="15" lat="52.5170365" lon="13.3888599" display_name="Berlin, Germany" class="place" type="city" importance="0.822149797630868">
<city>Berlin</city>
<state>Berlin</state>
<country>Germany</country>
<country_code>de</country_code>
</place>
</lookupresults>
Details / Gazetteer
Currently the details page (details.php) creates a high load on the server and is only intended as a debugging aide, as a result no xml api is currently provided. Scraping or heavy use is likely to result in an IP ban.
Usage Policy
For the usage policy of nominatim.openstreetmap.org, please see Nominatim usage policy.
Source Code
Nominatim is based around the postgresql import utility osm2pgsql using the alternative gazetteer output option. Indexing and search are performed using a combination of C, plpgsql and php. The source can be found here:
https://github.com/openstreetmap/Nominatim
Full installation instructions can be found in on the nominatim.org website.
Bugs / Error reporting
Please report bugs and problems in the Nominatim issue tracker on Github (there are also reports on trac.openstreetmap.org).
When you report unexpected search results, please include the following in your bug report:
- the exact search term you were using
- links to the OSM objects you expect to find and, optionally, a link to the OSM object that was actually found
Alternatives / Third-party providers
For slightly larger requirements you may be able to use one the various third-party providers, though of course, you will need to agree to their terms of service.
If your requirements are even larger, you can install your own instance of Nominatim.
