The Overpass Tutorial

Overpass (actually "The Overpass API") is a powerful way to query OpenStreetMap data. You can ask it questions like:

• Show me all museums in Austria
• Show me which roads were edited in the last hour

Overpass will then give you an answer in OSM XML, JSON or CSV.

To ask Overpass questions like the ones above, you will need to learn its language. That is what we will do in this tutorial.

Confusingly, there are two dialects that Overpass understands. One is XML based, which is harder to read for most humans. We will ignore that dialect in this tutorial and focus on Overpass QL, the Overpass Query Language. It looks like this:

area[name="Troisdorf"];
way(area)[highway][name];
out;

Don't worry if that makes no sense to you at all right now. That's why you are here to learn! If you have some programming experience, you will recognize some familiar elements, like semicolons to separate statements.

For this tutorial, we will be making extensive use of a website called Overpass Turbo. Overpass Turbo makes it easy to test queries, shows the answer on a map, can help you fix errors in your queries, share your work and export the answers.

Before we start

We tried very hard to make this tutorial as gentle an introduction to Overpass as possible. We do not assume that you have used Overpass before at all. However, to be successful you should be familiar with the OpenStreetMap data model of nodes, ways, relations and tags. Mapbox has a really good guide covering those topics.

We will have 'bonus' pieces of information here and there. They will look like this. You can skip them without worrying you will miss anything important.

So let's get started!

Hello Overpass

As we mentioned before, we will be using Overpass Turbo throughout this tutorial. So let's start by pointing your browser there:

https://overpass-turbo.eu/

If this is the first time you visit the Overpass Turbo web site, it will have an example query already in place:

/*
This is an example Overpass query.
Try it out by pressing the Run button above!
You can find more examples with the Load tool.
*/
node
  [amenity=drinking_water]
  ({{bbox}});
out;

If you see something different, or the query editor pane (the left side of the window) is empty, you can copy the the example from here and paste it in the editor pane.

Click Run to try it out.

After a few seconds, you will see the map on the right change. Small circles appear that you can click on. This is the answer to the example query!

Let's pick this apart and see what happened.

When you clicked Run, Overpass Turbo looked at the query in the editor and saw it was valid. Overpass Turbo then sent the query to the Overpass API and waited for the result. When it came in, it displayed the result on the map.

Remember, Overpass Turbo is 'just' a nice front for the Overpass API. The API itself just returns data in XML format. (You can specify other response formats in the query, more about that later.) To see what the Overpass API actually returned, click on the Data tab above the map pane.

Next, let's look at the query piece by piece.

/*
This is an example Overpass query.
Try it out by pressing the Run button above!
You can find more examples with the Load tool.
*/

The first few lines are a comment. Comments are not part of the actual query, but serve to clarify the actual code. The /* signals the start of a comment, and */ signals the end of it. Each of these need to be on a separate line all by themselves.

A comment does not have to be multiple lines. A simple comment that fits on one line starts with // followed by the comment itself: // I am a comment line

node

First, we tell Overpass that we are looking for OSM nodes, rather than ways, or relations.

  [amenity=drinking_water]

Next, we tell Overpass that we are looking for the tag amenity with the value drinking_water. Notice how this part is surrounded by [] square brackets. We use square brackets to look for nodes (or other OSM features) that have particular tags or tag patterns.

We can add more than one of these clauses if we are interested only in a specific combination of tags, for example [amenity=drinking_water][hot_water=yes] to only look for drinking water sources that have hot water.

  ({{bbox}});

In this next part we tell Overpass about the geographic area we are interested in. Note how this part has round brackets () around it.

The query will only return things that are within the area we define here. In this case, the query specifies that we are interested in the "bounding box" (bbox) or extent of the map to the right.

This is a special Overpass Turbo trick. Before the query is sent to the API, {{bbox}} gets translated to the actual coordinates of the map extent.

See the semicolon ; at the end? This tells Overpass we have reached the end of the statement. The entire part starting with node up to here is one statement.

out;

Finally, we tell overpass to output the result. This seems unnecessary: what good is a query if there is no result that we can see? The answer to that is a little complex, we will go into detail a little later. For now just remember that every query needs to end with out; for it to give us a result.

That's it!

Phew! We have covered a lot of things in this first lesson. In the next lessons, we will look more closely at building and sharing Overpass queries using Overpass Turbo. See you there!