docs/api/Reverse.md

   1 ## Reverse Geocoding
   2
   3 Reverse geocoding generates an address from a latitude and longitude.  The optional `zoom` parameter specifies the level of detail required in terms of something suitable for a Leaflet.js/OpenLayers/etc. zoom level.
   4
   5 ### Parameters
   6 ```
   7 https://nominatim.openstreetmap.org/reverse?<query>
   8 ```
   9
  10 * `format=[xml|json|jsonv2|geojson|geocodejson]`
  11
  12     * Output format
  13     * defaults to `xml`
  14     * `jsonv2` adds the next fields to response:
  15         * `place_rank`
  16         * `category`
  17         * `type`
  18         * `importance`
  19         * `addresstype`
  20
  21 * `json_callback=<string>`
  22
  23     * Wrap json output in a callback function (JSONP) i.e. `<string>(<json>)`
  24
  25 * `accept-language=<browser language string>`
  26
  27     * Preferred language order for showing search results, overrides the value specified in the "Accept-Language" HTTP header.
  28     * Either uses standard rfc2616 accept-language string or a simple comma separated list of language codes.
  29
  30 * `osm_type=[N|W|R]` `osm_id=<value>`
  31     * A specific osm node / way / relation to return an address for
  32     * **Please use this in preference to lat/lon where possible**
  33
  34 * `lat=<value>` `lon=<value>`
  35     * The location to generate an address for
  36
  37 * `zoom=[0-18]`
  38     * Level of detail required where `0` is country and `18` is house/building
  39
  40 * `addressdetails=[0|1]`
  41     * defaults to 0
  42     * Include a breakdown of the address into elements
  43
  44 * `email=<valid email address>`
  45
  46     * If you are making large numbers of request please include a valid email address or alternatively include your email address as part of the User-Agent string.
  47     * This information will be kept confidential and only used to contact you in the event of a problem, see [Usage Policy](https://operations.osmfoundation.org/policies/nominatim/) for more details.
  48
  49 * `polygon_geojson=1`
  50     * Output geometry of results in geojson format.
  51
  52 * `polygon_kml=1`
  53     * Output geometry of results in kml format.
  54
  55 * `polygon_svg=1`
  56     * Output geometry of results in svg format.
  57
  58 * `polygon_text=1`
  59     * Output geometry of results as a WKT.
  60
  61 * `polygon_threshold=0.0`
  62     * defaults to 0.0
  63     * Simplify the output geometry before returning. The parameter is the
  64       tolerance in degrees with which the geometry may differ from the original
  65       geometry. Topology is preserved in the result.
  66
  67 * `extratags=1`
  68     * Include additional information in the result if available, e.g. wikipedia link, opening hours.
  69
  70 * `namedetails=1`
  71     * Include a list of alternative names in the results.
  72     * These may include language variants, references, operator and brand.
  73
  74 ### Example
  75
  76 * [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)
  77
  78 ```xml
  79   <reversegeocode timestamp="Fri, 06 Nov 09 16:33:54 +0000" querystring="...">
  80     <result place_id="1620612" osm_type="node" osm_id="452010817">
  81       135, Pilkington Avenue, Wylde Green, City of Birmingham, West Midlands (county), B72, United Kingdom
  82     </result>
  83     <addressparts>
  84       <house_number>135</house_number>
  85       <road>Pilkington Avenue</road>
  86       <village>Wylde Green</village>
  87       <town>Sutton Coldfield</town>
  88       <city>City of Birmingham</city>
  89       <county>West Midlands (county)</county>
  90       <postcode>B72</postcode>
  91       <country>United Kingdom</country>
  92       <country_code>gb</country_code>
  93     </addressparts>
  94   </reversegeocode>
  95 ```
  96
  97 ##### Example with `format=jsonv2`
  98
  99 * [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)
 100
 101 ```json
 102 {
 103   "place_id":"134140761",
 104   "licence":"Data © OpenStreetMap contributors, ODbL 1.0. http:\/\/www.openstreetmap.org\/copyright",
 105   "osm_type":"way",
 106   "osm_id":"280940520",
 107 "lat":"-34.4391708",
 108   "lon":"-58.7064573",
 109   "place_rank":"26",
 110   "category":"highway",
 111   "type":"motorway",
 112   "importance":"0.1",
 113   "addresstype":"road",
 114   "display_name":"Autopista Pedro Eugenio Aramburu, El Triángulo, Partido de Malvinas Argentinas, Buenos Aires, 1.619, Argentina",
 115   "name":"Autopista Pedro Eugenio Aramburu",
 116   "address":{
 117     "road":"Autopista Pedro Eugenio Aramburu",
 118     "village":"El Triángulo",
 119     "state_district":"Partido de Malvinas Argentinas",
 120     "state":"Buenos Aires",
 121     "postcode":"1.619",
 122     "country":"Argentina",
 123     "country_code":"ar"
 124   },
 125   "boundingbox":["-34.44159","-34.4370994","-58.7086067","-58.7044712"]
 126 }
 127 ```
 128
 129 ##### Example with `format=geojson`
 130
 131 * [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)
 132
 133 ```json
 134 {
 135   "type": "FeatureCollection",
 136   "licence": "Data © OpenStreetMap contributors, ODbL 1.0. https://osm.org/copyright",
 137   "features": [
 138     {
 139       "type": "Feature",
 140       "properties": {
 141         "place_id": "18512203",
 142         "osm_type": "node",
 143         "osm_id": "1704756187",
 144         "place_rank": "30",
 145         "category": "place",
 146         "type": "house",
 147         "importance": "0",
 148         "addresstype": "place",
 149         "name": null,
 150         "display_name": "71, Via Guglielmo Marconi, Saragozza-Porto, Bologna, BO, Emilia-Romagna, 40122, Italy",
 151         "address": {
 152           "house_number": "71",
 153           "road": "Via Guglielmo Marconi",
 154           "suburb": "Saragozza-Porto",
 155           "city": "Bologna",
 156           "county": "BO",
 157           "state": "Emilia-Romagna",
 158           "postcode": "40122",
 159           "country": "Italy",
 160           "country_code": "it"
 161         }
 162       },
 163       "bbox": [
 164         11.3397676,
 165         44.5014307,
 166         11.3399676,
 167         44.5016307
 168       ],
 169       "geometry": {
 170         "type": "Point",
 171         "coordinates": [
 172           11.3398676,
 173           44.5015307
 174         ]
 175       }
 176     }
 177   ]
 178 }
 179 ```
 180
 181 ##### Example with `format=geocodejson`
 182
 183 [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)
 184
 185 ```json
 186 {
 187   "type": "FeatureCollection",
 188   "geocoding": {
 189     "version": "0.1.0",
 190     "attribution": "Data © OpenStreetMap contributors, ODbL 1.0. https://osm.org/copyright",
 191     "licence": "ODbL",
 192     "query": "60.229917843587,11.16630979382"
 193   },
 194   "features": {
 195     "type": "Feature",
 196     "properties": {
 197       "geocoding": {
 198         "place_id": "42700574",
 199         "osm_type": "node",
 200         "osm_id": "3110596255",
 201         "type": "house",
 202         "accuracy": 0,
 203         "label": "1, Løvenbergvegen, Mogreina, Ullensaker, Akershus, 2054, Norway",
 204         "name": null,
 205         "housenumber": "1",
 206         "street": "Løvenbergvegen",
 207         "postcode": "2054",
 208         "county": "Akershus",
 209         "country": "Norway",
 210         "admin": {
 211           "level7": "Ullensaker",
 212           "level4": "Akershus",
 213           "level2": "Norway"
 214         }
 215       }
 216     },
 217     "geometry": {
 218       "type": "Point",
 219       "coordinates": [
 220         11.1658572,
 221         60.2301296
 222       ]
 223     }
 224   }
 225 }
 226 ```
 227
 228 ### Hierarchy
 229
 230 * Admin level => XML entity
 231     * 2 => `<country>`
 232     * 4 => `<state>`
 233     * 5 => `<state_district>`
 234     * 6
 235     * 7 => `<county>`
 236     * 8 => `<village>`
 237     * 9 => `<city_district>`
 238     * 10 => `<suburb>`