Nominatim
Nominatim (from the Latin, 'by name') is a tool to search OSM data by name and address and to generate synthetic addresses of OSM points (reverse geocoding). It can be found at http://nominatim.openstreetmap.org . Nominatim is also used as one of the sources for the Search box on the OpenStreetMap home page and powers the search on the MapQuest Open Initiative websites.
This page provides usage instructions. For details of how Nominatim works please see the Development Overview and there is a short FAQ. There is also a list of language mappings per country and some experimental address formats per country.
If you find problems with the search results please help by providing a test case or submitting a bug through trac. See also the notes for Version 2.
Contents |
Search
Nominatim indexes named (or numbered) features with the OSM data set and a subset of other unnamed features (pubs, hotels, churches, etc)
Search terms are processed left to right.
This Search will work: pilkington avenue, birmingham
This search will fail: birmingham, pilkington avenue
(Commas are optional, but improve performance by reducing the complexity of the search.)
Where house numbers have been defined for an area they should be used: 135 pilkington avenue, birmingham
Special Keywords
Various keywords are translated into searches for specific osm tags (i.e. Pub => amenity=pub). A current list of special phrases processed is available.
Parameters
http://nominatim.openstreetmap.org/search?<params> http://nominatim.openstreetmap.org/search/<query>?<params>
format=[html|xml|json] Output format
json_callback=<string> Wrap json output in a callback function (JSONP) i.e. <string>(<json>)
accept-language=<browser language string> Preferred language order for showing search results, overrides the browser value. Either uses standard rfc2616 accept-language string or a simple comma separated list of language codes.
q=<query> Query string to search for. Alternatively can be entered as:
street=<housenumber> <streetname> city=<city> county=<county> state=<state> country=<country> postalcode=<postalcode> (experimental) Alternative query string format for structured requests. Structured requests are faster and require less server resources. DO NOT COMBINE WITH q=<query> PARAMETER.
countrycodes=<countrycode>[,<countrycode>][,<countrycode>]... Limit search results to a specific country (or a list of countries). <countrycode> should be the ISO 3166-1 alpha2 code, e.g. gb for the uk, de for germany, etc.
viewbox=<left>,<top>,<right>,<bottom> or viewboxlbrt=<left>,<bottom>,<right>,<top> The preferred area to find search results
bounded=[0|1] Restrict the results to only items contained with the bounding box. Restricting the results to the bounding box also enables searching by amenity only, for example a search query of just "[pub]" would normally be rejected but with bounded=1 will result in a list of items matching within the bounding box.
polygon=[0|1] Output polygon outlines for items found
addressdetails=[0|1] Include a breakdown of the address into elements
email=<valid email address> If you are making large numbers of request please include a valid email address or alternatively include your email address as part of the User-Agent string. This information will be kept confidential and only used to contact you in the event of a problem, see Usage Policy for more details.
exclude_place_ids=<place_id,[place_id],[place_id]> If you do not want certain openstreetmap objects to appear in the search result, give a comma separated list of the place_id's you want to skip.
limit=<integer> Limit the number of returned results.
dedupe=[0|1] No explanation yet.
debug=[0|1] No explanation yet.
polygon_geojson=1 (experimental) Output geometry of results in geojson format.
polygon_kml=1 (experimental) Output geometry of results in kml format.
polygon_svg=1 (experimental) Output geometry of results in svg format.
polygon_text=1 (experimental) Output geometry of results as a WKT.
Examples
http://nominatim.openstreetmap.org/search?q=135+pilkington+avenue,+birmingham&format=xml&polygon=1&addressdetails=1 http://nominatim.openstreetmap.org/search/135%20pilkington%20avenue,%20birmingham?format=xml&polygon=1&addressdetails=1 http://nominatim.openstreetmap.org/search/gb/birmingham/pilkington%20avenue/135?format=xml&polygon=1&addressdetails=1
<searchresults timestamp="Sat, 07 Nov 09 14:42:10 +0000" querystring="135 pilkington, avenue birmingham" polygon="true">
<place
place_id="1620612" osm_type="node" osm_id="452010817"
boundingbox="52.548641204834,52.5488433837891,-1.81612110137939,-1.81592094898224"
polygonpoints="[['-1.81592098644987','52.5487429714954'],['-1.81592290792183','52.5487234624632'],...]"
lat="52.5487429714954" lon="-1.81602098644987"
display_name="135, Pilkington Avenue, Wylde Green, City of Birmingham, West Midlands (county), B72, United Kingdom"
class="place" type="house">
<house>135</house>
<road>Pilkington Avenue</road>
<village>Wylde Green</village>
<town>Sutton Coldfield</town>
<city>City of Birmingham</city>
<county>West Midlands (county)</county>
<postcode>B72</postcode>
<country>United Kingdom</country>
<country_code>gb</country_code>
</place>
</searchresults>
Reverse Geocoding / Address lookup
Reverse geocoding generates an address from a latitude and longitude. The optional zoom parameter specifies the level of detail required in terms of something suitable for an openlayers zoom level.
Parameters
http://nominatim.openstreetmap.org/reverse?<query>
format=[xml|json] Output format
json_callback=<string> Wrap json output in a callback function (JSONP) i.e. <string>(<json>)
accept-language=<browser language string> Preferred language order for showing search results, overrides the browser value. Either uses standard rfc2616 accept-language string or a simple comma separated list of language codes.
osm_type=[N|W|R] osm_id=<value> A specific osm node / way / relation to return an address for Please use this in preference to lat/lon where possible
lat=<value> lon=<value> The location to generate an address for
zoom=[0-18] Level of detail required where 0 is country and 18 is house/building
addressdetails=[0|1] Include a breakdown of the address into elements
email=<valid email address> If you are making large numbers of request please include a valid email address or alternatively include your email address as part of the User-Agent string. This information will be kept confidential and only used to contact you in the event of a problem, see Usage Policy for more details.
Example
http://nominatim.openstreetmap.org/reverse?format=xml&lat=52.5487429714954&lon=-1.81602098644987&zoom=18&addressdetails=1
<reversegeocode timestamp="Fri, 06 Nov 09 16:33:54 +0000" querystring="...">
<result place_id="1620612" osm_type="node" osm_id="452010817">
135, Pilkington Avenue, Wylde Green, City of Birmingham, West Midlands (county), B72, United Kingdom
</result>
<addressparts>
<house>135</house>
<road>Pilkington Avenue</road>
<village>Wylde Green</village>
<town>Sutton Coldfield</town>
<city>City of Birmingham</city>
<county>West Midlands (county)</county>
<postcode>B72</postcode>
<country>United Kingdom</country>
<country_code>gb</country_code>
</addressparts>
</reversegeocode>
Details / Gazetteer
Currently the details page (details.php) creates a high load on the server and is only intended as a debugging aide, as a result no xml api is currently provided. Scraping or heavy use is likely to result in an IP ban.
Usage Policy
For the usage policy of nominatim.openstreetmap.org, please see Nominatim usage policy.
MapQuest also provide an version of this API, without the usage limits. For details please see [1]
Source Code
Nominatim is based around the postgresql import utility osm2pgsql using the alternative gazetteer output option. The source for osm2pgsql can be obtained here:
http://svn.openstreetmap.org/applications/utils/export/osm2pgsql
Indexing and search are performed using a combination of C, plpgsql and php. The source for this can be found here:
http://github.com/twain47/Nominatim
Full installation instructions can be found in Nominatim/Installation.
Bugs / Error reporting
The Nominatim is maintained by Twain, please report bugs using the Nominatim component in Trac.
