]> git.openstreetmap.org Git - nominatim.git/blob - docs/api/Output.md
Merge pull request #1557 from mtmail/document-boundingbox
[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  * `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 feature list 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
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  * `extratags` - dictionary with additional useful tags like `website` or `maxspeed`
87    (only with `extratags=1`)
88  * `namedetails` - dictionary with full list of available names including ref etc.
89
90 Use `polygon_geojson` to output the full geometry of the object instead
91 of the centroid.
92
93 ### GeocodeJSON
94
95 The GeocodeJSON format follows the
96 [GeocodeJSON spec 0.1.0](https://github.com/geocoders/geocodejson-spec).
97 The following feature attributes are implemented:
98
99  * `osm_type`, `osm_id` - reference to the OSM object (unofficial extension)
100  * `type` - value of the main tag of the object (e.g. residential, restaurant, ...)
101  * `label` - full comma-separated address
102  * `name` - localised name of the place
103  * `housenumber`, `street`, `locality`, `postcode`, `city`,
104    `district`, `county`, `state`, `country` -
105    provided when it can be determined from the address
106    (see [this issue](https://github.com/openstreetmap/Nominatim/issues/1080) for
107    current limitations on the correctness of the address) and `addressdetails=1`
108    was given
109  * `admin` - list of localised names of administrative boundaries (only with `addressdetails=1`)
110
111 Use `polygon_geojson` to output the full geometry of the object instead
112 of the centroid.
113
114 ### XML
115
116 The XML response returns one or more place objects in slightly different
117 formats depending on the API call.
118
119 #### Reverse
120
121 ```
122 <reversegeocode timestamp="Sat, 11 Aug 18 11:53:21 +0000"
123                 attribution="Data © OpenStreetMap contributors, ODbL 1.0. https://www.openstreetmap.org/copyright"
124                 querystring="lat=48.400381&lon=11.745876&zoom=5&format=xml">
125   <result place_id="179509537" osm_type="relation" osm_id="2145268" ref="BY"
126           lat="48.9467562" lon="11.4038717"
127           boundingbox="47.2701114,50.5647142,8.9763497,13.8396373">
128        Bavaria, Germany
129   </result>
130   <addressparts>
131      <state>Bavaria</state>
132      <country>Germany</country>
133      <country_code>de</country_code>
134   </addressparts>
135   <extratags>
136     <tag key="place" value="state"/>
137     <tag key="wikidata" value="Q980"/>
138     <tag key="wikipedia" value="de:Bayern"/>
139     <tag key="population" value="12520000"/>
140     <tag key="name:prefix" value="Freistaat"/>
141   </extratags>
142 </reversegeocode>
143 ```
144
145 The attributes of the outer `reversegeocode` element return generic information
146 about the query, including the time when the response was sent (in UTC),
147 attribution to OSM and the original querystring.
148
149 The place information can be found in the `result` element. The attributes of that element contain:
150
151  * `place_id` - reference to the Nominatim internal database ID ([see notes](#place_id-is-not-a-persistent-id))
152  * `osm_type`, `osm_id` - reference to the OSM object
153  * `ref` - content of `ref` tag if it exists
154  * `lat`, `lon` - latitude and longitude of the centroid of the object
155  * `boundingbox` - comma-separated list of corner coordinates ([see notes](#boundingbox))
156
157 The full address of the result can be found in the content of the
158 `result` element as a comma-separated list.
159
160 Additional information requested with `addressdetails=1`, `extratags=1` and
161 `namedetails=1` can be found in extra elements.
162
163 #### Search and Lookup
164
165 ```
166 <searchresults timestamp="Sat, 11 Aug 18 11:55:35 +0000"
167                attribution="Data © OpenStreetMap contributors, ODbL 1.0. https://www.openstreetmap.org/copyright"
168                querystring="london" polygon="false" exclude_place_ids="100149"
169                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">
170   <place place_id="100149" osm_type="node" osm_id="107775" place_rank="15"
171          boundingbox="51.3473219,51.6673219,-0.2876474,0.0323526" lat="51.5073219" lon="-0.1276474"
172          display_name="London, Greater London, England, SW1A 2DU, United Kingdom"
173          class="place" type="city" importance="0.9654895765402"
174          icon="https://nominatim.openstreetmap.org/images/mapicons/poi_place_city.p.20.png">
175     <extratags>
176       <tag key="capital" value="yes"/>
177       <tag key="website" value="http://www.london.gov.uk"/>
178       <tag key="wikidata" value="Q84"/>
179       <tag key="wikipedia" value="en:London"/>
180       <tag key="population" value="8416535"/>
181     </extratags>
182     <city>London</city>
183     <state_district>Greater London</state_district>
184     <state>England</state>
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
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
212  * `display_name` - full comma-separated address
213  * `class`, `type` - key and value of the main OSM tag
214  * `importance` - computed importance rank
215  * `icon` - link to class icon (if available)
216
217 When `addressdetails=1` is requested, the localised address parts appear
218 as subelements with the type of the address part.
219
220 Additional information requested with `extratags=1` and `namedetails=1` can
221 be found in extra elements as sub-element of each place.
222
223
224 ## Notes on field values
225
226 ### place_id is not a persistent id
227
228 The `place_id` is created when a Nominatim database gets installed. A
229 single place will have a different value on another server or even when
230 the same data gets re-imported. It's thus not useful to treat it as
231 permanent for later use.
232
233 The combination `osm_type`+`osm_id` is slighly better but remember in
234 OpenStreetMap mappers can delete, split, recreate places (and those
235 get a new `osm_id`), there is no link between those old and new ids.
236 Places can also change their meaning without changing their `osm_id`,
237 e.g. when a restaurant is retagged as supermarket. For a more in-depth
238 discussion see [Permanent ID](https://wiki.openstreetmap.org/wiki/Permanent_ID).
239
240 Nominatim merges some places (e.g. center node of a city with the boundary
241 relation) so `osm_type`+`osm_id`+`class_name` would be more unique.
242
243 ### boundingbox
244
245 Comma separated list of min latitude, max latitude, min longitude, max longitude.
246 The whole planet would be `-90,90,-180,180`.
247
248 Can we used to pan and center the map on the result, for example with leafletjs
249 mapping library
250 `map.fitBounds([[bbox[0],bbox[2]],[bbox[1],bbox[3]]], {padding: [20, 20], maxzoom: 16});`
251
252 Bounds crossing the antimeridian have a min latitude -180 and max latitude 180,
253 essentially covering the planet (See [issue 184](https://github.com/openstreetmap/Nominatim/issues/184)).