]> git.openstreetmap.org Git - nominatim.git/blob - docs/api/Output.md
document which labels may appear in the address info
[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 which is selectable via the `format`
6 parameter.
7
8 ## Formats
9
10 ### JSON
11
12 The JSON format returns an array of places (for search and lookup) or
13 a single place (for reverse) of the following format:
14
15 ```
16   {
17     "place_id": "100149",
18     "licence": "Data © OpenStreetMap contributors, ODbL 1.0. https://osm.org/copyright",
19     "osm_type": "node",
20     "osm_id": "107775",
21     "boundingbox": ["51.3473219", "51.6673219", "-0.2876474", "0.0323526"],
22     "lat": "51.5073219",
23     "lon": "-0.1276474",
24     "display_name": "London, Greater London, England, SW1A 2DU, United Kingdom",
25     "class": "place",
26     "type": "city",
27     "importance": 0.9654895765402,
28     "icon": "https://nominatim.openstreetmap.org/images/mapicons/poi_place_city.p.20.png",
29     "address": {
30       "city": "London",
31       "state_district": "Greater London",
32       "state": "England",
33       "postcode": "SW1A 2DU",
34       "country": "United Kingdom",
35       "country_code": "gb"
36     },
37     "extratags": {
38       "capital": "yes",
39       "website": "http://www.london.gov.uk",
40       "wikidata": "Q84",
41       "wikipedia": "en:London",
42       "population": "8416535"
43     }
44   },
45 ```
46
47 The possible fields are:
48
49  * `place_id` - reference to the Nominatim internal database ID ([see notes](#place_id-is-not-a-persistent-id))
50  * `osm_type`, `osm_id` - reference to the OSM object
51  * `boundingbox` - area of corner coordinates ([see notes](#boundingbox))
52  * `lat`, `lon` - latitude and longitude of the centroid of the object
53  * `display_name` - full comma-separated address
54  * `class`, `type` - key and value of the main OSM tag
55  * `importance` - computed importance rank
56  * `icon` - link to class icon (if available)
57  * `address` - dictionary of address details (only with `addressdetails=1`,
58    [see notes](#addressdetails))
59  * `extratags` - dictionary with additional useful tags like website or maxspeed
60    (only with `extratags=1`)
61  * `namedetails` - dictionary with full list of available names including ref etc.
62  * `geojson`, `svg`, `geotext`, `geokml` - full geometry
63    (only with the appropriate `polygon_*` parameter)
64
65 ### JSONv2
66
67 This is the same as the JSON format with two changes:
68
69  * `class` renamed to `category`
70  * additional field `place_rank` with the search rank of the object
71
72 ### GeoJSON
73
74 This format follows the [RFC7946](https://geojson.org). Every feature includes
75 a bounding box (`bbox`).
76
77 The feature list has the following fields:
78
79  * `place_id` - reference to the Nominatim internal database ID ([see notes](#place_id-is-not-a-persistent-id))
80  * `osm_type`, `osm_id` - reference to the OSM object
81  * `category`, `type` - key and value of the main OSM tag
82  * `display_name` - full comma-separated address
83  * `place_rank` - class search rank
84  * `importance` - computed importance rank
85  * `icon` - link to class icon (if available)
86  * `address` - dictionary of address details (only with `addressdetails=1`,
87    [see notes](#addressdetails))
88  * `extratags` - dictionary with additional useful tags like `website` or `maxspeed`
89    (only with `extratags=1`)
90  * `namedetails` - dictionary with full list of available names including ref etc.
91
92 Use `polygon_geojson` to output the full geometry of the object instead
93 of the centroid.
94
95 ### GeocodeJSON
96
97 The GeocodeJSON format follows the
98 [GeocodeJSON spec 0.1.0](https://github.com/geocoders/geocodejson-spec).
99 The following feature attributes are implemented:
100
101  * `osm_type`, `osm_id` - reference to the OSM object (unofficial extension)
102  * `type` - value of the main tag of the object (e.g. residential, restaurant, ...)
103  * `label` - full comma-separated address
104  * `name` - localised name of the place
105  * `housenumber`, `street`, `locality`, `district`, `postcode`, `city`,
106    `county`, `state`, `country` -
107    provided when it can be determined from the address
108  * `admin` - list of localised names of administrative boundaries (only with `addressdetails=1`)
109
110 Use `polygon_geojson` to output the full geometry of the object instead
111 of the centroid.
112
113 ### XML
114
115 The XML response returns one or more place objects in slightly different
116 formats depending on the API call.
117
118 #### Reverse
119
120 ```
121 <reversegeocode timestamp="Sat, 11 Aug 18 11:53:21 +0000"
122                 attribution="Data © OpenStreetMap contributors, ODbL 1.0. https://www.openstreetmap.org/copyright"
123                 querystring="lat=48.400381&lon=11.745876&zoom=5&format=xml">
124   <result place_id="179509537" osm_type="relation" osm_id="2145268" ref="BY"
125           lat="48.9467562" lon="11.4038717"
126           boundingbox="47.2701114,50.5647142,8.9763497,13.8396373">
127        Bavaria, Germany
128   </result>
129   <addressparts>
130      <state>Bavaria</state>
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
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"
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     <postcode>SW1A 2DU</postcode>
185     <country>United Kingdom</country>
186     <country_code>gb</country_code>
187   </place>
188 </searchresults>
189 ```
190
191 The attributes of the outer `searchresults` or `lookupresults` element return
192 generic information about the query:
193
194  * `timestamp` - UTC time when the response was sent
195  * `attribution` - OSM licensing information
196  * `querystring` - original query
197  * `polygon` - true when extra geometry information was requested
198  * `exclude_place_ids` - IDs of places that should be ignored in a follow-up request
199  * `more_url` - search call that will yield additional results for the query
200    just sent
201
202 The place information can be found in the `place` elements, of which there may
203 be more than one. The attributes of that element contain:
204
205  * `place_id` - reference to the Nominatim internal database ID ([see notes](#place_id-is-not-a-persistent-id))
206  * `osm_type`, `osm_id` - reference to the OSM object
207  * `ref` - content of `ref` tag if it exists
208  * `lat`, `lon` - latitude and longitude of the centroid of the object
209  * `boundingbox` - comma-separated list of corner coordinates ([see notes](#boundingbox))
210  * `place_rank` - class search rank
211  * `display_name` - full comma-separated address
212  * `class`, `type` - key and value of the main OSM tag
213  * `importance` - computed importance rank
214  * `icon` - link to class icon (if available)
215
216 When `addressdetails=1` is requested, the localised address parts appear
217 as subelements with the type of the address part.
218
219 Additional information requested with `extratags=1` and `namedetails=1` can
220 be found in extra elements as sub-element of each place.
221
222
223 ## Notes on field values
224
225 ### place_id is not a persistent id
226
227 The `place_id` is created when a Nominatim database gets installed. A
228 single place will have a different value on another server or even when
229 the same data gets re-imported. It's thus not useful to treat it as
230 permanent for later use.
231
232 The combination `osm_type`+`osm_id` is slighly better but remember in
233 OpenStreetMap mappers can delete, split, recreate places (and those
234 get a new `osm_id`), there is no link between those old and new ids.
235 Places can also change their meaning without changing their `osm_id`,
236 e.g. when a restaurant is retagged as supermarket. For a more in-depth
237 discussion see [Permanent ID](https://wiki.openstreetmap.org/wiki/Permanent_ID).
238
239 Nominatim merges some places (e.g. center node of a city with the boundary
240 relation) so `osm_type`+`osm_id`+`class_name` would be more unique.
241
242 ### boundingbox
243
244 Comma separated list of min latitude, max latitude, min longitude, max longitude.
245 The whole planet would be `-90,90,-180,180`.
246
247 Can we used to pan and center the map on the result, for example with leafletjs
248 mapping library
249 `map.fitBounds([[bbox[0],bbox[2]],[bbox[1],bbox[3]]], {padding: [20, 20], maxzoom: 16});`
250
251 Bounds crossing the antimeridian have a min latitude -180 and max latitude 180,
252 essentially covering the planet (See [issue 184](https://github.com/openstreetmap/Nominatim/issues/184)).
253
254 ### addressdetails
255
256 Address details in the xml and json formats return a list of names together
257 with a designation label. Per default the following labels may appear:
258
259  * continent
260  * country, country_code
261  * region, state, state_district, county
262  * municipality, city, town, village
263  * city_district, district, borough, suburb, subdivision
264  * hamlet, croft, isolated_dwelling
265  * neighbourhood, allotments, quarter
266  * city_block, residental, farm, farmyard, industrial, commercial, retail
267  * road
268  * house_number, house_name
269  * emergency, historic, military, natural, landuse, place, railway,
270    man_made, aerialway, boundary, amenity, aeroway, club, craft, leisure,
271    office, mountain_pass, shop, tourism, bridge, tunnel, waterway
272
273 They roughly correspond to the classification of the OpenStreetMap data
274 according to either the `place` tag or the main key of the object.