]> git.openstreetmap.org Git - nominatim.git/blob - docs/api/Reverse.md
6d281da8aa9850debd2cd0b3539a81d636bcba1c
[nominatim.git] / docs / api / Reverse.md
1 # Reverse Geocoding
2
3 Reverse geocoding generates an address from a coordinate given as
4 latitude and longitude.
5
6 ## How it works
7
8 The reverse geocoding API does not exactly compute the address for the
9 coordinate it receives. It works by finding the closest suitable OSM object
10 and returning its address information. This may occasionally lead to
11 unexpected results.
12
13 First of all, Nominatim only includes OSM objects in
14 its index that are suitable for searching. Small, unnamed paths for example
15 are missing from the database and can therefore not be used for reverse
16 geocoding either.
17
18 The other issue to be aware of is that the closest OSM object may not always
19 have a similar enough address to the coordinate you were requesting. For
20 example, in dense city areas it may belong to a completely different street.
21
22 ## Endpoint
23
24 The main format of the reverse API is
25
26 ```
27 https://nominatim.openstreetmap.org/reverse?lat=<value>&lon=<value>&<params>
28 ```
29
30 where `lat` and `lon` are latitude and longitude of a coordinate in WGS84
31 projection. The API returns exactly one result or an error when the coordinate
32 is in an area with no OSM data coverage.
33
34
35 !!! danger "Deprecation warning"
36     The reverse API used to allow address lookup for a single OSM object by
37     its OSM id for `[PHP-only]`. The use is considered deprecated.
38     Use the [Address Lookup API](Lookup.md) instead.
39
40 !!! danger "Deprecation warning"
41     The API can also be used with the URL
42     `https://nominatim.openstreetmap.org/reverse.php`. This is now deprecated
43     and will be removed in future versions.
44
45
46 ## Parameters
47
48 This section lists additional parameters to further influence the output.
49
50 ### Output format
51
52 | Parameter | Value | Default |
53 |-----------| ----- | ------- |
54 | format    | one of: `xml`, `json`, `jsonv2`, `geojson`, `geocodejson` | `xml` |
55
56 See [Place Output Formats](Output.md) for details on each format.
57
58
59 | Parameter | Value | Default |
60 |-----------| ----- | ------- |
61 | json_callback | function name | _unset_ |
62
63 When given, then JSON output will be wrapped in a callback function with
64 the given name. See [JSONP](https://en.wikipedia.org/wiki/JSONP) for more
65 information.
66
67 Only has an effect for JSON output formats.
68
69
70 ### Output details
71
72 | Parameter | Value | Default |
73 |-----------| ----- | ------- |
74 | addressdetails | 0 or 1 | 1 |
75
76 When set to 1, include a breakdown of the address into elements.
77 The exact content of the address breakdown depends on the output format.
78
79 !!! tip
80     If you are interested in a stable classification of address categories
81     (suburb, city, state, etc), have a look at the `geocodejson` format.
82     All other formats return classifications according to OSM tagging.
83     There is a much larger set of categories and they are not always consistent,
84     which makes them very hard to work with.
85
86
87 | Parameter | Value | Default |
88 |-----------| ----- | ------- |
89 | extratags | 0 or 1 | 0 |
90
91 When set to 1, the response include any additional information in the result
92 that is available in the database, e.g. wikipedia link, opening hours.
93
94
95 | Parameter | Value | Default |
96 |-----------| ----- | ------- |
97 | namedetails | 0 or 1 | 0 |
98
99 When set to 1, include a full list of names for the result. These may include
100 language variants, older names, references and brand.
101
102
103 ### Language of results
104
105 | Parameter | Value | Default |
106 |-----------| ----- | ------- |
107 | accept-language | browser language string | content of "Accept-Language" HTTP header |
108
109 Preferred language order for showing search results. This may either be
110 a simple comma-separated list of language codes or have the same format
111 as the ["Accept-Language" HTTP header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language).
112
113 !!! tip
114     First-time users of Nominatim tend to be confused that they get different
115     results when using Nominatim in the browser versus in a command-line tool
116     like wget or curl. The command-line tools
117     usually don't send any Accept-Language header, prompting Nominatim
118     to show results in the local language. Browsers on the contratry always
119     send the currently chosen browser language.
120
121
122 ### Result restriction
123
124 | Parameter | Value | Default |
125 |-----------| ----- | ------- |
126 | zoom      | 0-18  | 18      |
127
128 Level of detail required for the address. This is a number that
129 corresponds roughly to the zoom level used in XYZ tile sources in frameworks
130 like Leaflet.js, Openlayers etc.
131 In terms of address details the zoom levels are as follows:
132
133  zoom | address detail
134  -----|---------------
135   3   | country
136   5   | state
137   8   | county
138   10  | city
139   12  | town / borough
140   13  | village / suburb
141   14  | neighbourhood
142   15  | any settlement
143   16  | major streets
144   17  | major and minor streets
145   18  | building
146
147
148 | Parameter | Value | Default |
149 |-----------| ----- | ------- |
150 | layer     | comma-separated list of: `address`, `poi`, `railway`, `natural`, `manmade` | _unset_ (no restriction) |
151
152 **`[Python-only]`**
153
154 The layer filter allows to select places by themes.
155
156 The `address` layer contains all places that make up an address:
157 address points with house numbers, streets, inhabited places (suburbs, villages,
158 cities, states etc.) and administrative boundaries.
159
160 The `poi` layer selects all point of interest. This includes classic points
161 of interest like restaurants, shops, hotels but also less obvious features
162 like recycling bins, guideposts or benches.
163
164 The `railway` layer includes railway infrastructure like tracks.
165 Note that in Nominatim's standard configuration, only very few railway
166 features are imported into the database.
167
168 The `natural` layer collects feautures like rivers, lakes and mountains while
169 the `manmade` layer functions as a catch-all for features not covered by the
170 other layers.
171
172
173 ### Polygon output
174
175 | Parameter | Value  | Default |
176 |-----------| -----  | ------- |
177 | polygon_geojson | 0 or 1 | 0 |
178 | polygon_kml     | 0 or 1 | 0 |
179 | polygon_svg     | 0 or 1 | 0 |
180 | polygon_text    | 0 or 1 | 0 |
181
182 Add the full geometry of the place to the result output. Output formats
183 in GeoJSON, KML, SVG or WKT are supported. Only one of these
184 options can be used at a time.
185
186 | Parameter | Value  | Default |
187 |-----------| -----  | ------- |
188 | polygon_threshold | floating-point number | 0.0 |
189
190 When one of the polygon_* outputs is chosen, return a simplified version
191 of the output geometry. The parameter describes the
192 tolerance in degrees with which the geometry may differ from the original
193 geometry. Topology is preserved in the geometry.
194
195
196 ### Other
197
198 | Parameter | Value  | Default |
199 |-----------| -----  | ------- |
200 | email     | valid email address | _unset_ |
201
202 If you are making large numbers of request please include an appropriate email
203 address to identify your requests. See Nominatim's
204 [Usage Policy](https://operations.osmfoundation.org/policies/nominatim/) for more details.
205
206
207 | Parameter | Value  | Default |
208 |-----------| -----  | ------- |
209 | debug     | 0 or 1 | 0       |
210
211 Output assorted developer debug information. Data on internals of Nominatim's
212 "search loop" logic, and SQL queries. The output is HTML format.
213 This overrides the specified machine readable format.
214
215
216 ## Examples
217
218 * [https://nominatim.openstreetmap.org/reverse?format=xml&lat=52.5487429714954&lon=-1.81602098644987&zoom=18&addressdetails=1](https://nominatim.openstreetmap.org/reverse?format=xml&lat=52.5487429714954&lon=-1.81602098644987&zoom=18&addressdetails=1)
219
220 ```xml
221   <reversegeocode timestamp="Fri, 06 Nov 09 16:33:54 +0000" querystring="...">
222     <result place_id="1620612" osm_type="node" osm_id="452010817">
223       135, Pilkington Avenue, Wylde Green, City of Birmingham, West Midlands (county), B72, United Kingdom
224     </result>
225     <addressparts>
226       <house_number>135</house_number>
227       <road>Pilkington Avenue</road>
228       <village>Wylde Green</village>
229       <town>Sutton Coldfield</town>
230       <city>City of Birmingham</city>
231       <county>West Midlands (county)</county>
232       <postcode>B72</postcode>
233       <country>United Kingdom</country>
234       <country_code>gb</country_code>
235     </addressparts>
236   </reversegeocode>
237 ```
238
239 ##### Example with `format=jsonv2`
240
241 * [https://nominatim.openstreetmap.org/reverse?format=jsonv2&lat=-34.44076&lon=-58.70521](https://nominatim.openstreetmap.org/reverse?format=jsonv2&lat=-34.44076&lon=-58.70521)
242
243 ```json
244 {
245   "place_id":"134140761",
246   "licence":"Data © OpenStreetMap contributors, ODbL 1.0. https:\/\/www.openstreetmap.org\/copyright",
247   "osm_type":"way",
248   "osm_id":"280940520",
249   "lat":"-34.4391708",
250   "lon":"-58.7064573",
251   "place_rank":"26",
252   "category":"highway",
253   "type":"motorway",
254   "importance":"0.1",
255   "addresstype":"road",
256   "display_name":"Autopista Pedro Eugenio Aramburu, El Triángulo, Partido de Malvinas Argentinas, Buenos Aires, 1.619, Argentina",
257   "name":"Autopista Pedro Eugenio Aramburu",
258   "address":{
259     "road":"Autopista Pedro Eugenio Aramburu",
260     "village":"El Triángulo",
261     "state_district":"Partido de Malvinas Argentinas",
262     "state":"Buenos Aires",
263     "postcode":"1.619",
264     "country":"Argentina",
265     "country_code":"ar"
266   },
267   "boundingbox":["-34.44159","-34.4370994","-58.7086067","-58.7044712"]
268 }
269 ```
270
271 ##### Example with `format=geojson`
272
273 * [https://nominatim.openstreetmap.org/reverse?format=geojson&lat=44.50155&lon=11.33989](https://nominatim.openstreetmap.org/reverse?format=geojson&lat=44.50155&lon=11.33989)
274
275 ```json
276 {
277   "type": "FeatureCollection",
278   "licence": "Data © OpenStreetMap contributors, ODbL 1.0. https://osm.org/copyright",
279   "features": [
280     {
281       "type": "Feature",
282       "properties": {
283         "place_id": "18512203",
284         "osm_type": "node",
285         "osm_id": "1704756187",
286         "place_rank": "30",
287         "category": "place",
288         "type": "house",
289         "importance": "0",
290         "addresstype": "place",
291         "name": null,
292         "display_name": "71, Via Guglielmo Marconi, Saragozza-Porto, Bologna, BO, Emilia-Romagna, 40122, Italy",
293         "address": {
294           "house_number": "71",
295           "road": "Via Guglielmo Marconi",
296           "suburb": "Saragozza-Porto",
297           "city": "Bologna",
298           "county": "BO",
299           "state": "Emilia-Romagna",
300           "postcode": "40122",
301           "country": "Italy",
302           "country_code": "it"
303         }
304       },
305       "bbox": [
306         11.3397676,
307         44.5014307,
308         11.3399676,
309         44.5016307
310       ],
311       "geometry": {
312         "type": "Point",
313         "coordinates": [
314           11.3398676,
315           44.5015307
316         ]
317       }
318     }
319   ]
320 }
321 ```
322
323 ##### Example with `format=geocodejson`
324
325 [https://nominatim.openstreetmap.org/reverse?format=geocodejson&lat=60.2299&lon=11.1663](https://nominatim.openstreetmap.org/reverse?format=geocodejson&lat=60.2299&lon=11.1663)
326
327 ```json
328 {
329   "type": "FeatureCollection",
330   "geocoding": {
331     "version": "0.1.0",
332     "attribution": "Data © OpenStreetMap contributors, ODbL 1.0. https://osm.org/copyright",
333     "licence": "ODbL",
334     "query": "60.229917843587,11.16630979382"
335   },
336   "features": {
337     "type": "Feature",
338     "properties": {
339       "geocoding": {
340         "place_id": "42700574",
341         "osm_type": "node",
342         "osm_id": "3110596255",
343         "type": "house",
344         "accuracy": 0,
345         "label": "1, Løvenbergvegen, Mogreina, Ullensaker, Akershus, 2054, Norway",
346         "name": null,
347         "housenumber": "1",
348         "street": "Løvenbergvegen",
349         "postcode": "2054",
350         "county": "Akershus",
351         "country": "Norway",
352         "admin": {
353           "level7": "Ullensaker",
354           "level4": "Akershus",
355           "level2": "Norway"
356         }
357       }
358     },
359     "geometry": {
360       "type": "Point",
361       "coordinates": [
362         11.1658572,
363         60.2301296
364       ]
365     }
366   }
367 }
368 ```
369