Nominatim Search Service Developer's Guide

The Nominatim Search Service is similar to our MapQuest Search Service with its simple interface and powerful capabilities, but instead relies solely on data contributed to OpenStreetMap. To view it in action, visit any of our Open Beta domains (http://open.mapquest.*)

If you have questions or comments while going through this guide, please don't hesitate to post on our Open Forums! Also, visit the Nominatim Wiki page for a complete list of acceptable parameters.

Hello, World!

The following example demonstrates a simple search request for "Westminster Abbey" using Nominatim. Only three parameters are being requested:

  • format - Output format being called. [html/json/xml]
  • json_callback - Callback function used to display the results below.
  • q - Query string being searched.

The JavaScript code which sends the request and displays the result can be viewed here.

(Search will be displayed below)     


Contents


Overview

Developed by Brian Quinion, Nominatim is a tool used to search through OpenStreetMap data by name and address, and vice versa (reverse geocoding).

Content Searched

Nominatim indexes both named and numbered features in OpenStreetMap and several other unnamed features, such as pubs, hotels and churches. When searching, certain keywords are translated into searches for specific OSM tags. For example, entering the word "pub" results in Nominatim searching for features that are tagged as amenity=pub.

Refer to the Nominatim Wiki page for a full list of the special phrases that result in Nominatim searching for a specific key=value pair.

Indexing and Version

The Nominatim Search Service is updated approximately every 20 minutes. Data is constantly being indexed but if you believe you're experiencing a delay, it's possible there was a particularly large import of data recently into OpenStreetMap.

Currently, we're using Nominatim Version 1 with plans on switching to Version 2 soon. The switch will mostly result in the change of the internal database structure rather than a change in the external API. However, Version 2 should see a significant improvement in the quality of the responses so stay tuned for more information.


Search Options and 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
format Specify the output format being called. Must be one of the following, if supplied:
  • html
  • json
  • xml
json_callback Callback function used to display the results below.
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.

Basic Sample Search

In the following example, we'll be taking a look at the parameters listed above. Limit your results, add address details, set a pre-defined search area, exclude features, do a local search, and more.

The JavaScript code which sends the request and displays the result can be viewed here.

Options Value(s)
Query:
Address Details:
Limit:
Viewbox (left, top, right, bottom):
Exclude:

(Search will be displayed below)     


Search along a Route

Searching along a route is an advanced search that allows you to take advantage of the powerful capabilities of MapQuest's Open Directions Service. The routewidth, as explained above, acts as a route buffer and does a query within the specified distance along the route.

The JavaScript code which sends the request and displays the result can be viewed here.

Options Value(s)
From:
To:
Query:
Route Width:

(Search will be displayed below)     


Reverse Geocoding

The following examples use Nominatim to reverse geocode. This is the process where you begin with a geographic coordinate and the nearest known address is returned. With Nominatim, you have the option of reverse geocoding with coordinates or with the OpenStreetMap ID.

When reverse geocoding by OSM Type/ID, please make sure you specify the correct osm_type - Node, Way, Relation (N, W, R).

The JavaScript code which sends the request and displays the result can be viewed here.


By OSM Type/ID

Options Value(s)
OSM Type:
OSM ID:

(Search will be displayed below)     


By Latitude/Longitude

Options Value(s)
Latitude:
Longitude:

(Search will be displayed below)     


OpenStreetMap data is licensed under the Open Data Commons Open Database License (ODbL).

  © MapQuest, Inc. All rights reserved.    Privacy Policy | Terms of Use