Getting started with OpenStreetMap Nominatim API
OpenStreetMap (OSM) is a collaborative project to create a free editable map of the world. It is built by a community of mappers that contribute and maintain OSM data.
Today, we are going to learn how to start using the Nominatim API. This API is commonly used to search OSM data by name and address and to generate synthetic addresses of OSM points (reverse geocoding). In this post, I will be introducing you to the main 3 endpoints: details, search and reverse.
Introduction
Elements are the basic components of OpenStreetMap’s conceptual data model of the physical world. There are 3 types of elements:
- nodes: they define points in space.
- ways: they define linear features and area boundaries. Ways can be closed or open.
Open way:
Closed way:
- relations: they define groups of elements.
Every element is identified by an id, and it is very important to take into account that each element type has its own id space. This means, it is possible that a node and a way with the same id exist, and it is unlikely that they are related.
Nominatim API
Details endpoint
This endpoint is used to look up details about a single place by id. This is the format of the request:
https://nominatim.openstreetmap.org/details?osmtype=[N|W|R]&osmid=<value>&class=<value>Let’s do an example request for New York City, which has id=175905 and type=R (the class parameter is optional):
curl "https://nominatim.openstreetmap.org/details?osmtype=R&osmid=175905&format=json"Result:
{
"place_id": 235405672,
"parent_place_id": 235374174,
"osm_type": "R",
"osm_id": 175905,
"category": "boundary",
"type": "administrative",
"admin_level": 5,
"localname": "New York",
"names": {
"alt_name": "New York City",
"alt_name:cs": "Nový York",
"name": "New York",
"name:ar": "نيويورك",
"name:be": "Нью-Ёрк",
"name:be-tarask": "Нью-Ёрк",
"name:ca": "Nova York",
"name:cs": "New York",
"name:cy": "Efrog Newydd",
"name:de": "New York",
"name:el": "Νέα Υόρκη",
"name:en": "New York",
"name:eo": "Novjorko",
"name:es": "Nueva York",
"name:fa": "نیویورک",
"name:fr": "New York",
"name:he": "ניו יורק",
"name:hi": "न्यूयॊर्क्",
"name:is": "Nýja Jórvík",
"name:it": "New York",
"name:ja": "ニューヨーク",
"name:jbo": ".nu,IORK.",
"name:kn": "ನ್ಯೂಯೊರ್ಕ್",
"name:ko": "뉴욕",
"name:mi": "Niu Iaka",
"name:oc": "Nòva York",
"name:pl": "Nowy Jork",
"name:ru": "Нью-Йорк",
"name:ta": "நியூ யோர்க்",
"name:te": "న్యూయొర్క్",
"name:uk": "Нью-Йорк",
"name:zh": "纽约",
"official_name": "City of New York",
"old_name:it": "Nuova York",
"short_name": "NYC"
},
"addresstags": [],
"housenumber": null,
"calculated_postcode": null,
"country_code": "us",
"indexed_date": "2020-05-01T22:41:17+00:00",
"importance": 0.8175766114518461,
"calculated_importance": 0.8175766114518461,
"extratags": {
"border_type": "city",
"importance": "international",
"linked_place": "city",
"place": "city",
"population": "8550405",
"population:date": "2010",
"rank": "0",
"website": "https://www.nyc.gov",
"wikidata": "Q60",
"wikipedia": "en:New York City"
},
"calculated_wikipedia": "en:New_York_City",
"icon": "https://nominatim.openstreetmap.org/images/mapicons/poi_boundary_administrative.p.20.png",
"rank_address": 16,
"rank_search": 10,
"isarea": true,
"centroid": {
"type": "Point",
"coordinates": [-74.0060152, 40.7127281]
},
"geometry": {
"type": "Point",
"coordinates": [-74.0060152, 40.7127281]
},
"linked_places": [{
"localname": "New York",
"place_id": 252347,
"osm_id": 61785451,
"osm_type": "N",
"place_type": null,
"class": "place",
"type": "city",
"admin_level": 15,
"rank_address": 16,
"distance": 0,
"isaddress": null
}]
}Take a look at the details endpoint documentation for more parameters of the request.
Search endpoint
This endpoint is used to look up a location from a textual description. These are the possible formats of the request:
https://nominatim.openstreetmap.org/search/<query>?<params>https://nominatim.openstreetmap.org/search?q=<query><params>
Queries to this endpoint can return multiple elements. We can include a limit=<limit> to set a limit on the number of elements that the query will return.
Let’s do an example request for query=“New York” with limit=2:
curl "https://nominatim.openstreetmap.org/search?q=New York City&limit=2&format=json"Result:
[{
"place_id": 235405672,
"licence": "Data © OpenStreetMap contributors, ODbL 1.0. https://osm.org/copyright",
"osm_type": "relation",
"osm_id": 175905,
"boundingbox": ["40.477399", "40.9161785", "-74.25909", "-73.7001809"],
"lat": "40.7127281",
"lon": "-74.0060152",
"display_name": "New York, United States of America",
"class": "boundary",
"type": "administrative",
"importance": 1.017576611451846,
"icon": "https://nominatim.openstreetmap.org/images/mapicons/poi_boundary_administrative.p.20.png"
}, {
"place_id": 235374174,
"licence": "Data © OpenStreetMap contributors, ODbL 1.0. https://osm.org/copyright",
"osm_type": "relation",
"osm_id": 61320,
"boundingbox": ["40.477399", "45.0158611", "-79.761944", "-71.7955694"],
"lat": "43.1561681",
"lon": "-75.8449946",
"display_name": "New York, United States of America",
"class": "boundary",
"type": "administrative",
"importance": 0.9655846409089575,
"icon": "https://nominatim.openstreetmap.org/images/mapicons/poi_boundary_administrative.p.20.png"
}]Take a look at the search endpoint documentation for more parameters of the request.
Reverse endpoint
This endpoint is used to reverse geocode, this is, generate an address from a latitude and a longitude. This is the format of the request:
https://nominatim.openstreetmap.org/reverse?<query>The latitude and the longitude can be specified in the next way: lat=<value>, lon=<value>. It can be set a zoom=[0–18] to specify the maximum administration level of the address returned, a higher value means more level of detail for the address. You can take a look at the possible values in the documentation.
Let’s do an example request for lat=40.7127281 and lon=-74.0060152:
curl "https://nominatim.openstreetmap.org/reverse?lat=40.7127281&lon=-74.0060152&zoom=10&format=json"Result:
{
"place_id": 287295616,
"licence": "Data © OpenStreetMap contributors, ODbL 1.0. https://osm.org/copyright",
"osm_type": "relation",
"osm_id": 7340078,
"lat": "40.7033821",
"lon": "-74.01050626160045",
"display_name": "Manhattan Community Board 1, New York County, New York, United States of America",
"address": {
"city": "Manhattan Community Board 1",
"county": "New York County",
"state": "New York",
"country": "United States of America",
"country_code": "us"
},
"boundingbox": ["40.6793188", "40.727468", "-74.0472219", "-73.9945629"]
}Take a look at the reverse endpoint documentation for more parameters of the request.
Request parameters
There are several parameters that can be used to get more information about the elements that we are receiving. These are:
- addressdetails=[0|1]: include a breakdown of the address into elements.
- keywords=[0|1]: include a list of name keywords and address keywords (word ids).
- linkedplaces=[0|1]: Include details of places higher in the address hierarchy.
- hierarchy=[0|1]: include details of places lower in the address hierarchy.
- group_hierarchy=[0|1]: for JSON output will group the places by type.
- polygon_geojson=[0|1]: include the geometry of result.
- namedetails=[0|1]: include a list of alternative names in the results. These may include language variants, references, operator and brand.
Example script with Python
If you want to start using the Nominatim API with Python, take a look at this GitHub Gist with examples of everything mentioned in this post.
Usage policy
Before you start using the Nominatim API, I recommend you to take a look at the usage policy for proper usage and to avoid getting banned for a couple of hours.
