Overpass API User's Manual

Overpass Turbo

The standard tool to develop requests.

A public instance is available at https://overpass-turbo.eu. It is, like Overpass API, open source, and the source code is available from Github. Martin Raifer has developed Overpass Turbo, and I'm grateful to him both for the idea and the software.

Almost all output formats that the Overpass API can emit can be understood by Overpass Turbo. Very large result sets cause difficulties; the JavaScript engines even of contemporary browsers then get strained in their memory management. For this reason, Overpass Turbo will ask you if it has received a large set of results if you accept the risk to freeze your browser by the amount of data.

There are many popular and helpful features in Overpass Turbo, but they exceed the mission of this manual. Instead, the proper documentation of Overpass Turbo introduces them. Features not introduced here include e.g. styles and the request generator wizard. This manual concentrates on the immediate interaction between Overpass Turbo and the Overpass query language.

The interface of the website consists of multiple parts; these parts are differently arranged between desktop and mobile site version. Please open the site now in a separated browser tab.

In the desktop version there is on the left a large text field; please type or paste your request here. The right part is a slippy map. By the two tabs in the upper right corner this part can be switched between the map view and a text field showing the received raw data.

In the mobile version the text field sits above the slippy map. The second text field for the received raw data is below the slippy map. Instead of the tabs you switch between the two parts by intense scrolling.

We exercise the standard use case: Please enter into the text field ...

nwr[name="Canary Wharf"];
out geom;

... or use this link!

Please click now on Execute. For a short moment a progress meter asks you to be patient. Then you see almost exactly the same as before.

Please click now on the magnifier. This is on the left brim of the slippy map the third symbol counted from the top, below the plus and minus buttons. The slippy map moves to the center of the results and the finest possible resolution such that still all results fit into the viewport.

The objects marked in the map view are now exactly the objects that the request has found.

It is often useful to view the raw returned data. It gets shown when you click on the tab Data above the upper right corner of the map view respectively with scrolling in the mobile version.

Meanwhile, all on the map highlighted objects are clickable and show on click, depending on the degree of detail of the request, their id, their tags, and their metadata.

Eventually you will get the warning that not for all objects the geometry has been delivered. Then you can try out the automatic completion of the request. Or you replace all out in the request by their counterparts with geometry out geom.

If you anticipate a large result or if you want to process the result anyway with a different tool than Overpass Turbo then you can directly export the data without an attempt to display them: Please go to Export, keep in the tab Data, and select raw data directly from Overpass API. For long running requests it is normal that apparently nothing happens after the click to trigger the request.

I suggest you to put attention to two useful features:

• In the lower right corner of the map view a counter shows how many objects of each type have been returned in the last request.
• In the upper left corner there is a search input field. Although it is less powerful than Nominatim on openstreetmap.org, it is usually good enough for the names of towns to place the slippy map at the right location.

The documentation of Overpass Turbo already explains the colours. We put our attention rather to the interaction here: For a given object or type of object you have an idea whether it is a point, a line, a composition of both, something abstract or something with a fuzzy boundary. In the OpenStreetMap data structures it is modeled in some way; this can meet or differ from your expectation.

The Overpass API offers tools to change from the OpenStreetMap representation to a representation that better fits the presentation. This can happen by amending the coordinates, geometric simplification, or by cropping. Overpass Turbo strives to always present in the best possible way, no matter whether the representation in OpenStreetMap makes sense, and also no matter whether the output format chosen in the request fits to the data or not.

This section shall explain what presentation finally the given situation results in and how this is influenced by the request and the data.

Objects appearing as points can have a yellow or a red interior. Those with yellow interior are nodes while those with red interior are ways.

Ways can be morphed to points due to their small extent because otherwise they may become too unremarkable: Please zoom out in this example and observe how buildings and streets morph into points!

( way({{bbox}})[building];
  way({{bbox}})[highway=steps]; );
out geom;

If this hampers the presentation of a specific result, then you can turn that off at Settings, Map, Don't display small features as POIs. The setting comes into effect with the execution of the next request (or the same request again).

Or the objects have been collapsed because the request has asked only for points by out center:

way({{bbox}})[building];
out center;

Point objects can have a blue or a purple border; and this applies also to line segments or areas. In all these cases, relations are involved:

rel[name="Canary Wharf"];
out geom;

Opposed to nodes or ways, the details of the relation then are not shown by a click on the object, but in the object's bubble there is just a link to the relation's presentation on the main server. Under normal circumstances, this is no problem.

But if you have asked for a museum version different from the current version, then the data from the main page is still the current version and thus differs from the data returned from your request. Rather, you need to look into the raw data shown in the tab Data.

If the line or boundary of the area is dashed, then the geometry of the object is incomplete. This is almost always an intended effect of the output clipping (example):

(
  way(51.475,-0.002,51.478,0.003)[highway=unclassified];
  rel(bw);
);
out geom(51.475,-0.002,51.478,0.003);

But it can also be the effect of a request that has added for a way some but not all nodes. Here we have loaded ways based on nodes, but we have forgotten to ask for the nodes referred by the ways but outside the bounding box:

(
  node(51.475,-0.003,51.478,0.003);
  way(bn);
);
out;

The request can be fixed by out geom; more possibilities are listed in the section about geometry:

(
  node(51.475,-0.003,51.478,0.003);
  way(bn);
);
out geom;

You can make the sent bounding box visible if you set this substring in a different location than usual (and then press execute):

make example info_text="The current bounding box is {{bbox}}";
out;

A second handy feature is controlled by the button Share in the upper left corner. This creates a permanent link where you can get back the request written at the moment when the link has been created. Even if somebody else opens the link and edits the request, then the link still points to the originally stored request.

It is also possible, per checkbox, to convey the current map viewport. This manifests as center coordinate and zoom level, in particular the visible map differs between screens of different sizes.

Per object id and type Overpass Turbo shows only one object. Thus, diffs cannot be visualized by Overpass Turbo in a meaningful way.

Overpass Turbo does not show GeoJSON directly from the Overpass API. Overpass Turbo has its own conversion module for GeoJSON, and Martin is wary of the user confusion if both mechanisms are active in parallel. For the moment being, to show GeoJSON you need to use the experimental instance https://olbricht.nrw/ovt/.

next: Spatial Data Selection