- 1 Introduction
- 2 Community: where can I get help?
- 3 Developers / System Administrators
- 4 Limitations
- 5 The map query
- 6 Simple usage examples
- 7 Advanced usage examples
- 8 Building blocks
- 9 Meta data
- 10 Public transport example
- 11 XAPI Compatibility Layer
- 12 Programs/Scripts around Overpass
- 13 Talks, Presentations, Workshops
- 14 Books
The Overpass API (formerly known as OSM Server Side Scripting, or OSM3S) is a read-only API that serves up custom selected parts of the OSM map data. It acts as a database over the web: the client sends a query to the API and gets back the data set that corresponds to the query.
Unlike the main API, which is optimized for editing, Overpass API is optimized for data consumers that need a few elements within a glimpse or up to roughly 100 million elements in some minutes, both selected by search criteria like e.g. location, type of objects, tag properties, proximity, or combinations of them. It acts as a database backend for various services.
Overpass API has a powerful query language with a lot more features than the former XAPI based tools. For details, see the introductory level language guide or the comprehensive Overpass QL guide/language reference. It is highly recommended to get familiar with various features via overpass turbo, an interactive Web based frontend. For legacy applications there's also a compatibility layer to allow a smooth transition from XAPI.
To support small and well scaling OSM main services, Overpass API is run as a third party service. You can use the public visible instances:
|Name||Data coverage||Endpoint||Version||Attic data||Hardware||Usage policy|
|Main Overpass API instance||Global||http://overpass-api.de/api/||0.7.52||Yes||4 physical cores, 32 GB RAM, SSD||Both servers have a total capacity of about 1.000.000 requests per day. You can safely assume that you don't disturb other users when you do less than 10.000 queries per day or download less than 5 GB data per day.|
|Rambler Overpass API instance||Global||http://overpass.osm.rambler.ru/cgi/||0.7.52||Yes||8 cores, 64 GB RAM, hard disks|
|Overpass API on openstreetmap.fr||Global||http://api.openstreetmap.fr/oapi/interpreter/||0.7.4||No||?||?|
|Swiss Overpass API instance||Switzerland only||http://overpass.osm.ch/api/||0.7.51||No||12 cores, 64 GB RAM, hard disks||?|
Queries to the Overpass API are in XML or Overpass QL form. See the semantics explained below.
You can use the Overpass turbo frontend to create and display queries for the above mentioned Overpass API instances.
Overpass API also provides permanent links.
Community: where can I get help?
There are several community sites providing help for Overpass API and overpass turbo related questions. It is the recommended channel for introductory to expert level questions or more generally, if your question is interesting to a wider audience.
|Site||Language||Frequently used 'tags' for questions|
|Help OSM||English||overpass, overpass-turbo|
Developers / System Administrators
There is a mailing list for developers
Every service has its limitations, and so does Overpass API:
- Downloading big data:
As the size of an Overpass API query result is only known when the download is complete. It is impossible to give an ETA while downloading. And the dynamically generated files from Overpass API typically take longer to generate and download than downloading existing static extracts of the same region. As a result, when you want to extract country-sized regions with all (or nearly all) data in it, it's better to use planet.osm mirrors for that. Overpass API is most useful when the amount of data needed is only a selection of the data available in the region.
- Querying of OSM data history:
Overpass API doesn't offer changeset-based criteria. It's possible to work around that, by using time-based diffs, but this may be clumsy. Overpass API also can't give you full history of an object, but time-based selection criteria can give you the state of an object at a certain time.
The map query
Before we get to a detailed syntax explanation, we present the probably most common use case, the map query, to collect all data from a given bounding box:
The order of values in the bounding box (51.249,7.148,51.251,7.152) is minimum latitude, minimum longitude, maximum latitude, maximum longitude (or South-West-North-East). See more details about bbox below.
Simple usage examples
This section has moved to the query language guide.
Advanced usage examples
The following examples introduce the remaining commands recurse and around. They only make sense in combination with other commands.
Again, all of the following examples can be tested by copying the snippets to http://www.overpass-api.de/query_form.html.
Note: Queries may take several minutes to be completed. If you receive timeouts, you can extend the timeout period.
With recurse, you query for membership relations. It is available for ways to get all referred nodes, for relations to get all member nodes or member ways. Or the other way round, to get for a node, way or relation the ways or relations the element is member of. You select among the type of element by the type attribute.
Example: Get the nodes of all relations that have the key ref with value CE 61. In fact, get all bus stops served by CE 61.
<query type="relation"> <has-kv k="ref" v="CE 61"/> </query> <recurse type="relation-node"/> <print/>
Get the ways of all relations that have the key ref with value CE 61. In fact, that is the itinerary served by CE 61.
<query type="relation"> <has-kv k="ref" v="CE 61"/> </query> <recurse type="relation-way"/> <print/>
Get the nodes of the above mentioned ways. You don't get the bus stops, but that is intentionally - see below at the union examples.
<query type="relation"> <has-kv k="ref" v="CE 61"/> </query> <recurse type="relation-way"/> <recurse type="way-node"/> <print/>
Get all relations that have the nodes named Lichtscheid as members. These are the bus lines stopping there.
<query type="node"> <has-kv k="name" v="Lichtscheid"/> </query> <recurse type="node-relation"/> <print/>
Get all the ways that have a node member within the given bounding box.
<bbox-query s="51.249" n="51.251" w="7.149" e="7.151"/> <recurse type="node-way"/> <print/>
And we can also get relation members of relations:
<query type="relation"> <has-kv k="name" v="VRR Buslinien"/> </query> <recurse type="relation-relation"/> <print/>
Or the same thing backwards:
<query type="relation"> <has-kv k="ref" v="CE 65"/> </query> <recurse type="relation-backwards"/> <print/>
around allows you to get all nodes near one or more given nodes. For example, to get all nodes that are at most 10 meters around the nodes called Bristol:
<query type="node"> <has-kv k="name" v="Bristol"/> </query> <around radius="10"/> <print/>
You can also chain queries to get only nodes satisfying a second criterion that are located near nodes matching the first criterion. Here, we will search for all bus stops within 100 meters of pubs named "Bristol":
<query type="node"> <has-kv k="amenity" v="pub"/> <has-kv k="name" v="Bristol"/> </query> <query type="node"> <around radius="100"/> <has-kv k="highway" v="bus_stop"/> </query> <print/>
We still have some helper statements to explain, in particular union, item, the variable mechanism, osm-script, and foreach.
Again, all of the following examples can be tested by copying the snippets to http://www.overpass-api.de/query_form.html.
Union allows you to group the results of several queries. For example, you can get all nodes that have name Lichtscheid or Müngstener Straße.
<union> <query type="node"> <has-kv k="name" v="Lichtscheid"/> </query> <query type="node"> <has-kv k="name" v="Müngstener Straße"/> </query> </union> <print/>
Another usage would be to get a relation with all of its members, including the nodes of member ways.
<union> <query type="relation"> <has-kv k="ref" v="CE 61"/> </query> <recurse type="relation-node" into="nodes"/> <recurse type="relation-way"/> <recurse type="way-node"/> </union> <print/>
This needs some explanation:
- query collects the relations with ref CE 61. It writes the result to the default variable _. And the embracing union collects the data.
- recurse relation-node collects the nodes that are members of the above found relations. The result is placed in the variable nodes (we don't need it there anymore, just to keep relations in the default variable). And it is collected by the embracing union.
- recurse relation-way sees again the relations from the default variable and returns the ways that are members of the default variable's relations. Again, the embracing union collects the results.
- recurse way-node finally returns the nodes that are members of the ways just collected. This is the last piece of data that goes into the union's result.
If you think this is complicated, you are right. I'm open to suggestions how to improve the statement semantics, but I haven't found anything systematic yet.
Now we are ready to assemble the map call, by combining a bbox-query with several recurse statements and embracing the whole thing with an union.
Part of the idea behind item and variables you have already seen in the preceding example: every statement fetches its input from a variable and puts its output into a variable. If you omit the variable name, it defaults to _. This makes in possible to remove almost all explicit specifications of variables. The input is always fetched from the variable named by the attribute from, the output is always put into the variable specified with into.
<query type="way" into="foo"> <has-kv k="name" v="Am Hofe"/> </query> <print from="foo"/>
E.g., this does the same as the respective example at print, but it uses the explicitly stated variable foo.
To make this concept fully versatile, item allows you to specify a set as input in union and query:
<query type="relation"> <has-kv k="network" v="VRR"/> <has-kv k="ref" v="645"/> </query> <recurse type="relation-node" into="stops"/> <query type="node"> <around from="stops" radius="100"/> <has-kv k="highway" v="bus_stop"/> </query> <union> <item/> <recurse type="node-relation"/> <query type="node"> <around from="stops" radius="100"/> <has-kv k="park_ride"/> </query> </union> <print/>
Here, in the middle, the item ensures that the beforehand collected data for bus_stop is included in the results of union. This also shows how the variable stops is necessary to make the query possible.
<bbox-query s="51.15" n="51.35" w="7.0" e="7.3"/> <recurse type="node-way"/> <query type="way"> <item/> <has-kv k="highway" v="motorway"/> </query> <print/>
The item in query restricts the possibly found items to those already found in the step before, with recurse. Thus, we have a complete query to find ways with arbitrary tags within a bbox.
The osm-script is silently added if you don't specify it explicitly. The reason to specify one explicitly is to tweak the resource management:
<osm-script timeout="900" element-limit="1073741824"> <bbox-query s="51.15" n="51.35" w="7.0" e="7.3"/> <print/> </osm-script>
This extends the timeout from 3 minutes to 15 minutes (written as 900 seconds). Additionally, the soft quota for memory usage is set to 1 GiB (equals 1073741824 byte).
<query type="relation"> <has-kv k="type" v="multipolygon"/> <has-kv k="name"/> </query> <foreach into="pivot"> <union> <recurse type="relation-way" from="pivot"/> <recurse type="way-node"/> </union> <make-area pivot="pivot"/> </foreach>
This is the essential part of the rule that creates the areas. We do not explain the make-area here. The first part with query collects all relations with certain properties. In the second part, we want to do something with each element in the result of query. This does foreach. The body of the loop is executed once for every element in the input set, containing exactly this single element in the output set, here named as pivot.
Beside the special mode of print, there are two statements dedicated to query for specific meta data, user and newer.
You can select all data that has been touched the last time by a particular user. Choose the user name (for example, mine):
<user name="Roland Olbricht"/> <print mode="meta"/>
Or choose a user id:
<user uid="65282"/> <print mode="meta"/>
This statement can also be used within a query statement. It then restricts the result to data that has been last touched by the provided user:
<query type="node"> <user name="Roland Olbricht"/> <has-kv k="highway" v="bus_stop"/> <bbox-query s="51.2" n="51.35" w="7.05" e="7.3"/> </query> <print mode="meta"/>
Newer can be used within query statement (and not as a standalone statement). It restricts the output to elements that are newer than the given date. The date must be in the format YYYY-MM-DDTHH:MM:SSZ. It refers, as the results, always to the timezone UTC.
<query type="node"> <newer than="2011-08-01T00:00:00Z"/> <has-kv k="highway" v="bus_stop"/> <bbox-query s="51.2" n="51.35" w="7.05" e="7.3"/> </query> <print mode="meta"/>
If you want to get all nodes newer than a certain date from a bbox, you can use query with an item substatement.
<bbox-query s="51.2" n="51.35" w="7.05" e="7.3"/> <query type="node"> <item/> <newer than="2011-08-01T00:00:00Z"/> </query> <print mode="meta"/>
Public transport example
An interesting example of how the Overpass API can be integrated into an application - a service to generate line diagrams for public transport.
- Example one here
- Example two here
(Please be patient - each request can take up to 10 seconds to generate, depending on server load.)
Note: PTv2 or any newer versions or variations thereof are currently not supported.
XAPI Compatibility Layer
For details and examples see:
Programs/Scripts around Overpass
- There is a simple Python wrapper written by Martijn van Exel (talk).
- There is an advanced Python wrapper called OverPy
- query-overpass is a simple API wrapper and CLI for Overpass.
- To GPX output osm2node source code and Online service
- API 0.6 wrapper source code and Online service
- osmtogeojson converts OSM data to GeoJSON and has full support for Overpass API's extended geometry output modes.
- gimmeOSM lets you enter a feature ID and returns it as GeoJSON.
Talks, Presentations, Workshops
This section lists previous presentation, talks, workshops on Overpass API and related topics. Many presentations are a good start even for beginners with lots of examples.
|July 2015||AGIT 2015||Salzburg (AT)||Overpass API: OpenStreetMap-Daten vorgefiltert beziehen||Presentation||Roland Olbricht||German||?|
|June 2015||SotM US 2015||NYC (US)||Working with OSM diffs / The Overpass API||Workshop||Roland Olbricht||English||?, Abstract|
|April 2015||geo-spatial.org||Cluj (RO)||Overpass API: utilizarea datelor OpenStreetMap pentru a realiza hărți tematice||Workshop||Alex Morega||Romanian||Workshop materials|
|March 2015||FOSSGIS 2015||Münster (DE)||Schatzsuche in OpenStreetMap||Presentation||Roland Olbricht||German||Abstract, Video|
|March 2015||FOSSGIS 2015||Münster (DE)||OpenStreetMap-Daten pflegen und finden mit der Overpass API||Workshop (paid)||Roland Olbricht||German||no material available|
|February 2015||FOSDEM 2015||Bruxelles (BE)||Overpass-API - A service to query OpenStreetMap data||Presentation||Roland Olbricht||English||Slides, Video|
|September 2014||Bonn (DE)||Overpass-API Seminar bei ZERA||Workshop||Roland Olbricht||German||Manuscript, Slides|
|June 2014||SotM-EU 2014||Karlsruhe (DE)||Overpass API v0.7.50 - The temporal dimension||Presentation||Roland Olbricht||English||Slides/Video|
|June 2014||SotM-EU 2014||Karlsruhe (DE)||Sparse Editing - Editing Large-Scale Objects||Presentation||Roland Olbricht||English||Slides/Video|
|April 2014||Grazer Linuxtage 2014||Graz (AT)||OpenStreetMap Daten nutzen||Presentation||Martin Raifer||German||Slides|
|March 2014||FOSSGIS 2014||Berlin (DE)||Daten aus OpenStreetMap extrahieren, analysieren und filtern mit der Overpass API||Workshop (paid)||Roland Olbricht||German||no material available|
|October 2013||Intergeo 2013||Essen (DE)||OSM-Daten direkt nutzen mit der Overpass API||Presentation||Roland Olbricht||German||Slides|
|October 2013||OSMit 2013||Rovereto (IT)||Overpass Turbo||Presentation||Martin Raifer||Italian||Slides|
|March 2013||FOSSGIS 2013||Rapperswil (CH)||Daten aus OpenStreetMap extrahieren, analysieren und filtern mit der Overpass API||Workshop||Roland Olbricht||German||Slides|
|March 2013||FOSSGIS 2013||Rapperswil (CH)||overpass turbo - Einfache Analyse von OpenStreetMap Daten||Presentation||Martin Raifer||German||Slides, Video, Tagungsband FOSSGIS 2013|
|March 2013||FOSSGIS 2013||Rapperswil (CH)||Mobile Karten erstellen mit OSM, OpenLayers und Overpass API||Presentation||Roland Olbricht||German||Slides, Video|
|December 2012||OSMDE009 OSM Talk: Die Overpass API||Podcast||Roland Olbricht, Stephan/RadioOSM||German||Link|
|March 2012||FOSSGIS 2012||Berlin (DE)||Overpass API||Presentation||Roland Olbricht||German||Slides, Tagungsband FOSSGIS 2012|
|July 2011||SotM-EU 2011||Vienna (AT)||Overpass API - an open and slim XAPI alternative||Presentation||Roland Olbricht||English||Slides, Video|
Olbricht, Roland (2015). "OpenStreetMap in GIScience". in Jokar Arsanjani, J.; Zipf, A.; Mooney, P. et al.. Springer International Publishing Switzerland. pp. 101-122.