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 ## Endpoint
   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 !!! danger "Deprecation warning"
  19     The API can also be used with the URL
  20     `https://nominatim.openstreetmap.org/lookup.php`. This is now deprecated
  21     and will be removed in future versions.
  22
  23
  24 ## Parameters
  25
  26 This section lists additional optional parameters.
  27
  28 ### Output format
  29
  30 | Parameter | Value | Default |
  31 |-----------| ----- | ------- |
  32 | format    | one of: `xml`, `json`, `jsonv2`, `geojson`, `geocodejson` | `jsonv2` |
  33
  34 See [Place Output Formats](Output.md) for details on each format.
  35
  36
  37 | Parameter | Value | Default |
  38 |-----------| ----- | ------- |
  39 | json_callback | function name | _unset_ |
  40
  41 When given, then JSON output will be wrapped in a callback function with
  42 the given name. See [JSONP](https://en.wikipedia.org/wiki/JSONP) for more
  43 information.
  44
  45 Only has an effect for JSON output formats.
  46
  47
  48 ### Output details
  49
  50 | Parameter | Value | Default |
  51 |-----------| ----- | ------- |
  52 | addressdetails | 0 or 1 | 0 |
  53
  54 When set to 1, include a breakdown of the address into elements.
  55 The exact content of the address breakdown depends on the output format.
  56
  57 !!! tip
  58     If you are interested in a stable classification of address categories
  59     (suburb, city, state, etc), have a look at the `geocodejson` format.
  60     All other formats return classifications according to OSM tagging.
  61     There is a much larger set of categories and they are not always consistent,
  62     which makes them very hard to work with.
  63
  64
  65 | Parameter | Value | Default |
  66 |-----------| ----- | ------- |
  67 | extratags | 0 or 1 | 0 |
  68
  69 When set to 1, the response include any additional information in the result
  70 that is available in the database, e.g. wikipedia link, opening hours.
  71
  72
  73 | Parameter | Value | Default |
  74 |-----------| ----- | ------- |
  75 | namedetails | 0 or 1 | 0 |
  76
  77 When set to 1, include a full list of names for the result. These may include
  78 language variants, older names, references and brand.
  79
  80 | Parameter | Value | Default |
  81 |-----------| ----- | ------- |
  82 | entrances | 0 or 1 | 0 |
  83
  84 When set to 1, include the tagged entrances in the result.
  85
  86
  87 ### Language of results
  88
  89 | Parameter | Value | Default |
  90 |-----------| ----- | ------- |
  91 | accept-language | browser language string | content of "Accept-Language" HTTP header |
  92
  93 Preferred language order for showing search results. This may either be
  94 a simple comma-separated list of language codes or have the same format
  95 as the ["Accept-Language" HTTP header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language).
  96
  97 !!! tip
  98     First-time users of Nominatim tend to be confused that they get different
  99     results when using Nominatim in the browser versus in a command-line tool
 100     like wget or curl. The command-line tools
 101     usually don't send any Accept-Language header, prompting Nominatim
 102     to show results in the local language. Browsers on the contrary always
 103     send the currently chosen browser language.
 104
 105
 106 ### Polygon output
 107
 108 | Parameter | Value  | Default |
 109 |-----------| -----  | ------- |
 110 | polygon_geojson | 0 or 1 | 0 |
 111 | polygon_kml     | 0 or 1 | 0 |
 112 | polygon_svg     | 0 or 1 | 0 |
 113 | polygon_text    | 0 or 1 | 0 |
 114
 115 Add the full geometry of the place to the result output. Output formats
 116 in GeoJSON, KML, SVG or WKT are supported. Only one of these
 117 options can be used at a time.
 118
 119 | Parameter | Value  | Default |
 120 |-----------| -----  | ------- |
 121 | polygon_threshold | floating-point number | 0.0 |
 122
 123 When one of the polygon_* outputs is chosen, return a simplified version
 124 of the output geometry. The parameter describes the
 125 tolerance in degrees with which the geometry may differ from the original
 126 geometry. Topology is preserved in the geometry.
 127
 128
 129 ### Other
 130
 131 | Parameter | Value  | Default |
 132 |-----------| -----  | ------- |
 133 | email     | valid email address | _unset_ |
 134
 135 If you are making large numbers of request please include an appropriate email
 136 address to identify your requests. See Nominatim's
 137 [Usage Policy](https://operations.osmfoundation.org/policies/nominatim/) for more details.
 138
 139
 140 | Parameter | Value  | Default |
 141 |-----------| -----  | ------- |
 142 | debug     | 0 or 1 | 0       |
 143
 144 Output assorted developer debug information. Data on internals of Nominatim's
 145 "search loop" logic, and SQL queries. The output is HTML format.
 146 This overrides the specified machine readable format.
 147
 148
 149 ## Examples
 150
 151 ##### XML
 152
 153 [https://nominatim.openstreetmap.org/lookup?osm_ids=R146656,W104393803,N240109189](https://nominatim.openstreetmap.org/lookup?osm_ids=R146656,W50637691,N240109189)
 154
 155 ```xml
 156   <lookupresults timestamp="Mon, 28 Mar 22 14:38:54 +0000" attribution="Data &#xA9; OpenStreetMap contributors, ODbL 1.0. http://www.openstreetmap.org/copyright" querystring="R146656,W50637691,N240109189" more_url="">
 157     <place place_id="282236157" osm_type="relation" osm_id="146656" place_rank="16" address_rank="16" boundingbox="53.3401044,53.5445923,-2.3199185,-2.1468288" lat="53.44246175" lon="-2.2324547359718547" display_name="Manchester, Greater Manchester, North West England, England, United Kingdom" class="boundary" type="administrative" importance="0.35">
 158       <city>Manchester</city>
 159       <county>Greater Manchester</county>
 160       <state_district>North West England</state_district>
 161       <state>England</state>
 162       <country>United Kingdom</country>
 163       <country_code>gb</country_code>
 164     </place>
 165     <place place_id="115462561" osm_type="way" osm_id="50637691" place_rank="30" address_rank="30" boundingbox="52.3994612,52.3996426,13.0479574,13.0481754" lat="52.399550700000006" lon="13.048066846939687" display_name="Brandenburger Tor, Brandenburger Stra&#xDF;e, Historische Innenstadt, Innenstadt, Potsdam, Brandenburg, 14467, Germany" class="tourism" type="attraction" importance="0.29402874005524">
 166       <tourism>Brandenburger Tor</tourism>
 167       <road>Brandenburger Stra&#xDF;e</road>
 168       <suburb>Historische Innenstadt</suburb>
 169       <city>Potsdam</city>
 170       <state>Brandenburg</state>
 171       <postcode>14467</postcode>
 172       <country>Germany</country>
 173       <country_code>de</country_code>
 174     </place>
 175     <place place_id="567505" osm_type="node" osm_id="240109189" place_rank="15" address_rank="16" boundingbox="52.3586925,52.6786925,13.2396024,13.5596024" lat="52.5186925" lon="13.3996024" display_name="Berlin, 10178, Germany" class="place" type="city" importance="0.78753902824914">
 176       <city>Berlin</city>
 177       <state>Berlin</state>
 178       <postcode>10178</postcode>
 179       <country>Germany</country>
 180       <country_code>de</country_code>
 181     </place>
 182   </lookupresults>
 183 ```
 184
 185 ##### JSON with extratags
 186
 187 [https://nominatim.openstreetmap.org/lookup?osm_ids=W50637691&format=json&extratags=1](https://nominatim.openstreetmap.org/lookup?osm_ids=W50637691&format=json&extratags=1)
 188
 189 ```json
 190 [
 191    {
 192       "place_id": 115462561,
 193       "licence": "Data © OpenStreetMap contributors, ODbL 1.0. https://osm.org/copyright",
 194       "osm_type": "way",
 195       "osm_id": 50637691,
 196       "boundingbox": [
 197         "52.3994612",
 198         "52.3996426",
 199         "13.0479574",
 200         "13.0481754"
 201       ],
 202       "lat": "52.399550700000006",
 203       "lon": "13.048066846939687",
 204       "display_name": "Brandenburger Tor, Brandenburger Straße, Historische Innenstadt, Innenstadt, Potsdam, Brandenburg, 14467, Germany",
 205       "class": "tourism",
 206       "type": "attraction",
 207       "importance": 0.2940287400552381,
 208       "address": {
 209         "tourism": "Brandenburger Tor",
 210         "road": "Brandenburger Straße",
 211         "suburb": "Historische Innenstadt",
 212         "city": "Potsdam",
 213         "state": "Brandenburg",
 214         "postcode": "14467",
 215         "country": "Germany",
 216         "country_code": "de"
 217       },
 218       "extratags": {
 219         "image": "http://commons.wikimedia.org/wiki/File:Potsdam_brandenburger_tor.jpg",
 220         "heritage": "4",
 221         "wikidata": "Q695045",
 222         "architect": "Carl von Gontard;Georg Christian Unger",
 223         "wikipedia": "de:Brandenburger Tor (Potsdam)",
 224         "wheelchair": "yes",
 225         "description": "Kleines Brandenburger Tor in Potsdam",
 226         "heritage:website": "http://www.bldam-brandenburg.de/images/stories/PDF/DML%202012/04-p-internet-13.pdf",
 227         "heritage:operator": "bldam",
 228         "architect:wikidata": "Q68768;Q95223",
 229         "year_of_construction": "1771"
 230       }
 231    }
 232 ]
 233 ```