Overpass API - OpenStreetMap Wiki

Introduction

The Overpass API (formerly known as OSM Server Side Scripting, or OSM3S before 2011) 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 10 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.

Please see the full user's manual for a detailed introduction.

There exists in addition a 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.

Public Overpass API instances

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

Munin

Usage policy Main Overpass API instance

Global

https://lz4.overpass-api.de/api/interpreter

0.7.56.7 b85c4387

yes

4 physical cores, 64 GB RAM, SSD

Link

Any of the three servers has 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 and download less than 5 GB data per day. The address overpass-api.de and endpoint https://overpass-api.de/api/interpreter will continue to work and redirects per round robin to z and lz4. Main Overpass API instance

Global

https://z.overpass-api.de/api/interpreter

0.7.56.8 7d656e78

yes

4 physical cores, 64 GB RAM, SSD

Link Russian Overpass API instance

Global

https://overpass.openstreetmap.ru/api/interpreter

0.7.55.7 8b86ff77

no

8 cores, 64 GB RAM, hard disks

? French Overpass API instance

Global

https://overpass.openstreetmap.fr/api/interpreter

0.7.54.10 2e325488

no

8 cores, 16 GB RAM, SSD

[1]

You are welcome to use that API for any purpose. As long as you don't exceed 1000 queries per day per "project". (By "project" I mean if you use this API in a smartphone app and you have 10,000 customer querying once per day then you are above the limit). Swiss Overpass API instance

Switzerland only

https://overpass.osm.ch/api/interpreter

0.7.55.7 8b86ff77

no

12 cores, 64 GB RAM, hard disks

?

Ask User:Datendelphin Kumi Systems Overpass Instance

Global

https://overpass.kumi.systems/api/interpreter

0.7.56.3 eb200aeb

maybe (theoretically enabled, not officially supported)

4 servers with 20 cores, 256GB RAM, SSD each

-

Feel free to use our service in any project, there is no rate limit in place. Please notify us in advance if you intend to use our service in a large scale project. Operational issues/questions/feedback? Please post a support ticket. Taiwan Overpass API

Global

https://overpass.nchc.org.tw/api/interpreter

0.7.56.3 eb200aeb

yes

?

?

If you have any question or feedback, please contact OSM.tw or contact NCHC FSL

An Overpass API endpoint is also available for Open Historical Map.

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?

Of course: please read the documentation first.

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.

Please note that old questions and answers on these sites often are outdated. Missing features may have been implemented in the meantime, and workarounds may have been streamlined. I estimate a reasonable expiration limit to be two years.

In addition, only OSM Help is managed by the OSM community, the other sites are controlled by third parties.

Site

Language

Frequently used 'tags' for questions OSM Help

English

overpass, overpass-turbo GIS StackExchange

English

overpass-api Stack Overflow

English

overpass-api OSM US Slack (channel #overpass)

English

OSM Dev Telegram group

English

OSM World Discord (channel #developer)

English

Developers / System Administrators

You can install your own instance from the latest stable release or the git source code repository (latest version). It is licensed under the Affero GPL v3.

The project is maintained by Roland Olbricht (mail: [email protected]). Contributions like bug reports or pull requests to the source code are welcome.

There is a mailing list for developers

Limitations

Every service has its limitations, and so does Overpass API:

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 (including metadata) from a given bounding box (these requests are compacted to the minimum; note that the icon links to run those requests also include parameters to set the center of the rendered map at specified coordinates and zoom level, and to run the request immediately on load):

Overpass QL

Overpass XML

(
   node(51.249,7.148,51.251,7.152);
   <;
);
out meta;

<union>
  <bbox-query s="51.249" w="7.148" n="51.251" e="7.152"/>
  <recurse type="up"/>
</union>
<print mode="meta"/>

To run this query, you can feed it into this query form, or you can use Overpass Turbo to see the results on a map.

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

To find out more about the Overpass API query language, see Overpass API Language Guide, as well as the Overpass API Query Language description.

Resource management options (osm-script)

The osm-script is silently added if you don't specify it explicitly when using the XML syntax. The reason to specify one explicitly is to tweak the resource management options by setting optional XML attributes (equivalent bracketted options may also be specified in an empty statement at start of your query when using the QL syntax).

Overpass XML

Overpass QL

<osm-script timeout="900" element-limit="1073741824">
  <bbox-query s="51.15" w="7.0" n="51.35" e="7.3"/>
  <print/>
</osm-script>

[timeout:900][maxsize:1073741824];
node(51.15,7.0,51.35,7.3);
out;

This query 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).

Warning: when running this example, more than 100 MiB of data will be retrieved (even if it does not recurse up to give all details like in the first example, here it will only retrieve a flat list of nodes with their tags). Overpass will alert you if you run it directly in your browser to render the data on the map, the browser tab may crash if you continue loading it. The results of such large requests should be downloaded for processing by other tools.

These resource limits cannot be set to arbitrary high values: each Overpass API instance may refuse to extend them above some threshold (depending on server capabilities or current server load), or the query may just fail with an error message (and non-OK HTTP server error status).

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 this query form.

Note: Queries may take several minutes to be completed. If you receive timeouts, you can extend the timeout period.

Recurse

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 E61. In fact, get all bus stops served by E61.

Overpass QL

Overpass XML

rel[ref="E61"];
node(r);

out body;

<osm-script><query type="relation">
  <has-kv k="ref" v="E61"/>
</query>
<recurse type="relation-node"/>

<print/></osm-script>

Get the ways of all relations that have the key ref with value E61. In fact, that is the itinerary served by E61.

Overpass QL

Overpass XML

rel[ref="E61"];
way(r);

out body;

<osm-script><query type="relation">
  <has-kv k="ref" v="E61"/>
</query>
<recurse type="relation-way"/>

<print/></osm-script>

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.

Overpass QL

Overpass XML

rel[ref="E61"];
way(r);
node(w);

out body;

<osm-script><query type="relation">
  <has-kv k="ref" v="E61"/>
</query>
<recurse type="relation-way"/>
<recurse type="way-node"/>

<print/></osm-script>

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="E61"/>
</query>
<recurse type="relation-backwards"/>

<print/>

Around

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/>

Building blocks

We still have some helper statements to explain, in particular union, item, the variable mechanism, and foreach.

Again, all of the following examples can be tested by copying the snippets to this form.

Union

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.

Foreach

<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, please have a look at Areas wiki page for details. 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.

Meta data

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

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.

See example prerendered views on the right. More examples on this page.

On this wiki, you can create links to this tool with the documented {{Sketch Line}} template.

(Please be patient - each request can take up to 10 seconds to generate, depending on server load.)

Note: As of Overpass API v0.7.52, PTv2 support has some known issues, resulting in duplicate stop names or some gaps, see Github issue #190. Rendering issues for newer PTvX versions or variations thereof may be possible as well.

XAPI Compatibility Layer

For details and examples see:

Programs/Scripts around Overpass

Python API

• There is a Python transpiler which converts a Python function to an Overpass query
• There is a simple Python wrapper written by Martijn van Exel (talk).
• There is an advanced Python wrapper called OverPy
• OSMPythonTools provides easy access to OSM related services, including Overpass

Node.js API

• query-overpass is a simple API wrapper and CLI for Overpass.

Converters

• 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.

Date

Event

Location

Title

Type

Speaker

Language

Links February 2020

OSMit 2020

Torino (IT)

Overpass Turbo: oltre il wizard

Presentation

Andrea Albani

Italian

Slides Examples September 2019

SotMUS 2019

Minneapolis (US)

A turbo introduction to Overpass

Presentation

Minh Nguyễn

English

Video, Slides, Slides+notes Autumn 2017

Université Rennes (FR)

Introduction aux données OpenStreetMap et à l'API Overpass Turbo

Presentation

Boris Mericskay

French

Slides September 2016

SotM 2016

Brussels (BE)

Gardening OSM data with Overpass API

Presentation

Roland Olbricht

English

Video July 2016

FOSSGIS 2016 - OSM-Sonntag

Salzburg (AT)

Overpass-Abfragen jenseits key=value selber schreiben

Workshop

Nakaner

German

Slides May 2016

SOTM FR 2016

Clermont-Ferrand (FR)

Démystifier l'API Overpass / Demystify the Overpass API

Workshop

Antoine Riche

French

Video Oct 2015

FOSS@HFT Stuttgart

Stuttgart (DE)

Parametrisierter Download aus einer weltweiten Geodatenbank (OpenStreetmap) sowie daran anschliessend mit dem Workshop Algorithmik und Technik, Hypothesenprüfung

Presentation/Workshop

Roland Olbricht

German

Video 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

Audio 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

Books

Olbricht, Roland (2015). “OpenStreetMap in GIScience”. in Jokar Arsanjani, J.; Zipf, A.; Mooney, P. et al.. Springer International Publishing Switzerland. pp. 101-122.