The Overpass API has been developed to perform read-only queries to the Openstreetmap database, using a powerful and flexible language known as Overpass QL. This post illustrates the syntax of this language with sample queries.
OpenStreetMap (OSM) is a huge geographical information database, constantly updated by a large community of contributors all over the world.
OSM offers a main API designed for editing the content of this database. But some applications that use the OSM DB are not focused on editing data, but rather in displaying the content of the database. To accomplish this purpose, the often must perform queries using different selection criteria, sometimes returning large datasets. Several read-only interfaces have been developed to meet this requierement in an efficient way:
Initially, a read-only XAPI (eXtended API) was developed, based on the OSM main API, to implement enhanced search capabilities.
Later, Overpass API, using a more powerful query language, was developed. To ease the migration of existing software utilities that used XAPI, a XAPI compatibility layer has been added to Overpass API.
There are currrently three well-known servers that give public access to OSM through the Overpass API:
How to query the OSM DB with Overpass
Queries to OSM are issued by means of HTTP GET or POST requests to the URL that provides the service, with a “data” argument whose value is the query string, written in Overpass QL language:
There are several command-line utilities, such as
curl, that can be used to retrieve the content of a URL, and are also suited to perform queries to the OSM DB with Overpass.
For instance, data for the node with the numerical ID 1422314245 can be requested using wget as:
$ wget 'http://overpass-api.de/api/interpreter?data=node(1422314245);out;'
With the command above, the result is retrieved in XML format:
<?xml version="1.0" encoding="UTF-8"?> <osm version="0.6" generator="Overpass API"> <note>The data included in this document is from www.openstreetmap.org. The data is made availa ble under ODbL.</note> <meta osm_base="2014-08-01T07:07:02Z"/> <node id="1422314245" lat="51.8979282" lon="-8.4705806"> <tag k="is_in" v="County Cork"/> <tag k="is_in:continent" v="Europe"/> <tag k="name" v="Cork"/> <tag k="name:ar" v="كورك"/> <tag k="name:cy" v="Corc"/> <tag k="name:en" v="Cork"/> <tag k="name:ga" v="Corcaigh"/> <tag k="name:ru" v="Корк"/> <tag k="name:sr" v="Корк"/> <tag k="note" v="Experimental import of Irish places and POIs from GNS Dataset"/> <tag k="place" v="city"/> <tag k="place_county" v="Cork"/> <tag k="population" v="127000"/> <tag k="ref:LOCODE" v="IEORK"/> <tag k="source" v="gns_ei"/> <tag k="wikipedia:en" v="Cork_(city)"/> </node> </osm>
Note: As can be seen, the urls passed to wget must be enclosed in quotes, because the query string often includes special characters such as parentheses, square brackets, etc., that otherwise would be intepreted by the shell.
Issuing queries from a program or script
There are libraries for most programming languages that implement the ability to retrieve the content of a given URL. Those libraries ca be used to perform queries to the OSM database from a program or script, in the Overpass API query language.
The only caveat is making sure that the search string is HTML-encoded, because it often includes special characters not valid in a URL.
For instance, an Overpass query can be done from a PHP script with the sentences:
$node_id = 1422314245; $query= "node($node_id);out;"; $node_xml = file_get_contents("http://overpass-api.de/api/interpreter?data=" . urlencode($query)); echo $node_xml;
In this sample, the urlencode() built-in function is used to encode the query
A query in Overpass_QL language is a sequence of sentences, each sentence ending in a semicolon “;”. The syntax of sentences remembers that of the “C” language.
A query normally starts with a sentence “node”, “way” or “relation” that requests a set of nodes, ways or relations, filtered through some search criteria.
Query the set of nodes, ways or relations inside a bounding box
One of the most common filters is a bounding box, as in the following example:
The coordinates of the bounding box are in the sequence (south latitude, south longitude, north latitude, north longitude).
As shown in the example, the query must end with a “out” sentence that delivers the result.
The same kind of sentence can be used to retrieve all ways inside a bounding box:
And also to retrieve all relations in a bounding box:
The union operator can also be used to query for the set of nodes, ways and relations in a bounding box:
( node(50.745,7.17,50.75,7.18); way(50.745,7.17,50.75,7.18); relation(50.745,7.17,50.75,7.18); ); out;
Query nodes, ways or relations by their unique id
If the numerical id of the desired node, way or relation, the details can be requested with a query:
Query by name and other attributes
The criteria that must be met by tags assigned to nodes,ways and relations for a given search can be specified inside square brackets. For instance:
node ["highway"="bus_stop"] ["shelter"] ["shelter"!="no"] (50.7,7.1,50.8,7.25); out;
In this example, the query requests all nodes inside a bounding box, whose tags meet the criteria:
- The value of tag “highway” is “bus_stop”
- The “shelter” tag exists
- The value of tag tag “shelter” is not set to “no”
Regular expressions can also be used. For instance, to request all ways inside a bounding box that do no have a “highway” tag:
way ["highway"!~"."] (50.74,7.17,50.75,7.18); out;
Retrieve all the dependencies
When a search for a way is performed, the information retrieved includes the name and values of all tags associated to the way, as well as the unique identifiers of the nodes belonging to the way. For instance:
way ["name"="Gielgenstraße"] (50.7,7.1,50.8,7.25); out;
But, if we need to retrieve also the coordinates of the nodes, a search by the node id would need to be performed for each node. This set of searches can be replaced with a single recursive query, using the special sentence “>”.
( way ["name"="Gielgenstraße"] (50.7,7.1,50.8,7.25); >; ); out;
A recursive search can also be done for relations. In this case, the information related to each of the relation members (including nodes, ways and relations) will be obtained, together with the information related to the relation being searched.
Retrieving all parent elements (reverse recursion)
It is also possible to search recursively backwards, with the “<” sentence. Adding this sentence, the results of the search will include the complete information of ways and relations that reference the elements matched in the main search.
( way ["name"="Gielgenstraße"] (50.7,7.1,50.8,7.25); <; ); out;
Finally, it is also possible to combine the “<” and “>” sentences, to retrieve the complete information of all ways and relations in the search results:
( way ["name"="Gielgenstraße"] (50.7,7.1,50.8,7.25); <; >; ); out;
Retrieving the result in JSON and other formats
By default, the result is delivered in XML format.
To request the result in JSON format, a format specifier sentence can be added:
Besides “xml” and “json”, the “custom” and “popup” formats can also be requested. The meaning of these formats and the configuration guidelines that apply for them can be consulted at “Overpass API – Output Formats”
- OSM main API
- Overpass API
- Overpass QL language guide
- Overpass QL anguage reference
- Output formats
- Command line