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 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 Additional parameters 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.md)
  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   12  | town / borough
  96   13  | village / suburb
  97   14  | neighbourhood
  98   15  | locality
  99   16  | major streets
 100   17  | major and minor streets
 101   18  | building
 102
 103
 104 ### Polygon output
 105
 106 * `polygon_geojson=1`
 107 * `polygon_kml=1`
 108 * `polygon_svg=1`
 109 * `polygon_text=1`
 110
 111 Output geometry of results as a GeoJSON, KML, SVG or WKT. Only one of these
 112 options can be used at a time. (Default: 0)
 113
 114 * `polygon_threshold=0.0`
 115
 116 Return a simplified version of the output geometry. The parameter is the
 117 tolerance in degrees with which the geometry may differ from the original
 118 geometry. Topology is preserved in the result. (Default: 0.0)
 119
 120 ### Other
 121
 122 * `email=<valid email address>`
 123
 124 If you are making a large number of requests, please include an appropriate email
 125 address to identify your requests. See Nominatim's [Usage Policy](https://operations.osmfoundation.org/policies/nominatim/) for more details.
 126
 127
 128 * `debug=[0|1]`
 129
 130 Output assorted developer debug information. Data on internals of Nominatim's
 131 "Search Loop" logic, and SQL queries. The output is (rough) HTML format.
 132 This overrides the specified machine readable format. (Default: 0)
 133
 134
 135 ## Examples
 136
 137 * [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)
 138
 139 ```xml
 140   <reversegeocode timestamp="Fri, 06 Nov 09 16:33:54 +0000" querystring="...">
 141     <result place_id="1620612" osm_type="node" osm_id="452010817">
 142       135, Pilkington Avenue, Wylde Green, City of Birmingham, West Midlands (county), B72, United Kingdom
 143     </result>
 144     <addressparts>
 145       <house_number>135</house_number>
 146       <road>Pilkington Avenue</road>
 147       <village>Wylde Green</village>
 148       <town>Sutton Coldfield</town>
 149       <city>City of Birmingham</city>
 150       <county>West Midlands (county)</county>
 151       <postcode>B72</postcode>
 152       <country>United Kingdom</country>
 153       <country_code>gb</country_code>
 154     </addressparts>
 155   </reversegeocode>
 156 ```
 157
 158 ##### Example with `format=jsonv2`
 159
 160 * [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)
 161
 162 ```json
 163 {
 164   "place_id":"134140761",
 165   "licence":"Data © OpenStreetMap contributors, ODbL 1.0. https:\/\/www.openstreetmap.org\/copyright",
 166   "osm_type":"way",
 167   "osm_id":"280940520",
 168   "lat":"-34.4391708",
 169   "lon":"-58.7064573",
 170   "place_rank":"26",
 171   "category":"highway",
 172   "type":"motorway",
 173   "importance":"0.1",
 174   "addresstype":"road",
 175   "display_name":"Autopista Pedro Eugenio Aramburu, El Triángulo, Partido de Malvinas Argentinas, Buenos Aires, 1.619, Argentina",
 176   "name":"Autopista Pedro Eugenio Aramburu",
 177   "address":{
 178     "road":"Autopista Pedro Eugenio Aramburu",
 179     "village":"El Triángulo",
 180     "state_district":"Partido de Malvinas Argentinas",
 181     "state":"Buenos Aires",
 182     "postcode":"1.619",
 183     "country":"Argentina",
 184     "country_code":"ar"
 185   },
 186   "boundingbox":["-34.44159","-34.4370994","-58.7086067","-58.7044712"]
 187 }
 188 ```
 189
 190 ##### Example with `format=geojson`
 191
 192 * [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)
 193
 194 ```json
 195 {
 196   "type": "FeatureCollection",
 197   "licence": "Data © OpenStreetMap contributors, ODbL 1.0. https://osm.org/copyright",
 198   "features": [
 199     {
 200       "type": "Feature",
 201       "properties": {
 202         "place_id": "18512203",
 203         "osm_type": "node",
 204         "osm_id": "1704756187",
 205         "place_rank": "30",
 206         "category": "place",
 207         "type": "house",
 208         "importance": "0",
 209         "addresstype": "place",
 210         "name": null,
 211         "display_name": "71, Via Guglielmo Marconi, Saragozza-Porto, Bologna, BO, Emilia-Romagna, 40122, Italy",
 212         "address": {
 213           "house_number": "71",
 214           "road": "Via Guglielmo Marconi",
 215           "suburb": "Saragozza-Porto",
 216           "city": "Bologna",
 217           "county": "BO",
 218           "state": "Emilia-Romagna",
 219           "postcode": "40122",
 220           "country": "Italy",
 221           "country_code": "it"
 222         }
 223       },
 224       "bbox": [
 225         11.3397676,
 226         44.5014307,
 227         11.3399676,
 228         44.5016307
 229       ],
 230       "geometry": {
 231         "type": "Point",
 232         "coordinates": [
 233           11.3398676,
 234           44.5015307
 235         ]
 236       }
 237     }
 238   ]
 239 }
 240 ```
 241
 242 ##### Example with `format=geocodejson`
 243
 244 [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)
 245
 246 ```json
 247 {
 248   "type": "FeatureCollection",
 249   "geocoding": {
 250     "version": "0.1.0",
 251     "attribution": "Data © OpenStreetMap contributors, ODbL 1.0. https://osm.org/copyright",
 252     "licence": "ODbL",
 253     "query": "60.229917843587,11.16630979382"
 254   },
 255   "features": {
 256     "type": "Feature",
 257     "properties": {
 258       "geocoding": {
 259         "place_id": "42700574",
 260         "osm_type": "node",
 261         "osm_id": "3110596255",
 262         "type": "house",
 263         "accuracy": 0,
 264         "label": "1, Løvenbergvegen, Mogreina, Ullensaker, Akershus, 2054, Norway",
 265         "name": null,
 266         "housenumber": "1",
 267         "street": "Løvenbergvegen",
 268         "postcode": "2054",
 269         "county": "Akershus",
 270         "country": "Norway",
 271         "admin": {
 272           "level7": "Ullensaker",
 273           "level4": "Akershus",
 274           "level2": "Norway"
 275         }
 276       }
 277     },
 278     "geometry": {
 279       "type": "Point",
 280       "coordinates": [
 281         11.1658572,
 282         60.2301296
 283       ]
 284     }
 285   }
 286 }
 287 ```
 288