UNCLASSIFIED

DEVELOPER DOCUMENTATION

The Nominatim search service can be used to search for map features by name or address, and retrieve information about those features.

The search API is available at the following URL:

https://osm-nominatim.gs.mil/search?q=<query>[&<params>]

where <query> is the name to search for, and <params> specifies that parameters of the search. The possible parameters are:

Parameter Description
format=[html|xml|json|jsonv2] Output format. If none specified, then query will be redirected to the Nominatim Web UI (the HTML 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 value specified in the "Accept-Language" HTTP header. Either uses standard RFC 2616 accept-language string or a simple comma separated list of language codes.
q=<query> Query string to search for
countrycodes=<countrycode>[,<countrycode>][,<countrycode>]... Limit search results to a specific country (or a list of countries). <countrycode> should be the ISO 3166-1alpha2 code, e.g. gb for the United Kingdom, de for Germany, etc.
viewbox=<x1>,<y1>,<x2>,<y2> The preferred area to find search results. Any two corner points of the box are accepted in any order as long as they span a real box.
bounded=[0|1] Restrict the results to only items contained with the viewbox (see above). 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.
addressdetails=[0|1] Include a breakdown of the address into elements
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. This can be used to broaden search results. For example, if a previous query only returned a few results, then including those here would cause the search to return other, less accurate, matches (if possible)
limit=<integer> Limit the number of returned results. Default is 10.
dedupe=[0|1] Sometimes you have several objects in OSM identifying the same place or object in reality. The simplest case is a street being split in many different OSM ways due to different characteristics. Nominatim will attempt to detect such duplicates and only return one match; this is controlled by the dedupe parameter which defaults to 1. Since the limit is, for reasons of efficiency, enforced before and not after de-duplicating, it is possible that de-duplicating leaves you with less results than requested.
polygon_geojson=1 Output geometry of results in GeoJSON format.
polygon_kml=1 Output geometry of results in KML format.
polygon_svg=1 Output geometry of results in SVG format.
polygon_text=1 Output geometry of results as Well Known Text (WKT).
extratags=1 Include additional information in the result if available, e.g. Wikipedia link, opening hours.
namedetails=1 Include a list of alternative names in the results. These may include language variants, references, operator and brand.

An example query that finds features with the name "Timbuktu" and returns the results as a JSON document would look like:

https://osm-nominatim.gs.mil/search?q=Timbuktu&format=jsonv2

To perform the same search, but also include the geometry of each result in GeoJSON format, the query would look like:

https://osm-nominatim.gs.mil/search?q=Timbuktu&format=jsonv2&polygon_geojson=1

Multiple searches can be done in one API call using a batch search. The queries are submitted using the "batch" parameter with a JSON array of individual search parameters:

https://osm-nominatim.gs.mil/search?batch=[{"q":"<query 1>"[,<params 1>]},{"q":"<query 2>"[,<params 2>]}]

Each "q" value is a query string, and additional parameters for each query become additional fields. For example, to search for both Istanbul and Constantinople, the request would look like:

https://osm-nominatim.gs.mil/search?batch=[{"q":"Istanbul"},{"q":"Constantinople"}]

To add name details for Constantinople to that same search, add the "namedetails" parameter:

https://osm-nominatim.gs.mil/search?batch=[{"q":"Istanbul"},{"q":"Constantinople","namedetails":"1"}]

The results from a batch query are always returned in JSON, with the following format:

{
   "licence":"<license text>",
   "batch":
   [
      [
         {
            "place_id":nnnnn,"osm_type":"node|way|relation", …
         },
         {
            <result 2 for query 1>
         },
         …
      ],
      [
         {
            <result 1 for query 2>
         },
         {
            <result 2 for query 2>
         },
         …
      ],
      …
   ]
}

The result arrays in the "batch" array are in the same order as the array of queries in the request.

Reverse geocoding generates an address from a latitude and longitude. It does not exactly compute the address for the coordinate it receives. It works by finding the closest suitable OSM object and returning its address information. This may occasionally lead to unexpected results.

The main format of the reverse API is

https://osm-nominatim.gs.mil/reverse?lat=<value>&lon=<value>[&<params>]

where lat and lon are latitude and longitude of a coordinate in WGS84 projection. The API returns exactly one result or an error when the coordinate is in an area with no OSM data coverage.

The possible parameters are:

Parameter Description
format=[html|xml|json|jsonv2|geojson|geocodejson] Output format. If none specified, then query will be redirected to the Nominatim Web UI (the HTML format)
json_callback=<string> Wrap JSON output in a callback function (JSONP) i.e. <string>(<json>)
addressdetails=[0|1] Include a breakdown of the address into elements. (Default: 1)
extratags=[0|1] Include additional information in the result if available, e.g. wikipedia link, opening hours. (Default: 0)
namedetails=[0|1] Include a list of alternative names in the results. These may include language variants, references, operator and brand. (Default: 0)
accept-language=<browser language string> Preferred language order for showing search results, overrides the value specified in the "Accept-Language" HTTP header. Either uses standard RFC 2616 accept-language string or a simple comma separated list of language codes.
polygon_geojson=1 Output geometry of results in GeoJSON format.
polygon_kml=1 Output geometry of results in KML format.
polygon_svg=1 Output geometry of results in SVG format.
polygon_text=1 Output geometry of results as Well Known Text (WKT).
zoom=[0-18] Level of detail required for the address. Default: 18. This is a number that corresponds roughly to the zoom level used in tiles. In terms of address details the zoom levels are as follows:
Zoom Address Detail
3 country
5 state
8 county
10 city
14 suburb
16 major streets
17 major and minor streets
18 building

DIDN'T FIND WHAT YOU WERE LOOKING FOR?

UNCLASSIFIED