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]`
  11
  12     * Output format.
  13     * `jsonv2` adds the next fields to response:
  14         * `place_rank`
  15         * `category`
  16         * `type`
  17         * `importance`
  18         * `addresstype`
  19
  20 * `json_callback=<string>`
  21
  22     * Wrap json output in a callback function (JSONP) i.e. `<string>(<json>)`
  23
  24 * `accept-language=<browser language string>`
  25
  26     * Preferred language order for showing search results, overrides the value specified in the "Accept-Language" HTTP header.
  27     * Either uses standard rfc2616 accept-language string or a simple comma separated list of language codes.
  28
  29 * `osm_type=[N|W|R]` `osm_id=<value>`
  30     * A specific osm node / way / relation to return an address for
  31     * **Please use this in preference to lat/lon where possible**
  32
  33 * `lat=<value>` `lon=<value>`
  34     * The location to generate an address for
  35
  36 * `zoom=[0-18]`
  37     * Level of detail required where `0` is country and `18` is house/building
  38
  39 * `addressdetails=[0|1]`
  40     * defaults to 0
  41     * Include a breakdown of the address into elements
  42
  43 * `email=<valid email address>`
  44
  45     * 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.
  46     * 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.
  47
  48 * `polygon_geojson=1`
  49     * Output geometry of results in geojson format.
  50
  51 * `polygon_kml=1`
  52     * Output geometry of results in kml format.
  53
  54 * `polygon_svg=1`
  55     * Output geometry of results in svg format.
  56
  57 * `polygon_text=1`
  58     * Output geometry of results as a WKT.
  59
  60 * `extratags=1`
  61     * Include additional information in the result if available, e.g. wikipedia link, opening hours.
  62
  63 * `namedetails=1`
  64     * Include a list of alternative names in the results.
  65     * These may include language variants, references, operator and brand.
  66
  67 ### Example
  68
  69 * [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)
  70
  71 ```xml
  72   <reversegeocode timestamp="Fri, 06 Nov 09 16:33:54 +0000" querystring="...">
  73     <result place_id="1620612" osm_type="node" osm_id="452010817">
  74       135, Pilkington Avenue, Wylde Green, City of Birmingham, West Midlands (county), B72, United Kingdom
  75     </result>
  76     <addressparts>
  77       <house_number>135</house_number>
  78       <road>Pilkington Avenue</road>
  79       <village>Wylde Green</village>
  80       <town>Sutton Coldfield</town>
  81       <city>City of Birmingham</city>
  82       <county>West Midlands (county)</county>
  83       <postcode>B72</postcode>
  84       <country>United Kingdom</country>
  85       <country_code>gb</country_code>
  86     </addressparts>
  87   </reversegeocode>
  88 ```
  89
  90 ##### Example with `format=jsonv2`
  91
  92 * [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)
  93
  94 ```json
  95 {
  96   "place_id":"134140761",
  97   "licence":"Data © OpenStreetMap contributors, ODbL 1.0. http:\/\/www.openstreetmap.org\/copyright",
  98   "osm_type":"way",
  99   "osm_id":"280940520",
 100 "lat":"-34.4391708",
 101   "lon":"-58.7064573",
 102   "place_rank":"26",
 103   "category":"highway",
 104   "type":"motorway",
 105   "importance":"0.1",
 106   "addresstype":"road",
 107   "display_name":"Autopista Pedro Eugenio Aramburu, El Triángulo, Partido de Malvinas Argentinas, Buenos Aires, 1.619, Argentina",
 108   "name":"Autopista Pedro Eugenio Aramburu",
 109   "address":{
 110     "road":"Autopista Pedro Eugenio Aramburu",
 111     "village":"El Triángulo",
 112     "state_district":"Partido de Malvinas Argentinas",
 113     "state":"Buenos Aires",
 114     "postcode":"1.619",
 115     "country":"Argentina",
 116     "country_code":"ar"
 117   },
 118   "boundingbox":["-34.44159","-34.4370994","-58.7086067","-58.7044712"]
 119 }
 120 ```
 121
 122 ### Hierarchy
 123
 124 * Admin level => XML entity
 125     * 2 => `<country>`
 126     * 4 => `<state>`
 127     * 5 => `<state_district>`
 128     * 6
 129     * 7 => `<county>`
 130     * 8 => `<village>`
 131     * 9 => `<city_district>`
 132     * 10 => `<suburb>`