Place Output
The /reverse, /search and /lookup
API calls produce very similar output which is explained in this section.
There is one section for each format. The format correspond to what was
selected via the format
parameter.
JSON
The JSON format returns an array of places (for search and lookup) or a single place (for reverse) of the following format:
{
"place_id": "100149",
"licence": "Data © OpenStreetMap contributors, ODbL 1.0. https://osm.org/copyright",
"osm_type": "node",
"osm_id": "107775",
"boundingbox": ["51.3473219", "51.6673219", "-0.2876474", "0.0323526"],
"lat": "51.5073219",
"lon": "-0.1276474",
"display_name": "London, Greater London, England, SW1A 2DU, United Kingdom",
"class": "place",
"type": "city",
"importance": 0.9654895765402,
"icon": "https://nominatim.openstreetmap.org/images/mapicons/poi_place_city.p.20.png",
"address": {
"city": "London",
"state_district": "Greater London",
"state": "England",
"postcode": "SW1A 2DU",
"country": "United Kingdom",
"country_code": "gb"
},
"extratags": {
"capital": "yes",
"website": "http://www.london.gov.uk",
"wikidata": "Q84",
"wikipedia": "en:London",
"population": "8416535"
}
}
The possible fields are:
place_id
- reference to the Nominatim internal database ID (see notes)osm_type
,osm_id
- reference to the OSM object (see notes)boundingbox
- area of corner coordinates (see notes)lat
,lon
- latitude and longitude of the centroid of the objectdisplay_name
- full comma-separated addressclass
,type
- key and value of the main OSM tagimportance
- computed importance rankicon
- link to class icon (if available)address
- dictionary of address details (only withaddressdetails=1
, see notes)extratags
- dictionary with additional useful tags like website or maxspeed (only withextratags=1
)namedetails
- dictionary with full list of available names including ref etc.geojson
,svg
,geotext
,geokml
- full geometry (only with the appropriatepolygon_*
parameter)
JSONv2
This is the same as the JSON format with two changes:
class
renamed tocategory
- additional field
place_rank
with the search rank of the object
GeoJSON
This format follows the RFC7946. Every feature includes
a bounding box (bbox
).
The properties object has the following fields:
place_id
- reference to the Nominatim internal database ID (see notes)osm_type
,osm_id
- reference to the OSM object (see notes)category
,type
- key and value of the main OSM tagdisplay_name
- full comma-separated addressplace_rank
- class search rankimportance
- computed importance rankicon
- link to class icon (if available)address
- dictionary of address details (only withaddressdetails=1
, see notes)extratags
- dictionary with additional useful tags likewebsite
ormaxspeed
(only withextratags=1
)namedetails
- dictionary with full list of available names including ref etc.
Use polygon_geojson
to output the full geometry of the object instead
of the centroid.
GeocodeJSON
The GeocodeJSON format follows the GeocodeJSON spec 0.1.0. The following feature attributes are implemented:
osm_type
,osm_id
- reference to the OSM object (unofficial extension, see notes)type
- value of the main tag of the object (e.g. residential, restaurant, ...)label
- full comma-separated addressname
- localised name of the placehousenumber
,street
,locality
,district
,postcode
,city
,county
,state
,country
- provided when it can be determined from the addressadmin
- list of localised names of administrative boundaries (only withaddressdetails=1
)
Use polygon_geojson
to output the full geometry of the object instead
of the centroid.
XML
The XML response returns one or more place objects in slightly different formats depending on the API call.
Reverse
<reversegeocode timestamp="Sat, 11 Aug 18 11:53:21 +0000"
attribution="Data © OpenStreetMap contributors, ODbL 1.0. https://www.openstreetmap.org/copyright"
querystring="lat=48.400381&lon=11.745876&zoom=5&format=xml">
<result place_id="179509537" osm_type="relation" osm_id="2145268" ref="BY" place_rank="15" address_rank="15"
lat="48.9467562" lon="11.4038717"
boundingbox="47.2701114,50.5647142,8.9763497,13.8396373">
Bavaria, Germany
</result>
<addressparts>
<state>Bavaria</state>
<country>Germany</country>
<country_code>de</country_code>
</addressparts>
<extratags>
<tag key="place" value="state"/>
<tag key="wikidata" value="Q980"/>
<tag key="wikipedia" value="de:Bayern"/>
<tag key="population" value="12520000"/>
<tag key="name:prefix" value="Freistaat"/>
</extratags>
</reversegeocode>
The attributes of the outer reversegeocode
element return generic information
about the query, including the time when the response was sent (in UTC),
attribution to OSM and the original querystring.
The place information can be found in the result
element. The attributes of that element contain:
place_id
- reference to the Nominatim internal database ID (see notes)osm_type
,osm_id
- reference to the OSM object (see notes)ref
- content ofref
tag if it existslat
,lon
- latitude and longitude of the centroid of the objectboundingbox
- comma-separated list of corner coordinates (see notes)
The full address of the result can be found in the content of the
result
element as a comma-separated list.
Additional information requested with addressdetails=1
, extratags=1
and
namedetails=1
can be found in extra elements.
Search and Lookup
<searchresults timestamp="Sat, 11 Aug 18 11:55:35 +0000"
attribution="Data © OpenStreetMap contributors, ODbL 1.0. https://www.openstreetmap.org/copyright"
querystring="london" polygon="false" exclude_place_ids="100149"
more_url="https://nominatim.openstreetmap.org/search.php?q=london&addressdetails=1&extratags=1&exclude_place_ids=100149&format=xml&accept-language=en-US%2Cen%3Bq%3D0.7%2Cde%3Bq%3D0.3">
<place place_id="100149" osm_type="node" osm_id="107775" place_rank="15" address_rank="15"
boundingbox="51.3473219,51.6673219,-0.2876474,0.0323526" lat="51.5073219" lon="-0.1276474"
display_name="London, Greater London, England, SW1A 2DU, United Kingdom"
class="place" type="city" importance="0.9654895765402"
icon="https://nominatim.openstreetmap.org/images/mapicons/poi_place_city.p.20.png">
<extratags>
<tag key="capital" value="yes"/>
<tag key="website" value="http://www.london.gov.uk"/>
<tag key="wikidata" value="Q84"/>
<tag key="wikipedia" value="en:London"/>
<tag key="population" value="8416535"/>
</extratags>
<city>London</city>
<state_district>Greater London</state_district>
<state>England</state>
<postcode>SW1A 2DU</postcode>
<country>United Kingdom</country>
<country_code>gb</country_code>
</place>
</searchresults>
The attributes of the outer searchresults
or lookupresults
element return
generic information about the query:
timestamp
- UTC time when the response was sentattribution
- OSM licensing informationquerystring
- original querypolygon
- true when extra geometry information was requestedexclude_place_ids
- IDs of places that should be ignored in a follow-up requestmore_url
- search call that will yield additional results for the query just sent
The place information can be found in the place
elements, of which there may
be more than one. The attributes of that element contain:
place_id
- reference to the Nominatim internal database ID (see notes)osm_type
,osm_id
- reference to the OSM object (see notes)ref
- content ofref
tag if it existslat
,lon
- latitude and longitude of the centroid of the objectboundingbox
- comma-separated list of corner coordinates (see notes)place_rank
- class search rankaddress_rank
- place address rankdisplay_name
- full comma-separated addressclass
,type
- key and value of the main OSM tagimportance
- computed importance rankicon
- link to class icon (if available)
When addressdetails=1
is requested, the localised address parts appear
as subelements with the type of the address part.
Additional information requested with extratags=1
and namedetails=1
can
be found in extra elements as sub-element of extratags
and namedetails
respectively.
Notes on field values
place_id is not a persistent id
The place_id
is an internal identifier that is assigned data is imported
into a Nominatim database. The same OSM object will have a different value
on another server. It may even change its ID on the same server when it is
removed and reimported while updating the database with fresh OSM data.
It is thus not useful to treat it as permanent for later use.
The combination osm_type
+osm_id
is slighly better but remember in
OpenStreetMap mappers can delete, split, recreate places (and those
get a new osm_id
), there is no link between those old and new ids.
Places can also change their meaning without changing their osm_id
,
e.g. when a restaurant is retagged as supermarket. For a more in-depth
discussion see Permanent ID.
If you need an ID that is consistent over multiple installations of Nominatim,
then you should use the combination of osm_type
+osm_id
+class
.
OSM reference
Nominatim may sometimes return special objects that do not correspond directly to an object in OpenStreetMap. These are:
- Postcodes. Nominatim returns an postcode point created from all mapped
postcodes of the same name. The class and type of these object is
place=postcdode
. Noosm_type
andosm_id
are included in the result. - Housenumber interpolations. Nominatim returns a single interpolated
housenumber from the interpolation way. The class and type are
place=house
andosm_type
andosm_id
correspond to the interpolation way in OSM. - TIGER housenumber. Nominatim returns a single interpolated housenumber
from the TIGER data. The class and type are
place=house
andosm_type
andosm_id
correspond to the street mentioned in the result.
Please note that the osm_type
and osm_id
returned may be changed in the
future. You should not expect to only find node
, way
and relation
for
the type.
boundingbox
Comma separated list of min latitude, max latitude, min longitude, max longitude.
The whole planet would be -90,90,-180,180
.
Can be used to pan and center the map on the result, for example with leafletjs
mapping library
map.fitBounds([[bbox[0],bbox[2]],[bbox[1],bbox[3]]], {padding: [20, 20], maxzoom: 16});
Bounds crossing the antimeridian have a min latitude -180 and max latitude 180, essentially covering the entire planet (see issue 184).
addressdetails
Address details in the xml and json formats return a list of names together with a designation label. Per default the following labels may appear:
- continent
- country, country_code
- region, state, state_district, county
- municipality, city, town, village
- city_district, district, borough, suburb, subdivision
- hamlet, croft, isolated_dwelling
- neighbourhood, allotments, quarter
- city_block, residental, farm, farmyard, industrial, commercial, retail
- road
- house_number, house_name
- emergency, historic, military, natural, landuse, place, railway, man_made, aerialway, boundary, amenity, aeroway, club, craft, leisure, office, mountain_pass, shop, tourism, bridge, tunnel, waterway
They roughly correspond to the classification of the OpenStreetMap data
according to either the place
tag or the main key of the object.