]> git.openstreetmap.org Git - nominatim.git/blob - docs/api/Output.md
add `state_code` field to response address details
[nominatim.git] / docs / api / Output.md
1 # Place Output
2
3 The [/reverse](Reverse.md), [/search](Search.md) and [/lookup](Lookup.md)
4 API calls produce very similar output which is explained in this section.
5 There is one section for each format. The format correspond to what was
6 selected via the `format` parameter.
7
8 ## JSON
9
10 The JSON format returns an array of places (for search and lookup) or
11 a single place (for reverse) of the following format:
12
13 ```
14   {
15     "place_id": "100149",
16     "licence": "Data © OpenStreetMap contributors, ODbL 1.0. https://osm.org/copyright",
17     "osm_type": "node",
18     "osm_id": "107775",
19     "boundingbox": ["51.3473219", "51.6673219", "-0.2876474", "0.0323526"],
20     "lat": "51.5073219",
21     "lon": "-0.1276474",
22     "display_name": "London, Greater London, England, SW1A 2DU, United Kingdom",
23     "class": "place",
24     "type": "city",
25     "importance": 0.9654895765402,
26     "icon": "https://nominatim.openstreetmap.org/images/mapicons/poi_place_city.p.20.png",
27     "address": {
28       "city": "London",
29       "state_district": "Greater London",
30       "state": "England",
31       "state_code": "ENG",
32       "postcode": "SW1A 2DU",
33       "country": "United Kingdom",
34       "country_code": "gb"
35     },
36     "extratags": {
37       "capital": "yes",
38       "website": "http://www.london.gov.uk",
39       "wikidata": "Q84",
40       "wikipedia": "en:London",
41       "population": "8416535"
42     }
43   }
44 ```
45
46 The possible fields are:
47
48  * `place_id` - reference to the Nominatim internal database ID ([see notes](#place_id-is-not-a-persistent-id))
49  * `osm_type`, `osm_id` - reference to the OSM object ([see notes](#osm-reference))
50  * `boundingbox` - area of corner coordinates ([see notes](#boundingbox))
51  * `lat`, `lon` - latitude and longitude of the centroid of the object
52  * `display_name` - full comma-separated address
53  * `class`, `type` - key and value of the main OSM tag
54  * `importance` - computed importance rank
55  * `icon` - link to class icon (if available)
56  * `address` - dictionary of address details (only with `addressdetails=1`,
57    [see notes](#addressdetails))
58  * `extratags` - dictionary with additional useful tags like website or maxspeed
59    (only with `extratags=1`)
60  * `namedetails` - dictionary with full list of available names including ref etc.
61  * `geojson`, `svg`, `geotext`, `geokml` - full geometry
62    (only with the appropriate `polygon_*` parameter)
63
64 ## JSONv2
65
66 This is the same as the JSON format with two changes:
67
68  * `class` renamed to `category`
69  * additional field `place_rank` with the search rank of the object
70
71 ## GeoJSON
72
73 This format follows the [RFC7946](https://geojson.org). Every feature includes
74 a bounding box (`bbox`).
75
76 The properties object has the following fields:
77
78  * `place_id` - reference to the Nominatim internal database ID ([see notes](#place_id-is-not-a-persistent-id))
79  * `osm_type`, `osm_id` - reference to the OSM object ([see notes](#osm-reference))
80  * `category`, `type` - key and value of the main OSM tag
81  * `display_name` - full comma-separated address
82  * `place_rank` - class search rank
83  * `importance` - computed importance rank
84  * `icon` - link to class icon (if available)
85  * `address` - dictionary of address details (only with `addressdetails=1`,
86    [see notes](#addressdetails))
87  * `extratags` - dictionary with additional useful tags like `website` or `maxspeed`
88    (only with `extratags=1`)
89  * `namedetails` - dictionary with full list of available names including ref etc.
90
91 Use `polygon_geojson` to output the full geometry of the object instead
92 of the centroid.
93
94 ## GeocodeJSON
95
96 The GeocodeJSON format follows the
97 [GeocodeJSON spec 0.1.0](https://github.com/geocoders/geocodejson-spec).
98 The following feature attributes are implemented:
99
100  * `osm_type`, `osm_id` - reference to the OSM object (unofficial extension, [see notes](#osm-reference))
101  * `type` - value of the main tag of the object (e.g. residential, restaurant, ...)
102  * `label` - full comma-separated address
103  * `name` - localised name of the place
104  * `housenumber`, `street`, `locality`, `district`, `postcode`, `city`,
105    `county`, `state`, `country` -
106    provided when it can be determined from the address
107  * `admin` - list of localised names of administrative boundaries (only with `addressdetails=1`)
108
109 Use `polygon_geojson` to output the full geometry of the object instead
110 of the centroid.
111
112 ## XML
113
114 The XML response returns one or more place objects in slightly different
115 formats depending on the API call.
116
117 ### Reverse
118
119 ```
120 <reversegeocode timestamp="Sat, 11 Aug 18 11:53:21 +0000"
121                 attribution="Data © OpenStreetMap contributors, ODbL 1.0. https://www.openstreetmap.org/copyright"
122                 querystring="lat=48.400381&lon=11.745876&zoom=5&format=xml">
123   <result place_id="179509537" osm_type="relation" osm_id="2145268" ref="BY" place_rank="15" address_rank="15"
124           lat="48.9467562" lon="11.4038717"
125           boundingbox="47.2701114,50.5647142,8.9763497,13.8396373">
126        Bavaria, Germany
127   </result>
128   <addressparts>
129      <state>Bavaria</state>
130      <state_code>BY</state_code>
131      <country>Germany</country>
132      <country_code>de</country_code>
133   </addressparts>
134   <extratags>
135     <tag key="place" value="state"/>
136     <tag key="wikidata" value="Q980"/>
137     <tag key="wikipedia" value="de:Bayern"/>
138     <tag key="population" value="12520000"/>
139     <tag key="name:prefix" value="Freistaat"/>
140   </extratags>
141 </reversegeocode>
142 ```
143
144 The attributes of the outer `reversegeocode` element return generic information
145 about the query, including the time when the response was sent (in UTC),
146 attribution to OSM and the original querystring.
147
148 The place information can be found in the `result` element. The attributes of that element contain:
149
150  * `place_id` - reference to the Nominatim internal database ID ([see notes](#place_id-is-not-a-persistent-id))
151  * `osm_type`, `osm_id` - reference to the OSM object ([see notes](#osm-reference))
152  * `ref` - content of `ref` tag if it exists
153  * `lat`, `lon` - latitude and longitude of the centroid of the object
154  * `boundingbox` - comma-separated list of corner coordinates ([see notes](#boundingbox))
155
156 The full address of the result can be found in the content of the
157 `result` element as a comma-separated list.
158
159 Additional information requested with `addressdetails=1`, `extratags=1` and
160 `namedetails=1` can be found in extra elements.
161
162 ### Search and Lookup
163
164 ```
165 <searchresults timestamp="Sat, 11 Aug 18 11:55:35 +0000"
166                attribution="Data © OpenStreetMap contributors, ODbL 1.0. https://www.openstreetmap.org/copyright"
167                querystring="london" polygon="false" exclude_place_ids="100149"
168                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">
169   <place place_id="100149" osm_type="node" osm_id="107775" place_rank="15" address_rank="15"
170          boundingbox="51.3473219,51.6673219,-0.2876474,0.0323526" lat="51.5073219" lon="-0.1276474"
171          display_name="London, Greater London, England, SW1A 2DU, United Kingdom"
172          class="place" type="city" importance="0.9654895765402"
173          icon="https://nominatim.openstreetmap.org/images/mapicons/poi_place_city.p.20.png">
174     <extratags>
175       <tag key="capital" value="yes"/>
176       <tag key="website" value="http://www.london.gov.uk"/>
177       <tag key="wikidata" value="Q84"/>
178       <tag key="wikipedia" value="en:London"/>
179       <tag key="population" value="8416535"/>
180     </extratags>
181     <city>London</city>
182     <state_district>Greater London</state_district>
183     <state>England</state>
184     <state_code>ENG</state_code>
185     <postcode>SW1A 2DU</postcode>
186     <country>United Kingdom</country>
187     <country_code>gb</country_code>
188   </place>
189 </searchresults>
190 ```
191
192 The attributes of the outer `searchresults` or `lookupresults` element return
193 generic information about the query:
194
195  * `timestamp` - UTC time when the response was sent
196  * `attribution` - OSM licensing information
197  * `querystring` - original query
198  * `polygon` - true when extra geometry information was requested
199  * `exclude_place_ids` - IDs of places that should be ignored in a follow-up request
200  * `more_url` - search call that will yield additional results for the query
201    just sent
202
203 The place information can be found in the `place` elements, of which there may
204 be more than one. The attributes of that element contain:
205
206  * `place_id` - reference to the Nominatim internal database ID ([see notes](#place_id-is-not-a-persistent-id))
207  * `osm_type`, `osm_id` - reference to the OSM object ([see notes](#osm-reference))
208  * `ref` - content of `ref` tag if it exists
209  * `lat`, `lon` - latitude and longitude of the centroid of the object
210  * `boundingbox` - comma-separated list of corner coordinates ([see notes](#boundingbox))
211  * `place_rank` - class [search rank](../develop/Ranking#search-rank)
212  * `address_rank` - place [address rank](../develop/Ranking#address-rank)
213  * `display_name` - full comma-separated address
214  * `class`, `type` - key and value of the main OSM tag
215  * `importance` - computed importance rank
216  * `icon` - link to class icon (if available)
217
218 When `addressdetails=1` is requested, the localised address parts appear
219 as subelements with the type of the address part.
220
221 Additional information requested with `extratags=1` and `namedetails=1` can
222 be found in extra elements as sub-element of `extratags` and `namedetails`
223 respectively.
224
225
226 ## Notes on field values
227
228 ### place_id is not a persistent id
229
230 The `place_id` is an internal identifier that is assigned data is imported
231 into a Nominatim database. The same OSM object will have a different value
232 on another server. It may even change its ID on the same server when it is
233 removed and reimported while updating the database with fresh OSM data.
234 It is thus not useful to treat it as permanent for later use.
235
236 The combination `osm_type`+`osm_id` is slighly better but remember in
237 OpenStreetMap mappers can delete, split, recreate places (and those
238 get a new `osm_id`), there is no link between those old and new ids.
239 Places can also change their meaning without changing their `osm_id`,
240 e.g. when a restaurant is retagged as supermarket. For a more in-depth
241 discussion see [Permanent ID](https://wiki.openstreetmap.org/wiki/Permanent_ID).
242
243 If you need an ID that is consistent over multiple installations of Nominatim,
244 then you should use the combination of `osm_type`+`osm_id`+`class`.
245
246 ### OSM reference
247
248 Nominatim may sometimes return special objects that do not correspond directly
249 to an object in OpenStreetMap. These are:
250
251 * **Postcodes**. Nominatim returns an postcode point created from all mapped
252   postcodes of the same name. The class and type of these object is `place=postcdode`.
253   No `osm_type` and `osm_id` are included in the result.
254 * **Housenumber interpolations**. Nominatim returns a single interpolated
255   housenumber from the interpolation way. The class and type are `place=house`
256   and `osm_type` and `osm_id` correspond to the interpolation way in OSM.
257 * **TIGER housenumber.** Nominatim returns a single interpolated housenumber
258   from the TIGER data. The class and type are `place=house`
259   and `osm_type` and `osm_id` correspond to the street mentioned in the result.
260
261 Please note that the `osm_type` and `osm_id` returned may be changed in the
262 future. You should not expect to only find `node`, `way` and `relation` for
263 the type.
264
265 ### boundingbox
266
267 Comma separated list of min latitude, max latitude, min longitude, max longitude.
268 The whole planet would be `-90,90,-180,180`.
269
270 Can be used to pan and center the map on the result, for example with leafletjs
271 mapping library
272 `map.fitBounds([[bbox[0],bbox[2]],[bbox[1],bbox[3]]], {padding: [20, 20], maxzoom: 16});`
273
274 Bounds crossing the antimeridian have a min latitude -180 and max latitude 180,
275 essentially covering the entire planet
276 (see [issue 184](https://github.com/openstreetmap/Nominatim/issues/184)).
277
278 ### addressdetails
279
280 Address details in the xml and json formats return a list of names together
281 with a designation label. Per default the following labels may appear:
282
283  * continent
284  * country, country_code
285  * region, state, state_code, state_district, county
286  * municipality, city, town, village
287  * city_district, district, borough, suburb, subdivision
288  * hamlet, croft, isolated_dwelling
289  * neighbourhood, allotments, quarter
290  * city_block, residental, farm, farmyard, industrial, commercial, retail
291  * road
292  * house_number, house_name
293  * emergency, historic, military, natural, landuse, place, railway,
294    man_made, aerialway, boundary, amenity, aeroway, club, craft, leisure,
295    office, mountain_pass, shop, tourism, bridge, tunnel, waterway
296  * postcode
297
298 They roughly correspond to the classification of the OpenStreetMap data
299 according to either the `place` tag or the main key of the object.