]> git.openstreetmap.org Git - nominatim.git/blob - docs/api/Reverse.md
'read_config' is no longer a fixture
[nominatim.git] / docs / api / Reverse.md
1 # Reverse Geocoding
2
3 Reverse geocoding generates an address from a latitude and longitude.
4
5 ## How it works
6
7 The reverse geocoding API does not exactly compute the address for the
8 coordinate it receives. It works by finding the closest suitable OSM object
9 and returning its address information. This may occasionally lead to
10 unexpected results.
11
12 First of all, Nominatim only includes OSM objects in
13 its index that are suitable for searching. Small, unnamed paths for example
14 are missing from the database and can therefore not be used for reverse
15 geocoding either.
16
17 The other issue to be aware of is that the closest OSM object may not always
18 have a similar enough address to the coordinate you were requesting. For
19 example, in dense city areas it may belong to a completely different street.
20
21
22 ## Parameters
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 longitutde 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 Additional paramters are accepted as listed below.
35
36 !!! warning "Deprecation warning"
37     The reverse API used to allow address lookup for a single OSM object by
38     its OSM id. This use is now deprecated. Use the [Address Lookup API](../Lookup)
39     instead.
40
41 ### Output format
42
43 * `format=[xml|json|jsonv2|geojson|geocodejson]`
44
45 See [Place Output Formats](Output.md) for details on each format. (Default: xml)
46
47 * `json_callback=<string>`
48
49 Wrap JSON output in a callback function ([JSONP](https://en.wikipedia.org/wiki/JSONP)) i.e. `<string>(<json>)`.
50 Only has an effect for JSON output formats.
51
52 ### Output details
53
54 * `addressdetails=[0|1]`
55
56 Include a breakdown of the address into elements. (Default: 1)
57
58
59 * `extratags=[0|1]`
60
61 Include additional information in the result if available,
62 e.g. wikipedia link, opening hours. (Default: 0)
63
64
65 * `namedetails=[0|1]`
66
67 Include a list of alternative names in the results. These may include
68 language variants, references, operator and brand. (Default: 0)
69
70
71 ### Language of results
72
73 * `accept-language=<browser language string>`
74
75 Preferred language order for showing search results, overrides the value
76 specified in the "Accept-Language" HTTP header.
77 Either use a standard RFC2616 accept-language string or a simple
78 comma-separated list of language codes.
79
80 ### Result limitation
81
82 * `zoom=[0-18]`
83
84 Level of detail required for the address. Default: 18. This is a number that
85 corresponds roughly to the zoom level used in XYZ tile sources in frameworks
86 like Leaflet.js, Openlayers etc.
87 In terms of address details the zoom levels are as follows:
88
89  zoom | address detail
90  -----|---------------
91   3   | country
92   5   | state
93   8   | county
94   10  | city
95   14  | suburb
96   16  | major streets
97   17  | major and minor streets
98   18  | building
99
100
101 ### Polygon output
102
103 * `polygon_geojson=1`
104 * `polygon_kml=1`
105 * `polygon_svg=1`
106 * `polygon_text=1`
107
108 Output geometry of results as a GeoJSON, KML, SVG or WKT. Only one of these
109 options can be used at a time. (Default: 0)
110
111 * `polygon_threshold=0.0`
112
113 Return a simplified version of the output geometry. The parameter is the
114 tolerance in degrees with which the geometry may differ from the original
115 geometry. Topology is preserved in the result. (Default: 0.0)
116
117 ### Other
118
119 * `email=<valid email address>`
120
121 If you are making large numbers of request please include an appropriate email
122 address to identify your requests. See Nominatim's [Usage Policy](https://operations.osmfoundation.org/policies/nominatim/) for more details.
123
124
125 * `debug=[0|1]`
126
127 Output assorted developer debug information. Data on internals of Nominatim's
128 "Search Loop" logic, and SQL queries. The output is (rough) HTML format.
129 This overrides the specified machine readable format. (Default: 0)
130
131
132 ## Examples
133
134 * [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)
135
136 ```xml
137   <reversegeocode timestamp="Fri, 06 Nov 09 16:33:54 +0000" querystring="...">
138     <result place_id="1620612" osm_type="node" osm_id="452010817">
139       135, Pilkington Avenue, Wylde Green, City of Birmingham, West Midlands (county), B72, United Kingdom
140     </result>
141     <addressparts>
142       <house_number>135</house_number>
143       <road>Pilkington Avenue</road>
144       <village>Wylde Green</village>
145       <town>Sutton Coldfield</town>
146       <city>City of Birmingham</city>
147       <county>West Midlands (county)</county>
148       <postcode>B72</postcode>
149       <country>United Kingdom</country>
150       <country_code>gb</country_code>
151     </addressparts>
152   </reversegeocode>
153 ```
154
155 ##### Example with `format=jsonv2`
156
157 * [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)
158
159 ```json
160 {
161   "place_id":"134140761",
162   "licence":"Data © OpenStreetMap contributors, ODbL 1.0. https:\/\/www.openstreetmap.org\/copyright",
163   "osm_type":"way",
164   "osm_id":"280940520",
165   "lat":"-34.4391708",
166   "lon":"-58.7064573",
167   "place_rank":"26",
168   "category":"highway",
169   "type":"motorway",
170   "importance":"0.1",
171   "addresstype":"road",
172   "display_name":"Autopista Pedro Eugenio Aramburu, El Triángulo, Partido de Malvinas Argentinas, Buenos Aires, 1.619, Argentina",
173   "name":"Autopista Pedro Eugenio Aramburu",
174   "address":{
175     "road":"Autopista Pedro Eugenio Aramburu",
176     "village":"El Triángulo",
177     "state_district":"Partido de Malvinas Argentinas",
178     "state":"Buenos Aires",
179     "postcode":"1.619",
180     "country":"Argentina",
181     "country_code":"ar"
182   },
183   "boundingbox":["-34.44159","-34.4370994","-58.7086067","-58.7044712"]
184 }
185 ```
186
187 ##### Example with `format=geojson`
188
189 * [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)
190
191 ```json
192 {
193   "type": "FeatureCollection",
194   "licence": "Data © OpenStreetMap contributors, ODbL 1.0. https://osm.org/copyright",
195   "features": [
196     {
197       "type": "Feature",
198       "properties": {
199         "place_id": "18512203",
200         "osm_type": "node",
201         "osm_id": "1704756187",
202         "place_rank": "30",
203         "category": "place",
204         "type": "house",
205         "importance": "0",
206         "addresstype": "place",
207         "name": null,
208         "display_name": "71, Via Guglielmo Marconi, Saragozza-Porto, Bologna, BO, Emilia-Romagna, 40122, Italy",
209         "address": {
210           "house_number": "71",
211           "road": "Via Guglielmo Marconi",
212           "suburb": "Saragozza-Porto",
213           "city": "Bologna",
214           "county": "BO",
215           "state": "Emilia-Romagna",
216           "postcode": "40122",
217           "country": "Italy",
218           "country_code": "it"
219         }
220       },
221       "bbox": [
222         11.3397676,
223         44.5014307,
224         11.3399676,
225         44.5016307
226       ],
227       "geometry": {
228         "type": "Point",
229         "coordinates": [
230           11.3398676,
231           44.5015307
232         ]
233       }
234     }
235   ]
236 }
237 ```
238
239 ##### Example with `format=geocodejson`
240
241 [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)
242
243 ```json
244 {
245   "type": "FeatureCollection",
246   "geocoding": {
247     "version": "0.1.0",
248     "attribution": "Data © OpenStreetMap contributors, ODbL 1.0. https://osm.org/copyright",
249     "licence": "ODbL",
250     "query": "60.229917843587,11.16630979382"
251   },
252   "features": {
253     "type": "Feature",
254     "properties": {
255       "geocoding": {
256         "place_id": "42700574",
257         "osm_type": "node",
258         "osm_id": "3110596255",
259         "type": "house",
260         "accuracy": 0,
261         "label": "1, Løvenbergvegen, Mogreina, Ullensaker, Akershus, 2054, Norway",
262         "name": null,
263         "housenumber": "1",
264         "street": "Løvenbergvegen",
265         "postcode": "2054",
266         "county": "Akershus",
267         "country": "Norway",
268         "admin": {
269           "level7": "Ullensaker",
270           "level4": "Akershus",
271           "level2": "Norway"
272         }
273       }
274     },
275     "geometry": {
276       "type": "Point",
277       "coordinates": [
278         11.1658572,
279         60.2301296
280       ]
281     }
282   }
283 }
284 ```
285