Skip to content

Address lookup

The lookup API allows to query the address and other details of one or multiple OSM objects like node, way or relation.

Endpoint

The lookup API has the following format:

  https://nominatim.openstreetmap.org/lookup?osm_ids=[N|W|R]<value>,…,…,&<params>

osm_ids is mandatory and must contain a comma-separated list of OSM ids each prefixed with its type, one of node(N), way(W) or relation(R). Up to 50 ids can be queried at the same time.

Deprecation warning

The API can also be used with the URL https://nominatim.openstreetmap.org/lookup.php. This is now deprecated and will be removed in future versions.

Parameters

This section lists additional optional parameters.

Output format

Parameter Value Default
format one of: xml, json, jsonv2, geojson, geocodejson jsonv2

See Place Output Formats for details on each format.

Parameter Value Default
json_callback function name unset

When given, then JSON output will be wrapped in a callback function with the given name. See JSONP for more information.

Only has an effect for JSON output formats.

Output details

Parameter Value Default
addressdetails 0 or 1 0

When set to 1, include a breakdown of the address into elements. The exact content of the address breakdown depends on the output format.

Tip

If you are interested in a stable classification of address categories (suburb, city, state, etc), have a look at the geocodejson format. All other formats return classifications according to OSM tagging. There is a much larger set of categories and they are not always consistent, which makes them very hard to work with.

Parameter Value Default
extratags 0 or 1 0

When set to 1, the response include any additional information in the result that is available in the database, e.g. wikipedia link, opening hours.

Parameter Value Default
namedetails 0 or 1 0

When set to 1, include a full list of names for the result. These may include language variants, older names, references and brand.

Language of results

Parameter Value Default
accept-language browser language string content of "Accept-Language" HTTP header

Preferred language order for showing search results. This may either be a simple comma-separated list of language codes or have the same format as the "Accept-Language" HTTP header.

Tip

First-time users of Nominatim tend to be confused that they get different results when using Nominatim in the browser versus in a command-line tool like wget or curl. The command-line tools usually don't send any Accept-Language header, prompting Nominatim to show results in the local language. Browsers on the contratry always send the currently chosen browser language.

Polygon output

Parameter Value Default
polygon_geojson 0 or 1 0
polygon_kml 0 or 1 0
polygon_svg 0 or 1 0
polygon_text 0 or 1 0

Add the full geometry of the place to the result output. Output formats in GeoJSON, KML, SVG or WKT are supported. Only one of these options can be used at a time.

Parameter Value Default
polygon_threshold floating-point number 0.0

When one of the polygon_* outputs is chosen, return a simplified version of the output geometry. The parameter describes the tolerance in degrees with which the geometry may differ from the original geometry. Topology is preserved in the geometry.

Other

Parameter Value Default
email valid email address unset

If you are making large numbers of request please include an appropriate email address to identify your requests. See Nominatim's Usage Policy for more details.

Parameter Value Default
debug 0 or 1 0

Output assorted developer debug information. Data on internals of Nominatim's "search loop" logic, and SQL queries. The output is HTML format. This overrides the specified machine readable format.

Examples

XML

https://nominatim.openstreetmap.org/lookup?osm_ids=R146656,W104393803,N240109189

  <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="">
    <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">
      <city>Manchester</city>
      <county>Greater Manchester</county>
      <state_district>North West England</state_district>
      <state>England</state>
      <country>United Kingdom</country>
      <country_code>gb</country_code>
    </place>
    <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">
      <tourism>Brandenburger Tor</tourism>
      <road>Brandenburger Stra&#xDF;e</road>
      <suburb>Historische Innenstadt</suburb>
      <city>Potsdam</city>
      <state>Brandenburg</state>
      <postcode>14467</postcode>
      <country>Germany</country>
      <country_code>de</country_code>
    </place>
    <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">
      <city>Berlin</city>
      <state>Berlin</state>
      <postcode>10178</postcode>
      <country>Germany</country>
      <country_code>de</country_code>
    </place>
  </lookupresults>
JSON with extratags

https://nominatim.openstreetmap.org/lookup?osm_ids=W50637691&format=json&extratags=1

[
   {
      "place_id": 115462561,
      "licence": "Data © OpenStreetMap contributors, ODbL 1.0. https://osm.org/copyright",
      "osm_type": "way",
      "osm_id": 50637691,
      "boundingbox": [
        "52.3994612",
        "52.3996426",
        "13.0479574",
        "13.0481754"
      ],
      "lat": "52.399550700000006",
      "lon": "13.048066846939687",
      "display_name": "Brandenburger Tor, Brandenburger Straße, Historische Innenstadt, Innenstadt, Potsdam, Brandenburg, 14467, Germany",
      "class": "tourism",
      "type": "attraction",
      "importance": 0.2940287400552381,
      "address": {
        "tourism": "Brandenburger Tor",
        "road": "Brandenburger Straße",
        "suburb": "Historische Innenstadt",
        "city": "Potsdam",
        "state": "Brandenburg",
        "postcode": "14467",
        "country": "Germany",
        "country_code": "de"
      },
      "extratags": {
        "image": "http://commons.wikimedia.org/wiki/File:Potsdam_brandenburger_tor.jpg",
        "heritage": "4",
        "wikidata": "Q695045",
        "architect": "Carl von Gontard;Georg Christian Unger",
        "wikipedia": "de:Brandenburger Tor (Potsdam)",
        "wheelchair": "yes",
        "description": "Kleines Brandenburger Tor in Potsdam",
        "heritage:website": "http://www.bldam-brandenburg.de/images/stories/PDF/DML%202012/04-p-internet-13.pdf",
        "heritage:operator": "bldam",
        "architect:wikidata": "Q68768;Q95223",
        "year_of_construction": "1771"
      }
   }
]