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