docs/api/Lookup.md

   1 # Address lookup
   2
   3 The lookup API allows to query the address and other details of one or
   4 multiple OSM objects like node, way or relation.
   5
   6 ## Parameters
   7
   8 The lookup API has the following format:
   9
  10 ```
  11   https://nominatim.openstreetmap.org/lookup?osm_ids=[N|W|R]<value>,…,…,&<params>
  12 ```
  13
  14 `osm_ids` is mandatory and must contain a comma-separated list of OSM ids each
  15 prefixed with its type, one of node(N), way(W) or relation(R). Up to 50 ids
  16 can be queried at the same time.
  17
  18 Additional optional parameters are explained below.
  19
  20 ### Output format
  21
  22 * `format=[xml|json|jsonv2|geojson|geocodejson]`
  23
  24 See [Place Output Formats](Output.md) for details on each format. (Default: xml)
  25
  26 * `json_callback=<string>`
  27
  28 Wrap JSON output in a callback function (JSONP) i.e. `<string>(<json>)`.
  29 Only has an effect for JSON output formats.
  30
  31 ### Output details
  32
  33 * `addressdetails=[0|1]`
  34
  35 Include a breakdown of the address into elements. (Default: 0)
  36
  37
  38 * `extratags=[0|1]`
  39
  40 Include additional information in the result if available,
  41 e.g. wikipedia link, opening hours. (Default: 0)
  42
  43
  44 * `namedetails=[0|1]`
  45
  46 Include a list of alternative names in the results. These may include
  47 language variants, references, operator and brand. (Default: 0)
  48
  49
  50 ### Language of results
  51
  52 * `accept-language=<browser language string>`
  53
  54 Preferred language order for showing search results, overrides the value
  55 specified in the "Accept-Language" HTTP header.
  56 Either use a standard RFC2616 accept-language string or a simple
  57 comma-separated list of language codes.
  58
  59 ### Polygon output
  60
  61 * `polygon_geojson=1`
  62 * `polygon_kml=1`
  63 * `polygon_svg=1`
  64 * `polygon_text=1`
  65
  66 Output geometry of results as a GeoJSON, KML, SVG or WKT. Only one of these
  67 options can be used at a time. (Default: 0)
  68
  69 * `polygon_threshold=0.0`
  70
  71 Return a simplified version of the output geometry. The parameter is the
  72 tolerance in degrees with which the geometry may differ from the original
  73 geometry. Topology is preserved in the result. (Default: 0.0)
  74
  75 ### Other
  76
  77 * `email=<valid email address>`
  78
  79 If you are making large numbers of request please include an appropriate email
  80 address to identify your requests. See Nominatim's [Usage Policy](https://operations.osmfoundation.org/policies/nominatim/) for more details.
  81
  82 * `debug=[0|1]`
  83
  84 Output assorted developer debug information. Data on internals of Nominatim's
  85 "Search Loop" logic, and SQL queries. The output is (rough) HTML format.
  86 This overrides the specified machine readable format. (Default: 0)
  87
  88
  89 ## Examples
  90
  91 ##### XML
  92
  93 [https://nominatim.openstreetmap.org/lookup?osm_ids=R146656,W104393803,N240109189](https://nominatim.openstreetmap.org/lookup?osm_ids=R146656,W104393803,N240109189)
  94
  95 ```xml
  96   <lookupresults timestamp="Mon, 29 Jun 15 18:01:33 +0000" attribution="Data © OpenStreetMap contributors, ODbL 1.0. https://www.openstreetmap.org/copyright" querystring="R146656,W104393803,N240109189" polygon="false">
  97     <place place_id="127761056" osm_type="relation" osm_id="146656" place_rank="16" lat="53.4791466" lon="-2.2447445" display_name="Manchester, Greater Manchester, North West England, England, United Kingdom" class="boundary" type="administrative" importance="0.704893333438333">
  98       <city>Manchester</city>
  99       <county>Greater Manchester</county>
 100       <state_district>North West England</state_district>
 101       <state>England</state>
 102       <country>United Kingdom</country>
 103       <country_code>gb</country_code>
 104     </place>
 105     <place place_id="77769745" osm_type="way" osm_id="104393803" place_rank="30" lat="52.5162024" lon="13.3777343363579" display_name="Brandenburg Gate, 1, Pariser Platz, Mitte, Berlin, 10117, Germany" class="tourism" type="attraction" importance="0.443472858361592">
 106       <attraction>Brandenburg Gate</attraction>
 107       <house_number>1</house_number>
 108       <pedestrian>Pariser Platz</pedestrian>
 109       <suburb>Mitte</suburb>
 110       <city_district>Mitte</city_district>
 111       <city>Berlin</city>
 112       <state>Berlin</state>
 113       <postcode>10117</postcode>
 114       <country>Germany</country>
 115       <country_code>de</country_code>
 116     </place>
 117     <place place_id="2570600569" osm_type="node" osm_id="240109189" place_rank="15" lat="52.5170365" lon="13.3888599" display_name="Berlin, Germany" class="place" type="city" importance="0.822149797630868">
 118       <city>Berlin</city>
 119       <state>Berlin</state>
 120       <country>Germany</country>
 121       <country_code>de</country_code>
 122     </place>
 123   </lookupresults>
 124 ```
 125
 126 ##### JSON with extratags
 127
 128 [https://nominatim.openstreetmap.org/lookup?osm_ids=W50637691&format=json](https://nominatim.openstreetmap.org/lookup?osm_ids=W50637691&format=json)
 129
 130 ```json
 131 [
 132   {
 133     "place_id": "84271358",
 134     "licence": "Data © OpenStreetMap contributors, ODbL 1.0. https://osm.org/copyright",
 135     "osm_type": "way",
 136     "osm_id": "50637691",
 137     "lat": "52.39955055",
 138     "lon": "13.04806574678",
 139     "display_name": "Brandenburger Tor, Brandenburger Straße, Nördliche Innenstadt, Innenstadt, Potsdam, Brandenburg, 14467, Germany",
 140     "class": "historic",
 141     "type": "city_gate",
 142     "importance": "0.221233780277011",
 143     "address": {
 144       "address29": "Brandenburger Tor",
 145       "pedestrian": "Brandenburger Straße",
 146       "suburb": "Nördliche Innenstadt",
 147       "city": "Potsdam",
 148       "state": "Brandenburg",
 149       "postcode": "14467",
 150       "country": "Germany",
 151       "country_code": "de"
 152     },
 153     "extratags": {
 154       "image": "http://commons.wikimedia.org/wiki/File:Potsdam_brandenburger_tor.jpg",
 155       "wikidata": "Q695045",
 156       "wikipedia": "de:Brandenburger Tor (Potsdam)",
 157       "wheelchair": "yes",
 158       "description": "Kleines Brandenburger Tor in Potsdam"
 159     }
 160   }
 161 ]
 162 ```