UNCLASSIFIED

GEOINT Services Open Street Map (OSM) Service

GEOINT Services provides three Open Street Map (OSM) related Application Programming Interface (API) services: a tile retrieval service, a feature query service (Overpass), and a search / geocoder service (Nominatim).

The geospatial data behind all of the services are kept up-to-date with upstream replication updates within 20-30 minutes of real time.

Video

Video tutorials

Training

The API usage is documented on the OpenStreetMap wiki. Both Leaflet and OpenLayers have built-in support for the tile service API, so their documentation might be a good supplement to the information on the OSM wiki.

http://wiki.openstreetmap.org/wiki/Using_OpenStreetMap

http://wiki.openstreetmap.org/wiki/Overpass_API

https://wiki.openstreetmap.org/wiki/Nominatim

Tile Service

The tile service supports map tile access via the OSM X/Y/Z API format and the Open Geospatial Consortium (OGC) Web Map Tile Service (WMTS) API format.

The X/Y/Zoom API is available at following URLs:

URL Style Projection Zoom Levels
https://osm.gs.mil/tiles/default/<zoom>/<x>/<y>.png default Web Mercator (EPSG:3857) 0 - 20
https://osm.gs.mil/tiles/bright/<zoom>/<x>/<y>.png bright Web Mercator (EPSG:3857) 0 - 20
https://osm.gs.mil/tiles/humanitarian/<zoom>/<x>/<y>.png humanitarian Web Mercator (EPSG:3857) 0 - 20
https://osm.gs.mil/tiles/default_pc/<zoom>/<x>/<y>.png default Plate Carrée (EPSG:4326) 0 - 20
https://osm.gs.mil/tiles/bright_pc/<zoom>/<x>/<y>.png bright Plate Carrée (EPSG:4326) 0 - 20
https://osm.gs.mil/tiles/humanitarian_pc/<zoom>/<x>/<y>.png humanitarian Plate Carrée (EPSG:4326) 0 - 20

The WMTS service can be configured using the following URL:

https://osm.gs.mil/wmts/1.0.0/WMTSCapabilities.xml - RESTful WMTS

or

https://osm.gs.mil/ows?SERVICE=WMTS&REQUEST=GetCapabilities - Key-Value Pair (KVP) WMTS

Parallel access to tiles from browser applications can be done using numbered versions of these URLs (osm-1 through osm-4).

For example, Leaflet can be configured as follows:

L.tileLayer('https://osm-{s}.gs.mil/tiles/default/{z}/{x}/{y}.png', { subdomains: '1234', … });

OpenLayers and OpenSphere can be configured as follows:

new TileLayer({source: new OSM({url: 'https://osm-{1-4}.gs.mil/tiles/default/{z}/{x}/{y}.png', … })});

Feature Query Service (Overpass)

The feature query service is an implementation of the OSM Overpass API, available on the following URL:

https://osm-overpass.gs.mil/overpass

For example, an Overpass interpreter query would be posted to:

https://osm-overpass.gs.mil/overpass/interpreter

Additional Overpass API documentation can be found at:

Search / Geocoder Service (Nominatim)

The Nominatim search service can be used to search for map features by name. The search API is available at the following URL:

https://osm-nominatim.gs.mil/search.php?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
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

Sample Applications for Developers

There are sample / reference web applications for each service available at the following URLs:

URL Application
https://osm.gs.mil/slippymap.html Sample Leaflet map
https://overpass-turbo.gs.mil Overpass API demonstration application
https://osm-nominatim.gs.mil Nominatim web interface