Overpass API/Language Guide

From OpenStreetMap Wiki
Jump to: navigation, search
Available languages
Deutsch English

This guide shows you a lot of examples for queries with Overpass API. You are invited to adapt the queries to your particular need.

Background and concepts

Overpass API allows to query for OSM data by your own search criteria. For this purpose, it has a specifically crafted query language.

The basic semantics of Overpass API is that flows of OSM data (nodes, ways...) are generated and modified by statements, which are executed one after another. The following simple query can for instance generate a flow of data containing all the nodes in a given bounding box, and print it:

node(50.745,7.17,50.75,7.18);out;

You can then filter further the resulting flow, looking only for the bus stops:

node(50.745,7.17,50.75,7.18)[highway=bus_stop];out;

Or you could also extend the result to include the ways which are referencing using the selected nodes. In this case, you may also want to extend the result with all nodes referenced by these ways:

node(50.745,7.17,50.75,7.18);way(bn);(._;>;);out;

These statements and their syntax are described in more details below.

The languages

Overpass API now offers its full expressive power within a single HTTP GET request. For this purpose, the new query language Overpass QL is introduced in parallel to the established XML query language. You can always convert between the two: Just paste one of the examples below into http://overpass-api.de/convert_form.html. You can choose there to get the output in

  • XML query format: this matches the XML form below in all the examples.
  • to pretty Overpass QL: this matches the Overpass QL form below.
  • to concise Overpass QL: this yields a one-line HTTP GET request for the same expression.

To execute the query, use instead http://overpass-api.de/query_form.html.

You have already seen a few examples of the QL syntax below. The QL syntax is more concise, and is to some extend similar to C-alike programming languages. A statement always ends with a semicolon ";". Furthermore:

  • A statement is either a query statement. Then it starts with "node", "way", "rel" or "relation" ("rel" is just a shorthand for "relation") or is one of the special statements ">", ">>", "<", or "<<".
  • Or it is an output statement. Then it starts with "out".

Query statements consist of the type and of at least one clause. There are different types of clauses:

All variants of tag requests; e.g.,

  ["key"="value"]
  ["key"]
  ["key"~"value"]
  ["key"!="value"]
  ["key"!~"value"]

Or bounding box clauses

  (51.0,7.0,52.0,8.0)

Bounding box clauses always start with the lower latitude followed by lower longitude, then upper latitude then upper longitude. Note that this is different from the ordering in the XAPI syntax. The XML syntax is safeguarded by using named parameters.

Or recursion forward or backward about membership links

  (r)
  (w)
  (n)
  (br)
  (bw)
  (bn)
  (>)
  (>>)
  (<)
  (<<)

Or special clauses of the form "(type:value)".

More details are provided in the respective parts of the Usage Examples.

About the links

Most examples are illustrated with showing links to a map. This is still a very experimental solution. The bounding box is fixed to show always the German town Bonn. And some queries take quite a lot of time, maybe over a minute if none of the needed data is in the cache on the server. The symbols are ugly, but this could also be changed for a mashup layer aiming at end users. They should be primarily easy to find.

Usage examples

Wherever you see the this symbol: overpass turbo icon, you can click it to use overpass turbo for inspecting the query and its results.

Find something

Finding something in the OpenStreetMap data always means to search for a location or for the values of certain tags. You can choose any key for the tag in the following examples. In a first step, we find objects by their names, thus we search for certain values of the key "name".

By exact name

In our first example, we search for a node by the value of its name tag:

Overpass XML Overpass QL
try it yourself in overpass-turbo
<osm-script>
  <query type="node">
    <has-kv k="name" v="Gielgen"/>
  </query>
  <print/>
</osm-script>
try it yourself in overpass-turbo
node["name"="Gielgen"];
out body;

Display result: OpenLayers map, JSON, XML.

By exact name and rough location

If this isn't exact enough, you could also specify a bounding box to get results from only within a certain bounding box. The coordinate order is (lower lat., lower lon., upper lat., upper lon.). If you don't have a bounding box, the following example may fit better to you:

Overpass XML Overpass QL
try it yourself in overpass-turbo
<osm-script>
  <query type="node">
    <has-kv k="name" v="Gielgen"/>
    <bbox-query e="7.25" n="50.8" s="50.7" w="7.1"/>
  </query>
  <print/>
</osm-script>
try it yourself in overpass-turbo
node
  ["name"="Gielgen"]
  (50.7,7.1,50.8,7.2);
out body;

Display result: OpenLayers map, JSON, XML.

Something near something else

A less technical way to get one of multiple results can be to find something by providing a nearby location. For example, you can search for a location called "Gielgen" in a 1000 meter radius of a location called "Bonn".

Overpass XML Overpass QL
try it yourself in overpass-turbo
<osm-script>
  <query type="node">
    <has-kv k="name" v="Bonn"/>
  </query>
  <query type="node">
    <around radius="1000"/>
    <has-kv k="name" v="Gielgen"/>
  </query>
  <print/>
</osm-script>
try it yourself in overpass-turbo
node["name"="Bonn"];
node
  (around:1000)
  ["name"="Gielgen"];
out body;

Display result: OpenLayers map, JSON, XML.

Non-exact names

But even when you don't know the exact name, you can find the object. For that purpose, Overpass API supports (POSIX extended) regular expressions. We give a couple of examples for useful regular expressions.

The first example searches for any node that contains the substring "holtorf" in its name:

Overpass XML Overpass QL
try it yourself in overpass-turbo
<osm-script>
  <query type="node">
    <has-kv k="name" regv="holtorf"/>
    <bbox-query e="7.25" n="50.8" s="50.7" w="7.1"/>
  </query>
  <print/>
</osm-script>
try it yourself in overpass-turbo
node
  ["name"~"holtorf"]
  (50.7,7.1,50.8,7.25);
out body;

Display result: OpenLayers map, JSON, XML.

The second example searches for any node that has the substring "Holtorf" as the beginning of the name:

Overpass XML Overpass QL
try it yourself in overpass-turbo
<osm-script>
  <query type="node">
    <has-kv k="name" regv="^Holtorf"/>
    <bbox-query e="7.25" n="50.8" s="50.7" w="7.1"/>
  </query>
  <print/>
</osm-script>
try it yourself in overpass-turbo
node
  ["name"~"^Holtorf"]
  (50.7,7.1,50.8,7.25);
out body;

Display result: OpenLayers map, JSON, XML.

The third example searches for any node that has the substring "holtorf" as the end of the name:

Overpass XML Overpass QL
try it yourself in overpass-turbo
<osm-script>
  <query type="node">
    <has-kv k="name" regv="Holtorf$"/>
    <bbox-query e="7.25" n="50.8" s="50.7" w="7.1"/>
  </query>
  <print/>
</osm-script>
try it yourself in overpass-turbo
node
  ["name"~"holtorf$"]
  (50.7,7.1,50.8,7.25);
out body;

Display result: OpenLayers map, JSON, XML.

Of course you could also search for "^Holtorf$", but this is the same as a simple search for equal value.

And you can search case insensitive with regular expressions by enclosing both variants in brackets:

Overpass XML Overpass QL
try it yourself in overpass-turbo
<osm-script>
  <query type="node">
    <has-kv k="name" regv="[hH]oltorf"/>
    <bbox-query e="7.25" n="50.8" s="50.7" w="7.1"/>
  </query>
  <print/>
</osm-script>
try it yourself in overpass-turbo
node
  ["name"~"[hH]oltorf"]
  (50.7,7.1,50.8,7.25);
out body;

Display result: OpenLayers map, JSON, XML.

Accents and decorated characters

A lot of European languages have modified variants of the well known Latin characters, not only "e" but also "é" or "ê". You can obtain them with a regular expression:

By list listing candidates:

Overpass XML Overpass QL
try it yourself in overpass-turbo
<osm-script>
  <query type="node">
    <has-kv k="name" regv="H[oôóòö]ltorf"/>
    <bbox-query e="7.25" n="50.8" s="50.7" w="7.1"/>
  </query>
  <print/>
</osm-script>
try it yourself in overpass-turbo
node
  ["name"~"H[oôóòö]ltorf"]
  (50.7,7.1,50.8,7.25);
out body;

Or by leaving a wildcard:

Overpass XML Overpass QL
try it yourself in overpass-turbo
<osm-script>
  <query type="node">
    <has-kv k="name" regv="H.ltorf"/>
    <bbox-query e="7.25" n="50.8" s="50.7" w="7.1"/>
  </query>
  <print/>
</osm-script>
try it yourself in overpass-turbo
node
  ["name"~"H.ltorf"]
  (50.7,7.1,50.8,7.25);
out body;

Please note: A single wildcard replaces a single UTF-8 codepoint, not necessarily only a single byte. So a single dot matches "e" as well as "é" or "ê".

One or another name

If you want to allow two alternative values, you can use a pipe for that.

Overpass XML Overpass QL
try it yourself in overpass-turbo
<osm-script>
  <query type="node">
    <has-kv k="name" regv="holtorf|Gielgen"/>
    <bbox-query e="7.25" n="50.8" s="50.7" w="7.1"/>
  </query>
  <print/>
</osm-script>
try it yourself in overpass-turbo
node
  ["name"~"holtorf|Gielgen"]
  (50.7,7.1,50.8,7.25);
out body;

Display result: OpenLayers map, JSON, XML.

More information about (POSIX extended) regular expressions can be found on the console or by your favourite search engine with "man 7 regex".

Negation

Regular expressions don't allow negation on their own. For that reason, there is an explicit negation operator in Overpass QL.

For example, the following query yields all ways that do not have a highway key value:

Overpass XML Overpass QL
try it yourself in overpass-turbo
<osm-script>
  <query type="way">
    <has-kv k="highway" modv="not" regv="."/>
    <bbox-query e="7.18" n="50.75" s="50.74" w="7.17"/>
  </query>
  <print limit="" mode="body" order="id"/>
</osm-script>
try it yourself in overpass-turbo
way
  ["highway"!~"."]
  (50.74,7.17,50.75,7.18);
out body;

Display result: OpenLayers map, JSON, XML.

As a second example, you can restrict a query for bus stops to those that have a shelter. Technically, we search for nodes with "highway"="bus_stop" and tag "shelter" present, but not set to "no".

Overpass XML Overpass QL
try it yourself in overpass-turbo
<osm-script>
  <query type="node">
    <has-kv k="highway" v="bus_stop"/>
    <has-kv k="shelter"/>
    <has-kv k="shelter" modv="not" v="no"/>
    <bbox-query e="7.25" n="50.8" s="50.7" w="7.1"/>
  </query>
  <print/>
</osm-script>
try it yourself in overpass-turbo
node
  ["highway"="bus_stop"]
  ["shelter"]
  ["shelter"!="no"]
  (50.7,7.1,50.8,7.25);
out body;

Display result: OpenLayers map, JSON, XML.

The same thing with regular expressions:

Overpass XML Overpass QL
try it yourself in overpass-turbo
<osm-script>
  <query type="node">
    <has-kv k="highway" v="bus_stop"/>
    <has-kv k="shelter"/>
    <has-kv k="shelter" modv="not" regv="no"/>
    <bbox-query e="7.25" n="50.8" s="50.7" w="7.1"/>
  </query>
  <print/>
</osm-script>
try it yourself in overpass-turbo
node
  ["highway"="bus_stop"]
  ["shelter"]
  ["shelter"!~"no"]
  (50.7,7.1,50.8,7.25);
out body;

Display result: OpenLayers map, JSON, XML.

Multiple tags

Of course you can search also for nodes that have a tag "highway" to value "bus_stop" and a tag "shelter" to value "yes":

Overpass XML Overpass QL
try it yourself in overpass-turbo
<osm-script>
  <query type="node">
    <has-kv k="highway" v="bus_stop"/>
    <has-kv k="shelter" v="yes"/>
    <bbox-query e="7.25" n="50.8" s="50.7" w="7.1"/>
  </query>
  <print/>
</osm-script>
try it yourself in overpass-turbo
node
  ["highway"="bus_stop"]
  ["shelter"="yes"]
  (50.7,7.1,50.8,7.25);
out body;

Display result: OpenLayers map, JSON, XML.

Streets and other ways

Every of the above queries also works for ways or relations. We search for the street "Gielgenstraße" within the now well-known bounding box:

Overpass XML Overpass QL
try it yourself in overpass-turbo
<osm-script>
  <query type="way">
    <has-kv k="name" v="Gielgenstraße"/>
    <bbox-query e="7.25" n="50.8" s="50.7" w="7.1"/>
  </query>
  <print/>
</osm-script>
try it yourself in overpass-turbo
way
  ["name"="Gielgenstraße"]
  (50.7,7.1,50.8,7.25);
out;

Display result: OpenLayers map, JSON, XML.

Please note that you need to also request the nodes of the way if you want to display the way in map (or need the coordinates for another reason. This is done with an extra-recurse down statement. To get also the way, we put both in an union statement. All these statements are explained further down.

Overpass XML Overpass QL
try it yourself in overpass-turbo
<osm-script>
  <query type="way">
    <has-kv k="name" v="Gielgenstraße"/>
    <bbox-query e="7.25" n="50.8" s="50.7" w="7.1"/>
  </query>
  <union>
    <item />
    <recurse type="way-node"/>
  </union>
  <print/>
</osm-script>
try it yourself in overpass-turbo
(
  way
    ["name"="Gielgenstraße"]
    (50.7,7.1,50.8,7.25);
  >;
);
out;

Relations

And now we search for the relation of "network"="VRS" and "ref"="636". This is a local bus service. As the network shortcut is unique, we don't need a bounding box or any other similar aid.

Overpass XML Overpass QL
try it yourself in overpass-turbo
<osm-script>
  <query type="relation">
    <has-kv k="network" v="VRS"/>
    <has-kv k="ref" v="636"/>
  </query>
  <print/>
</osm-script>
try it yourself in overpass-turbo
relation
  ["network"="VRS"]
  ["ref"="636"];
out body;

Display result: OpenLayers map, JSON, XML.

All kind of objects

And, finally, we search for all kind of objects with a certain tag within a bounding box. You need to repeat the tag for every type and to use the union operator. To allow us displaying everything on a map, we also ask for the nodes and ways that are referred by the relations and ways in the result:

Overpass XML Overpass QL
try it yourself in overpass-turbo
<osm-script>
  <union>
    <query type="node">
      <has-kv k="amenity" v="fire_station"/>
      <bbox-query e="7.3" n="50.8" s="50.6" w="7.0"/>
    </query>
    <query type="way">
      <has-kv k="amenity" modv="" v="fire_station"/>
      <bbox-query e="7.3" n="50.8" s="50.6" w="7.0"/>
    </query>
    <query type="relation">
      <has-kv k="amenity" modv="" v="fire_station"/>
      <bbox-query e="7.3" n="50.8" s="50.6" w="7.0"/>
    </query>
  </union>
  <union>
    <item/>
    <recurse type="down"/>
  </union>
  <print/>
</osm-script>
try it yourself in overpass-turbo
(
  node
    ["amenity"="fire_station"]
    (50.6,7.0,50.8,7.3);
  way
    ["amenity"="fire_station"]
    (50.6,7.0,50.8,7.3);
  rel
    ["amenity"="fire_station"]
    (50.6,7.0,50.8,7.3);
);
(._;>;);
out;

Display result: OpenLayers map JSON, XML.

All data in a bounding box

The bbox-query lets you download all nodes, ways or relations from the given bounding box. Specify with

  • s the southern limit (bottom lat.)
  • n the northern limit (top lat.)
  • w the western limit (usually lower lon.)
  • e the eastern limit (usually higher lon.)

Note that the western limit is higher than the eastern limit if and only if you query surpasses the longitude ±180.0.

Please note also that the Overpass QL form has the order (s, w, n, e), which is (lower lat., usually lower lon., higher lat., usually higher lon.). This is more concise, but of course requires some care to get the order right.

Nodes

All nodes in a small sample bounding box:

Overpass XML Overpass QL
try it yourself in overpass-turbo
<osm-script>
  <bbox-query e="7.157" n="50.748" s="50.746" w="7.154"/>
  <print/>
</osm-script>
try it yourself in overpass-turbo
node(50.746,7.154,50.748,7.157);
out body;

Display result: OpenLayers map, JSON, XML.

Ways

In a similar fashion, you can get all ways of the bounding box. A way is found not only if it has a node inside the bounding box but also if it just crosses somewhere the bounding box.

Overpass XML Overpass QL
try it yourself in overpass-turbo
<osm-script>
  <query type="way">
    <bbox-query e="7.157" n="50.748" s="50.746" w="7.154"/>
  </query>
  <print/>
</osm-script>
try it yourself in overpass-turbo
way(50.746,7.154,50.748,7.157);
out body;

Display result: OpenLayers map, JSON, XML.

Relations

A relation is found in a bounding box if it has a member of type node or way within the bounding box.

Overpass XML Overpass QL
try it yourself in overpass-turbo
<osm-script>
  <query type="relation">
    <bbox-query e="7.157" n="50.748" s="50.746" w="7.154"/>
  </query>
  <print/>
</osm-script>
try it yourself in overpass-turbo
relation(50.746,7.154,50.748,7.157);
out body;

Display result: OpenLayers map, JSON, XML.

Sample map calls

In general, you will be rather interested in complete data than just elements of a single type. First, there are several valid definitions of what "complete map data" means. The first unclear topic is what to do with nodes outside the bounding box which are members of ways that lie partly inside the bounding box.

The same question repeats for relations. If you wait for a turn restriction, you may prefer to get all elements of the relation included. If your bounding box hits for example the border of Russia, you likely don't want to download ten tousands kilometers of boundary around half the world.

A second question for relations is whether relations on relations should be included.

For that reason, we subsequently give examples for several variants of map calls. It is a discipline where the query paradigm shows its strength: you can construct a query of any flavor you want. Just choose from the examples below or modify them to your needs.

The particular statements of the calls are explained in the more advanced sections further below.

Simplest possible map call

This call includes all nodes in the bounding box, all ways that have such a node as member, and all relations that have such a node or such a way as members. Please observe that not all returned ways or relations are displayed in Open Layers because Open Layers requires all nodes of a way or members of a relation to be present.

Overpass XML Overpass QL
try it yourself in overpass-turbo
<osm-script>
  <union into="_">
    <bbox-query e="7.157" n="50.748" s="50.746" w="7.154"/>
    <recurse type="up"/>
  </union>
  <print mode="meta"/>
</osm-script>
try it yourself in overpass-turbo
(
  node(50.746,7.154,50.748,7.157);
  <;
);
out meta;

Display result: (Open Layers doesn't show), JSON, XML.

The operator "<" does here all the required backwards resolution of membership links of ways and relations. You could also break this up into step-by-step backwards recursion:

  • First, get all relations linking to the just found nodes: rel(bn);
  • Then, get all ways linking to the just found nodes: way(bn);
  • Finally, get all relations linking to the just found ways: rel(bw);

To complete the list of backwards membership resolution, rel(br); would find relations that have the just found relations as members.

Overpass XML Overpass QL
try it yourself in overpass-turbo
<osm-script>
  <union into="_">
    <bbox-query e="7.157" n="50.748" s="50.746" w="7.154"/>
    <recurse into="x" type="node-relation"/>
    <recurse type="node-way"/>
    <recurse type="way-relation"/>
  </union>
  <print mode="meta"/>
</osm-script>
try it yourself in overpass-turbo
(
  node(50.746,7.154,50.748,7.157);
  rel(bn)->.x;
  way(bn);
  rel(bw);
);
out meta;

Display result: (Open Layers doesn't show), JSON, XML.

Completed ways, but not relations

This call includes all nodes in the bouding box, all ways in the bounding box, all member nodes of these ways whether these are inside the bounding box or not, and all relations that have such a node or such a way as members. For the moment, the call of way with a bounding box makes the query sometimes slow. I will work on it, but please be patient for the moment. Please observe that not all returned relations are displayed in Open Layers because Open Layers requires all nodes of a way to be present.

Overpass XML Overpass QL
try it yourself in overpass-turbo
<osm-script>
  <union into="_">
    <bbox-query e="7.157" n="50.748" s="50.746" w="7.154"/>
    <recurse into="x" type="node-relation"/>
    <query type="way">
      <bbox-query e="7.157" n="50.748" s="50.746" w="7.154"/>
    </query>
    <recurse into="x" type="way-node"/>
    <recurse type="way-relation"/>
  </union>
  <print mode="meta"/>
</osm-script>
try it yourself in overpass-turbo
(
  node(50.746,7.154,50.748,7.157);
  rel(bn)->.x;
  way(50.746,7.154,50.748,7.157);
  node(w)->.x;
  rel(bw);
);
out meta;

Display result: OpenLayers map, JSON, XML.

Completed ways and relations

This call includes all nodes in the bouding box, all ways referring to any of these nodes, all member nodes of these ways whether these are inside the bounding box or not, all relations that have such a node or such a way as a member, and their node and way member, and even the nodes of these ways. Note that due to the involved relations, objects from quite far outside the bounding box are included.

Overpass XML Overpass QL
try it yourself in overpass-turbo
<osm-script>
  <union into="_">
    <bbox-query e="7.157" n="50.748" s="50.746" w="7.154"/>
    <recurse type="up"/>
    <recurse type="down"/>
  </union>
  <print limit="" mode="meta" order="id"/>
</osm-script>
try it yourself in overpass-turbo
(
  node(50.746,7.154,50.748,7.157);
  <;
  >;
);
out meta;

Display result: OpenLayers map, JSON, XML.

Here "<" does backwards membership resolution and ">" does forward membership resolution. In particular, ">" collects for all just found relations their member nodes, their member ways, and the member nodes of these member ways. This again can also be broken down into its building blocks:

  • node(w) collects the nodes that are members of the just found ways
  • node(r) does the same with the just found relations
  • way(r) collects the ways that are members of the just found relations

The statement rel(r) collects the relations that are members of the just found relations, but it is not invoked here. Now, the same query as before in a more step-by-step fashion:

Overpass XML Overpass QL
try it yourself in overpass-turbo
<osm-script>
  <union into="_">
    <bbox-query e="7.157" n="50.748" s="50.746" w="7.154"/>
    <recurse into="x" type="node-relation"/>
    <recurse type="node-way"/>
    <recurse type="way-relation"/>
  </union>
  <union into="_">
    <item set="_"/>
    <recurse type="relation-way"/>
  </union>
  <union into="_">
    <item set="_"/>
    <recurse into="x" type="relation-node"/>
    <recurse type="way-node"/>
  </union>
  <print mode="meta"/>
</osm-script>
try it yourself in overpass-turbo
(
  node(50.746,7.154,50.748,7.157);
  rel(bn)->.x;
  way(bn);
  rel(bw);
);
(
  ._;
  way(r);
);
(
  ._;
  node(r)->.x;
  node(w);
);
out meta;

Display result: OpenLayers map, JSON, XML.

Also relations on relations

This call includes additionally all relations on relations that after five steps of descent arrive at members in the bounding box. Their members are deliberately not included because that might end up with a significant part of all map data of Germany; i.e., several hundred megabyte of data. Note also that five levels of descent usually is more than enough to get all backlinks. If you doubt you have all backlinks, just add another rel(br); statement and see whether more data comes back.

Overpass XML Overpass QL
try it yourself in overpass-turbo
<osm-script>
  <union into="_">
    <bbox-query e="7.157" n="50.748" s="50.746" w="7.154"/>
    <recurse into="x" type="node-relation"/>
    <recurse type="node-way"/>
    <recurse type="way-relation"/>
  </union>
  <union into="_">
    <item set="_"/>
    <recurse type="relation-way"/>
  </union>
  <union into="_">
    <item set="_"/>
    <recurse into="x" type="relation-node"/>
    <recurse type="way-node"/>
  </union>
  <union into="_">
    <item set="_"/>
    <recurse type="relation-backwards"/>
    <recurse type="relation-backwards"/>
    <recurse type="relation-backwards"/>
    <recurse type="relation-backwards"/>
  </union>
  <print mode="meta"/>
</osm-script>
try it yourself in overpass-turbo
(
  node(50.746,7.154,50.748,7.157);
  rel(bn)->.x;
  way(bn);
  rel(bw);
);
(
  ._;
  way(r);
);
(
  ._;
  node(r)->.x;
  node(w);
);
(
  ._;
  rel(br);
  rel(br);
  rel(br);
  rel(br);
);
out meta;

Display result: OpenLayers map, JSON, XML.

Select region by polygon

In addition to bounding boxes, now also polygons can be used to cut out a region for download. A simple example is a part of my home town in Germany:

try it yourself in overpass-turbo
(
  node(poly:"50.7 7.1 50.7 7.12 50.71 7.11");
  <;
);
out meta;

Display result: XML, JSON

More general, the examples from above can be adapted to the polygon variant: Just replace the bbox condition by the polygon condition. The only restriction is that polygons can only be used as borders for nodes. Please use one of the various recurse statements to get ways and relations from it.

If you want to use a polygon like the output of rel2poly.pl as a boundary, you can convert it with the following bash script poly2request.sh:

#!/usr/bin/env bash
 
echo -n '(node(poly:"'
awk '{ if ($1 != "1" && $1 != "polygon" && $1 != "END") printf $2" "$1" "; }'
echo '");<;);out;'

Now you can get your download with e.g.

./poly2request.sh <polygon.txt >request.txt
wget --post-file=request.txt http://overpass-api.de/api/interpreter

Control output format

Print does what its name lets you expect: it prints the contents queried so far as returned data. Thus, almost every query ends with a print statement. For the sake of brevity, print has been renamed to out; in Overpass QL.

Degree of verbosity

Print exists in four different degrees of verbosity, which are specified by the mode attribute: body (default), skeleton, ids_only, and meta. Those are explained by the following examples, giving the relevant parts of the query and the result. The more concise the output is, the faster the query runs. For that reason, skeleton is used in this guide for the OpenLayers layers. meta is likely to be the best choice if you want to edit the data. If you are unsure what you need, try body first.

Normal (body)

body is the default mode: ids, child elements, and tags are printed. If you want the mode body, you can omit the mode attribute.

Overpass XML Overpass QL
try it yourself in overpass-turbo
<osm-script>
  <query type="node">
    <has-kv k="name" v="Gielgen"/>
    <has-kv k="place" v="suburb"/>
  </query>
  <print/>
</osm-script>
try it yourself in overpass-turbo
node
  ["name"="Gielgen"]
  ["place"="suburb"];
out;

Display result: OpenLayers map, JSON, XML.

Concise (skeleton)

The skeleton print mode is somewhat shorter: No tags are printed in this mode, only ids, child elements, and coordinates of nodes:

Overpass XML Overpass QL
try it yourself in overpass-turbo
<osm-script>
  <query type="node">
    <has-kv k="name" v="Gielgen"/>
    <has-kv k="place" v="suburb"/>
  </query>
  <print mode="skeleton"/>
</osm-script>
try it yourself in overpass-turbo
node
  ["name"="Gielgen"]
  ["place"="suburb"];
out skel;

Display result: OpenLayers map, JSON, XML.

Brief (ids_only)

ids_only is the shortest print mode; only ids are printed. ids_only is shortened to ids in Overpass QL. Note that this doesn't work with Open Layers because no coordinates are returned.

Overpass XML Overpass QL
try it yourself in overpass-turbo
<osm-script>
  <query type="node">
    <has-kv k="name" v="Gielgen"/>
    <has-kv k="place" v="suburb"/>
  </query>
  <print mode="ids_only"/>
</osm-script>
try it yourself in overpass-turbo
node
  ["name"="Gielgen"]
  ["place"="suburb"];
out ids;

Display result: OpenLayers map, JSON, XML.

Verbose (meta)

meta is the most complete mode. Beside child elements and tags, also the meta data (timestamp, version, changeset, user name and id) is printed:

Overpass XML Overpass QL
try it yourself in overpass-turbo
<osm-script>
  <query type="node">
    <has-kv k="name" v="Gielgen"/>
    <has-kv k="place" v="suburb"/>
  </query>
  <print mode="meta"/>
</osm-script>
try it yourself in overpass-turbo
node
  ["name"="Gielgen"]
  ["place"="suburb"];
out meta;

Display result: OpenLayers map, JSON, XML.

This meta data is, in particular, necessary in order to handle the result in JOSM.

order attribute

You can also change the order of the elements. By default, elements are ordered by their id (i.e., order="id"). You get faster results if you allow elements to be ordered by their location (i.e., order="quadtile", or qt in Overpass QL).

Overpass XML Overpass QL
try it yourself in overpass-turbo
<osm-script>
  <query type="node">
    <has-kv k="name" v="Gielgen"/>
    <has-kv k="place" v="suburb"/>
  </query>
  <print order="quadtile"/>
</osm-script>
try it yourself in overpass-turbo
node
  ["name"="Gielgen"]
  ["place"="suburb"];
out qt;

Display result: OpenLayers map, JSON, XML.

limit attribute

It is also possible to limit the number of printed elements:

Overpass XML Overpass QL
try it yourself in overpass-turbo
<osm-script>
  <query type="node">
    <has-kv k="name" v="Gielgen"/>
  </query>
  <print limit="2"/>
</osm-script>
try it yourself in overpass-turbo
node["name"="Gielgen"];
out 2;

Display result: OpenLayers map, JSON, XML.

This limits the output to at most two nodes.

Choose file format

You can get the result as JSON or as XML. By default, you get the data as XML. To get the result as JSON, just add a JSON request to the query header (before the first statement):

Overpass XML Overpass QL
link=http://overpass-turbo.eu/?Q=%3Cosm-script%20output%3D%22json%22%3E%0A%20%20%3Cquery%20type%3D%22node%22%3E%0A%20%20%20%20%3Chas-kv%20k%3D%22name%22%20v%3D%22Gielgen%22%2F%3E%0A%20%20%3C%has-kv k="name" v="Gielgen"/>     2Fquery%3E%0A%20%20%3Cprint%2F%3E%0A%3C%2Fosm-script%3E&C=50.73515;7.20519;14&R
<osm-script output="json">
  <query type="node">
    <has-kv k="name" v="Gielgen"/>
  </query>
  <print/>
</osm-script>
try it yourself in overpass-turbo
[out:json];
node["name"="Gielgen"];
out body;

Display result: OpenLayers map, JSON, XML.

Query by element id

If you want a specific id from the database, you can query for it. We give

  • an example for a node:
Overpass XML Overpass QL
try it yourself in overpass-turbo
<osm-script>
  <id-query ref="507464799" type="node"/>
  <print/>
</osm-script>
try it yourself in overpass-turbo
node(507464799);
out;

Display result: OpenLayers map, JSON, XML.

  • an example for a way:
Overpass XML Overpass QL
try it yourself in overpass-turbo
<osm-script>
  <id-query ref="24777894" type="way"/>
  <print/>
</osm-script>
try it yourself in overpass-turbo
way(24777894);
out;

Display result: OpenLayers map, JSON, XML.

  • an example for a relation:
Overpass XML Overpass QL
try it yourself in overpass-turbo
<osm-script>
  <id-query ref="1745069" type="relation"/>
  <print/>
</osm-script>
try it yourself in overpass-turbo
relation(1745069);
out;

Display result: OpenLayers map, JSON, XML.

Edit filtered data

If the OSM data are highly dense in a certain area then it becomes more and more difficult to do perform edits. By combining JOSM and Overpass API you can overcome this: The plugin mirrored_download simplifies the download of the necessary data. Working in this way comes close to the concept of "layers" in classical GIS systems. Caution: Editing this way requires more care than usual. Please read below.

As an example, we want to check which shops in Bonn already have a "wheelmap" tag and add it if applicable.

For this purpose we install in JOSM the plugin "mirrored_download" and as a wallpaper the standard OSM map in black/white. Then we download the filtered data.

Precautions

Editing in this way requires more diligence than usual: Changing a geometry might mess up an invisible object. Also, nodes can belong to not-downloaded ways, and editing could this way affect unknown ways. This problem otherwise only appears at the brim of the bounding box in JOSM. For these reasons: Please do neither delete nodes nor move them around. Changing tags or splitting and joining of ways is on the other hand safe, and this covers a couple of interesting editing scenarios.

Install mirrored_download

You need to do this and the following step only once because JOSM stores locally both settings and plugins.

Select "Edit > Preferences ...".

Select the power plug in the panel on the left.

Select "Download list"

Type "mirr" into the Search and select then the leftover entry "mirrored_download".

"OK". "Restart" and wait for the restart.

Install the background wallpaper

Select "Edit > Preferences ...".

Select "TMS/WMS", the lowest entry in the panel on the left.

Select from "Available default entries" the entry "OpenStreetMap (Mapnik Black & White)" and click "Activate", then "OK".

Select then "Imagery > OpenStreetMap (Mapnik Black & White)". You see a lighter grey. The real map will appear after we have chosen a bounding box in the next step. You can ignore the warning about misalignment because the OSM base map is by design the same way aligned as the data it is made from.

Download data

Select "File > Download from Overpass API".

Choose you desired bounding box from the "Slippy Map". You can zoom out and in with the mouse wheel. You can pan around by keeping the right mouse button pressed and dragging. You can choose a bounding box by dragging with pressed left mouse button.

Paste the following query to "Overpass query". We use here:

( node[shop];
  way[shop];>;
  rel[shop];>;);
(._;rel(bn););
(._;rel(bw););
(._;rel(br););
out meta;

The syntax is explained in the next section below. The bounding box will be set automatically by JOSM. The crucial thing is that we download here also relations and refer to the downloaded objects such that JOSM can take care of them when we edit.

Click "Download" and wait until the download has completed. During the tests this has taken 5 to 15 seconds.

Josm shops in bonn.png

Please keep the precautions in mind. Or use it as a flexible read-only view for OSM objects of chosen category.

More useful queries

The entire street grid:

( way[highway];>;);
(._;rel(bn););
(._;rel(bw););
(._;rel(br););
out meta;

All public transport related data:

( way[highway];>;
  way[railway];>;
  node[public_transport];
  node[highway=bus_stop];);
(._;rel(bn););
(._;rel(bw););
(._;rel(br););
out meta;

Language reference

This section has moved to the language reference.

FAQ

See Overpass_API/FAQ#Language