docs/api/Reverse.md

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