Open Search (Nominatim) API

GET
Search

Resource URL

http://open.mapquestapi.com/nominatim/v1/search.php

Resource Information

Response Formats HTML, JSON, XML
Authentication Yes (Requires Key)
Rate Limited Yes

Parameters

The following table displays common parameters that are used when requesting a Nominatim Search. Please refer to the Nominatim Wiki page for a complete list.

Name Description
key The API Key, which is needed to make requests to MapQuest services.
format Specify the output format being called. Must be one of the following, if supplied:
  • html
  • json
  • xml
json_callback A JavaScript function name. The JSON-formatted response will be wrapped in a call to the supplied callback function name to provide JSONP functionality. This functionality might be needed to do cross-site scripting. See the Wikipedia.org entry for JSON for more details.
q

Query string being searched.

Search terms are processed left to right and house numbers, where defined, will be used. Commas are optional but will improve performance by reducing the complexity of the search.

Enclosing the query string in [] causes Nominatim to do a facility search. For example, q=[pub] returns results where type=pub in OpenStreetMap.

addressdetails Include a breakdown of addresses into separate elements.
  • 0 - No, do not display the Address Details.
  • 1 - Yes, display the Address Details.
limit Limits the number of returned results to the integer entered.
countrycodes Limits the search to a specific country or a list of countries. Country codes must be in ISO 3166-1 alpha2.
  • countrycodes=countrycode,countrycode,countrycode...
viewbox Preferred area to find search results.
  • viewbox=left,top,right,bottom
exclude_place_ids Exclude specific features from your search based on OpenStreetMap's Place ID. Exclude multiple features by separating Place IDs with a comma.
  • exclude_place_ids=placeID1,placeID2,placeID3,...
bounded Restrict the search results to a bounding box or bounding route.
  • 0 - No, do not restrict results.
  • 1 - Yes, restrict results.
routewidth Specify the buffer radius of a route. Acceptable values are between 0 and 1 (in degrees).
osm_type Specify if the feature is a Node, Way, or Relation in OpenStreetMap.
  • N - Node
  • W - Way
  • R - Relation
osm_id Specify the OpenStreetMap ID# you wish to reverse geocode.

Example Request

GET

http://open.mapquestapi.com/nominatim/v1/search.php?key=KEY&format=json&q=windsor+[castle]&addressdetails=1&limit=3&viewbox=-1.99%2C52.02%2C0.78%2C50.94&exclude_place_ids=41697

Example Response

[
    {
        "place_id": "55567375",
        "licence": "Data © OpenStreetMap contributors, ODbL 1.0. http://www.openstreetmap.org/copyright",
        "osm_type": "way",
        "osm_id": "23580556",
        "boundingbox": [
            "51.4828405",
            "51.4847466",
            "-0.6083937",
            "-0.5999972"
        ],
        "lat": "51.48382",
        "lon": "-0.604132479198226",
        "display_name": "Windsor Castle, Moat Path, Clewer Within, Slopes Lodge, Eton, Windsor and Maidenhead, South East, England, SL4 1PB, United Kingdom",
        "class": "historic",
        "type": "castle",
        "importance": 0.60105687743994,
        "icon": "http://open.mapquestapi.com/nominatim/v1/images/mapicons/tourist_castle.p.20.png",
        "address": {
            "castle": "Windsor Castle",
            "path": "Moat Path",
            "neighbourhood": "Clewer Within",
            "suburb": "Slopes Lodge",
            "town": "Eton",
            "county": "Windsor and Maidenhead",
            "state_district": "South East",
            "state": "England",
            "postcode": "SL4 1PB",
            "country": "United Kingdom",
            "country_code": "gb"
        }
    }
]
<searchresults timestamp="Thu, 27 Aug 15 17:26:27 +0000" attribution="Data ©OpenStreetMap contributors, ODbL 1.0. http://www.openstreetmap.org/copyright" querystring="windsor [castle]" viewbox="-1.99,52.02,0.78,50.94" polygon="false" exclude_place_ids="41697,55567375" more_url="http://mq-open-search-ext-ls06.ihost.aol.com:8000/nominatim/v1/search?format=xml&exclude_place_ids=41697,55567375&accept-language=en-us&addressdetails=1&viewbox=-1.99%2C52.02%2C0.78%2C50.94&q=windsor+%5Bcastle%5D">
    <place place_id="55567375" osm_type="way" osm_id="23580556" place_rank="30" boundingbox="51.4828405,51.4847466,-0.6083937,-0.5999972" lat="51.48382" lon="-0.604132479198226" display_name="Windsor Castle, Moat Path, Clewer Within, Slopes Lodge, Eton, Windsor and Maidenhead, South East, England, SL4 1PB, United Kingdom" class="historic" type="castle" importance="0.60105687743994" icon="http://mq-open-search-ext-ls06.ihost.aol.com:8000/nominatim/v1/images/mapicons/tourist_castle.p.20.png">
        <castle>Windsor Castle</castle>
        <path>Moat Path</path>
        <neighbourhood>Clewer Within</neighbourhood>
        <suburb>Slopes Lodge</suburb>
        <town>Eton</town>
        <county>Windsor and Maidenhead</county>
        <state_district>South East</state_district>
        <state>England</state>
        <postcode>SL4 1PB</postcode>
        <country>United Kingdom</country>
        <country_code>gb</country_code>
    </place>
</searchresults>