Overpass API/Overpass QL and User:Xxzme/Overpass QL: Difference between pages

{{Languages|Overpass API/Overpass QL}}{{Overpassapi}}

'''Overpass QL''' (short for "Overpass Query Language") is the second query language created for the [[Overpass API]], the first being [[Overpass_API/Language_Guide#The Overpass API languages|Overpass XML]]. Overpass QL is a {{Wikipedia|en|Procedural programming|procedural|text=no}}, {{Wikipedia|en|Imperative programming|imperative|text=no}} programming language written with a {{Wikipedia|en|C syntax|C style syntax|text=no}}.

This wiki page intends to be a complete technical reference to the structure of Overpass QL. For a collection of '''practical examples''', see also the wiki page [[Overpass API/Overpass API by Example|Overpass API by Example]]. People without a technical background may find that page more accessible.

{{Ambox

| type = notice

| text = The features supported by an Overpass QL parser are defined by the [[Overpass API/versions|version of the Overpass API]] running on the server queried. Be sure that the [[Overpass_API#Public_Overpass_API_instances|Overpass API server you query]] has a new enough API version to support the features you wish to use.

Where known, a feature's minimum Overpass API version number is specified.

}}

== Language overview ==

=== Statements ===

Overpass QL source code is divided into ''statements,'' and every statement ends with a semicolon <code>;</code>. Statements are executed sequentially by a ''{{Wikipedia|en|Process (computing)|process|text=no}}'', and each statement run changes the process's ''execution state.''

=== Execution state ===

The Overpass QL ''execution state'' consists of:

* the default ''set'' <code>_</code> (a single underscore)

* other named sets, if created by the user

* a {{Wikipedia|en|Stack (abstract_data_type)|stack|text=no}}, during the execution of Overpass QL ''block statements''

=== Sets ===

Overpass QL manipulates ''sets''. Statements write their results into sets, and sets are then read by subsequent statements as input. An Overpass QL set can contain any combination of (and any number of) OpenStreetMap [[Node|nodes]], [[Way|ways]], [[Relation|relations]], and [[area]] [[elements]].

Unless you specify a ''named set'' as an input or result, all input is implicitly read from (and all results are written to) the default set named <code>_</code> (a single underscore). Once a new result is (implicitly or explicitly) assigned to an existing set, its previous contents will be replaced and are no longer available. Overpass QL sets always have global {{Wikipedia|en|Scope (computer_science)|scope (visibility)|text=no}}.

For example:

<syntaxhighlight lang="cpp">

node[name="Foo"];

</syntaxhighlight>

implicitly writes the result of the [[Tags|tag]] query <code>name="Foo"</code> to the default set <code>_</code>, overwriting any previous contents with this result. A result can be written to a specific set using the <code>-></code> syntax, when that set name is prefixed with <code>.</code>. The statement above is thus equivalent to:

<syntaxhighlight lang="cpp">

node[name="Foo"]->._;

</syntaxhighlight>

Similarly, this statement:

<syntaxhighlight lang="cpp">

(

node[name="Foo"];

node[name="Bar"];

);

</syntaxhighlight>

combines the results of two tag queries with a ''union statement'', then sends that result to the default set <code>_</code>. It is equivalent to:

<syntaxhighlight lang="cpp">

(

node[name="Foo"];

node[name="Bar"];

)->._;

</syntaxhighlight>

To write elements to a named set, again use the <code>-></code> syntax, followed by the set name. For example, this query:

<syntaxhighlight lang="cpp">

(node[name="Foo"];)->.a;

</syntaxhighlight>

will write all node elements with the tag <code>name=Foo</code> into the named set <code>a</code>. After this query, you have now 2 sets, the set <code>a</code>, with only the node elements, and the set <code>_</code>, unchanged.

Set names may consist of letters, digits, and the underscore; however, they must not start with a digit.

To read elements from a set, append <code>.</code> and the set name to the command.

<syntaxhighlight lang="cpp">

node.a[amenity=foo];

</syntaxhighlight>

will return all nodes in the named set <code>a</code> that have the [[key]] <code>amenity</code> with the [[value]] <code>foo</code>.

=== Language structure ===

There are several different types of Overpass QL ''statements''. They are grouped into:

* ''Settings,'' which are optional, global variables, set in the first statement of the query. Examples of ''settings'' are the server timeout for the Overpass API server, and the output format of the Overpass QL query.

* ''Block statements'': Block statements group Overpass QL statements together, to enable {{Wikipedia|en|Logical disjunction|disjunctions (truth tests)|text=no}}, as well as loops.

* ''Standalone queries'': These are complete statements on their own. They may perform functions such as querying the Overpass API server to create a set; manipulating the contents of an existing set; or sending the end results of a query to an output location. Standalone queries are themselves comprised of smaller Overpass QL language components, such as evaluators, filters, and operators.

=== Brackets ===

QL syntax uses ''round brackets'' (), ''square brackets'' [] and ''curly brackets'' {}. This documentation page uses the term ''brackets'' for ''square brackets''. See also [https://en.wikipedia.org/wiki/Bracket Wikipedia] for nomenclature.

== Settings ==

Overpass QL ''settings'' must be declared in the first uncommented statement of the Overpass QL source code. Settings cannot be declared in multiple statements.

Settings declarations are enclosed in brackets <code>[]</code>. A colon <code>:</code> appears between the setting name and the value or values to be set. The settings statement must be terminated with a semicolon <code>;</code>.<syntaxhighlight lang="cpp">

// This is a typical settings declaration line

// on an Overpass Turbo server

[out:json][timeout:25];

</syntaxhighlight>

=== ''timeout:'' ===

The ''timeout:'' setting has one parameter, a non-negative integer. Default value is ''180''.

This parameter indicates the maximum allowed runtime for the query in seconds, as expected by the user. If the query runs longer than this time, the server may abort the query with a timeout. The second effect is, the higher this value, the more probably the server rejects the query before executing it.

So, if you send a really complex big query, prefix it with a higher value; e.g., "3600" for an hour. And ensure that your client is patient enough to not abort due to a timeout in itself.

Example:

<syntaxhighlight lang="cpp">

[timeout:180]

</syntaxhighlight>

=== Element limit (''maxsize:'') ===

The ''maxsize:'' setting has one parameter, a non-negative integer. Default value is ''536870912'' (512 MB).

This parameter indicates the maximum allowed memory for the query in bytes RAM on the server, as expected by the user. If the query needs more RAM than this value, the server may abort the query with a memory exhaustion. The second effect is, the higher this value, the more probably the server rejects the query before executing it.

So, if you send a really complex big query, prefix it with a higher value; e.g., "1073741824" for a gigabyte. The maximum value highly depends on the current server load, e.g. requests for 2GB will likely be rejected during peak hours, as they don't fit into the overall resource management. Technically speaking, maxsize is treated as a 64bit signed number.

Example:

<syntaxhighlight lang="cpp">

[maxsize:1073741824]

</syntaxhighlight>

'''Important notice''': Recently, a new mechanism was introduced to abort queries exceeding 2 GB of memory. This exact size of this limit is still under discussion and might change over time.

If you experience error messages like "runtime error: Query run out of memory using about 2048 MB of RAM.", be sure to read [http://permalink.gmane.org/gmane.comp.gis.openstreetmap.overpass/237 this thread] as well.

=== Output format (''out:'') ===

<small>The ''out:'' global setting is unrelated to the ''out'' statement. Syntax should not be mixed.</small>

The ''out'' setting defines the output format used to return OSM data. It can take one of the five values; default value is ''xml'':

*''xml''

*''json'' <small> ''(not to be confused with geoJSON)'' </small>

*''csv''

*''custom''

*''popup''

Example:

<syntaxhighlight lang="cpp">

[out:json]

</syntaxhighlight>

==== CSV output mode ====

CSV output format returns OSM data as [[wikipedia:en:Delimiter-separated values|csv document]], which can be directly opened in tools like LibreOffice. It requires additional configuration parameters to define a list of fields to display, as well as two optional parameters for adding/removing the CSV header line and changing the column separator.

Format:

<syntaxhighlight lang="cpp">

[out:csv( fieldname_1 [,fieldname_n ...] [; csv-headerline [; csv-separator-character ] ] )]

</syntaxhighlight>

Notes:

* Numeric values (coordinates, ids) uses no thousands separator, and uses the English dot (.) for the decimal separator (in geometric coordinates).

* No escaping is made on for specific characters in string values. This will change with release 0.7.55.

* The default separator character (tab) should still allow most of the time to parse the tabular data without missing/broken/misaligned columns.

* These CSV defaults may still not match what your spreadsheet application expects (notably the decimal separator in non-English versions) if you open the CSV file directly with your application, and data could seem corrupted, or unparsable: instead, import the data in a text-only column of a new spreadsheet, and convert it to tabular data inside that application using your own settings; or use an external filter script to convert the file before opening it.

===== Simple example =====

<nowiki>[out:csv(name)]</nowiki> will output just name tag. See below for more complicated examples.

===== List of field names =====

Besides normal OSM field names (tags), special fields are available for each element in the result set to output. Note that all of these special field names need to be prefixed by two colons <code>::</code>.

{| class="wikitable"

|-

! Special field name

! Description

|-

|<code>::id</code>

| OSM Object ID

|-

|<code>::type</code>

| OSM Object type: node, way, relation

|-

|<code>::otype</code>

| OSM Object as numeric value

|-

|<code>::lat</code>

| Latitude (available for nodes, or in ''out center'' mode)

|-

|<code>::lon</code>

| Longitude (available for nodes, or in ''out center'' mode)

|-

| colspan="2" | The following meta information fields are '''only''' available if <code>out meta;</code> is used to output OSM elements.

|-

|<code>::version</code>

| OSM object's version number

|-

|<code>::timestamp</code>

| Last changed timestamp of an OSM object

|-

|<code>::changeset</code>

| Changeset in which the object was changed

|-

|<code>::uid</code>

| OSM User id

|-

|<code>::user</code>

| OSM User name

|-

| colspan="2" |The following meta information fields are '''only''' available if <code>out count;</code> is used to output OSM elements.

|-

|<code>::count</code>

|Returns total number of objects (nodes, ways, relations and areas) in inputset

|-

|<code>::count:nodes</code>

|Returns number of nodes in inputset

|-

|<code>::count:ways</code>

|Returns number of ways in inputset

|-

|<code>::count:relations</code>

|Returns number of relations in inputset

|-

|<code>::count:areas</code>

|Returns number of areas in inputset

|}

Example:

<syntaxhighlight lang="c">

[out:csv(

::"id", amenity, name, operator, opening_hours, "contact:website", "contact:phone", brand, dispensing, lastcheck

)];

</syntaxhighlight>

Railway stations in Bonn:

{{OverpassTurboExample|loc=50.51201;8.09641;12|query=

[out:csv(::id,::type,"name")];

area[name="Bonn"];

nwr(area)[railway=station];

out;

}}

===== CSV header line =====

The presence or absence of a header line can be controlled by the first optional parameter, which can be added right after the field list separated by semicolon. Possible values include ''true'' and ''false''. Default value is ''true''.

<syntaxhighlight lang="c">

[out:csv(

::"id", amenity, name, operator, opening_hours, "contact:website", "contact:phone", brand, dispensing, lastcheck;

false

)];

</syntaxhighlight>

===== CSV separator character =====

By default all fields are separated by a tab character ("\t"). However, this setting can be changed via the second optional parameter. In the following example all output fields will be separated by a pipe ("|") character instead

<syntaxhighlight lang="c">

[out:csv(

::"id", amenity, name, operator, opening_hours, "contact:website", "contact:phone", brand, dispensing, lastcheck;

true; "|"

)];

</syntaxhighlight>

; Checking CSV output for complete data

Unlike other output modes like XML and JSON, there's currently no indication of any error message at all. An empty result (or a result with just a header line) might indicate either that nothing was found or that the query was aborted due to timeout or some other more serious error condition. One way to work around this is to introduce an additional counter, which summarizes the previous query result and is always put as the very last output statement of a query.

The following example extends the previously shown list of all railway stations in Bonn by an additional output statement returning an additional aggregated row in the CSV, describing a pseudo-element with type "count" and whose value will be in the last requested <code>::count</code> column (whose value remains empty for normal data rows):

<syntaxhighlight lang="cpp">

[out:csv(::type,::id,"name",::count)];

area[name="Bonn"]->.a;

( node(area.a)[railway=station];

way(area.a)[railway=station];

rel(area.a)[railway=station];

);

out;

out count;

</syntaxhighlight>

The output now includes an additional column with type <code>::count</code> and an indication of how many total elements are contained in the current resultset: 5. If the final count line is missing or the total number differs, you know for sure that something went wrong and the query results are incomplete/inconsistent.

<pre>

@type @id name @count

node 26945519 Bonn-Oberkassel

node 1271017705 Bonn-Beuel

node 2428355974 Bonn-Bad Godesberg

node 2713060210 Bonn Hauptbahnhof

node 3400717493 Bonn-Mehlem

count 0 5

</pre>

The values ''custom'' and ''popup'' also require further configuration. Please see details in the [http://dev.overpass-api.de/output_formats.html output formats documentation].

=== Global bounding box (''bbox'') ===

The '[[#Bounding box|bounding box]]' defines the map area that the query will include. The global ''bbox'' setting can be used to define a bounding box and then this is implicitly used in all statements (unless a statement specifies a different explicit bbox). If no ''bbox'' is specified the default value is "the entire world".

In a standard Overpass QL program, a bounding box is constructed with two decimal degree coordinate pairs in [http://en.wikipedia.org/wiki/ISO_6709 ISO 6709 standard order and format], and each value is separated with a comma. The values are, in order: ''southern-most latitude'', ''western-most longitude'', ''northern-most latitude'', ''eastern-most longitude.''

<syntaxhighlight lang="cpp" line="1">

[bbox:south,west,north,east]

// A bbox framing the German city of Bonn

[bbox:50.6,7.0,50.8,7.3]

// A bbox framing part of Rio de Janeiro, Brazil

[bbox:-23,-43.3,-22.8,-43.1]

</syntaxhighlight>

'''Note:''' When a query is URL encoded as the value of the <code>data=</code> parameter, a bounding box can also be appended as a separate <code>bbox</code> variable. When used this way, the order is reversed, ''lon-lat''. (This is the common order for [http://openlayers.org/ OpenLayers] and other frameworks.)

The Bonn example, above, as used in a URL encoding:

<syntaxhighlight lang="http">

/api/interpreter?data=[bbox];node[amenity=post_box];out;&bbox=7.0,50.6,7.3,50.8

</syntaxhighlight>

This finds all post boxes roughly in Bonn, Germany.

=== Date ===

''date'' is a global setting which modifies an Overpass QL query to examine [[Attic Data|attic data]], and return results based on the OpenStreetMap database as of the date specified. This setting can be useful, for example, to reconstruct data that has been vandalized, or simply to view an object as it existed in the database at some point in the past.

It consists of the identifier <code>date</code>, followed by <code>:</code> and then an OpenStreetMap database standard [https://en.wikipedia.org/wiki/ISO_8601 ISO 8601] date enclosed in quotes, in the format <code>YYYY-MM-DDThh:mm:ssZ</code>.

This example queries the state of the database on 28th October 2015 at 19:20:00 UTC:<syntaxhighlight lang="cpp" line="1">

[date:"2015-10-28T19:20:00Z"]

</syntaxhighlight>

There is no attic data in the OpenStreetMap database with a date earlier than <code>2012-09-12T06:55:00Z</code> (1347432900 in epoch seconds). This date corresponds to the first change included in the [[ODbL]] compliant planet file. Use of an earlier <code>date</code> setting is technically possible, but doing so will always return the database state as of <code>2012-09-12T06:55:00Z</code>.

=== Difference between two dates (''diff'') ===

The ''diff'' setting lets the database determine the difference of two queries at different points in time. This is useful for example to deltas for database extracts.

It consists of the identifier <code>diff</code>, followed by <code>:</code> , an OpenStreetMap database standard [https://en.wikipedia.org/wiki/ISO_8601 ISO 8601] date enclosed in quotes, in the format <code>YYYY-MM-DDThh:mm:ssZ</code> , and optionally a comma and a second date which defaults to the current date ("now").

Example:

<syntaxhighlight lang="cpp" line="1">

[diff:"2012-09-14T15:00:00Z"]

</syntaxhighlight>

This processes the rest of the query as if it were posed on 14th September 2012 at 15:00, then processes the same query with current data and finally outputs the difference between the two results.

<syntaxhighlight lang="cpp" line="1">

[diff:"2012-09-14T15:00:00Z","2012-09-21T15:00:00Z"]

</syntaxhighlight>

Does basically the same, but compares the state of 14th September with the state of 21st September.

Note that the output does not include any intermediate versions, which might exist between the first and the last timestamp, i.e. if there are several changes on an object, only the last version in the given timeframe is returned.

=== Augmented-difference between two dates (''adiff'') ===

The ''adiff'' does basically the same as ''diff'' , but for all elements that aren't contained in the newer result, it is indicated what happened to them.

If an element has been deleted, then its last deletion date is printed and the indication "visible=false". If an element has changed such that it no longer matches the query then its last change date is printed and the indication "visible=true".

For more information see: [[Overpass_API/Augmented_Diffs|Augmented Diffs]].

== Block statements ==

=== Union ===

The ''union'' block statement is written as a pair of parentheses. Inside the ''union'', any sequence of statements can be placed, including nested ''union'' and ''foreach'' statements. Note that the square brackets '''[ ... ]''' shown below indicate an optional part of the syntax and are not to be typed literally.

<syntaxhighlight lang="cpp">

(statement_1; statement_2; …)[->.result_set];

</syntaxhighlight>

The ''union'' block statement takes no input set. It produces a result set which is the union of the result sets of all sub-statements, regardless of whether a sub-statement has a redirected result set or not.

Example:

<syntaxhighlight lang="cpp">

(node[name="Foo"]; way[name="Foo"];);

</syntaxhighlight>

The first statement collects all nodes that have a name tag "Foo"; the second statement collects all ways that have a name tag "Foo". After the union statement, the result set is the union of the result sets of both statements.

The result set of the union statement can be redirected with the usual postfix notation.

Example:

<syntaxhighlight lang="cpp">

(node[name="Foo"]; way[name="Foo"];)->.a;

</syntaxhighlight>

This is the same as the preceding example, but the result is written into the variable ''a''.

'''Limitation:''' Note that ''foreach'' and ''print'' statements cannot be sub-elements of element ''union''.

=== Difference ===

The ''difference'' block statement is written as a pair of parentheses. Inside the ''difference'' statement, exactly two statements must be placed, separated by a minus sign. Note that the square brackets '''[ ... ]''' shown below indicate an optional part of the syntax and are not to be typed literally.

<syntaxhighlight lang="cpp">

(statement_1; - statement_2;)[->.result_set];

</syntaxhighlight>

The ''difference'' block statement takes no input set. It produces a result set which contains all elements that are result of the first sub-statement and not contained in the result of the second sub-statement.

Example:

<syntaxhighlight lang="cpp">

(node[name="Foo"]; - node(50.0,7.0,51.0,8.0););

</syntaxhighlight>

This collects all nodes that have a name tag "Foo" but are not inside the given bounding box.

The result set of the difference statement can be redirected with the usual postfix notation.

Example:

<syntaxhighlight lang="cpp">

(node[name="Foo"]; - node(50.0,7.0,51.0,8.0);)->.a;

</syntaxhighlight>

This is the same as the preceding example, but the result is written into the variable ''a''.

=== Intersection ===

It is also possible to produce a set of elements that appear in both of two input sets, i.e. elements that are part of both sets. This is described below in [[#By_input_set_(.setname)|By input set (.setname)]]:

<syntaxhighlight lang="cpp">

node.a.b;

</syntaxhighlight>

This is not a block statement, but is listed here because of its close relation to the difference statement described above.

=== The block statement ''if'' ===

''since v0.7.55''

The block statement ''if'' executes its substatements only if its condition evaluates to boolean true. This allows e.g. to try more loosely search conditions if stricter search conditions did not deliver a result.

The statement does not directly interact with any sets.

The base syntax is

if (<Evaluator>)

{

<List of Substatements>

}

resp.

if (<Evaluator>)

{

<List of Substatements>

}

else

{

<List of Substatements>

}

where <Evaluator> is an evaluator and <List of Substatements> is a list of substatements.

=== For-each loop (''foreach'') ===

''since v0.7.51''

The ''foreach'' block statement is written as the keyword ''foreach'', followed by a pair of curly braces. Any sequence of statements can be placed between these braces, including nested ''union'' and ''foreach'' statements.

The ''foreach'' block statement takes an input set and produces no result set. The ''foreach'' statement loops over the content of the input set, once for every element in the input set.

Example:<!--syntax pretty printed with whitespaces for easier understanding, see below-->

<syntaxhighlight lang="cpp">

way[name="Foo"];

foreach

{

(

._;

>;

);

out;

}

</syntaxhighlight>

For each way that has a name tag with value "Foo", this prints the nodes that belong to this way immediately followed by the way itself. In detail, the result set of ''way[name="Foo"]'' is taken as the input set. Then, for each element in this input set, the loop body is executed once. Inside the loop body, the union of the element and its nodes is taken. This union is then printed.

Note that during execution, each printed subset in an iteration is independent of subsets printed in other iterations, possibly resulting in duplicate objects in the global output (no union is computed by the ''out'' statement within the loop).

The input set of the foreach statement can be taken from a variable with the usual postfix notation:

Example:

<syntaxhighlight lang="cpp">

foreach.a(...);

</syntaxhighlight>

This loops over the content of set ''a'' instead of the default set "_".

The name of the variable to put the loop element into can also be chosen by adding a postfix immediately before the opening parenthesis.

Example:

<syntaxhighlight lang="cpp">

foreach->.b(...);

</syntaxhighlight>

This puts the element to loop over into the variable ''b''. Without it, the ''foreach'' statement does not put the elements into any set.

Example for both input and loop set changed:

<syntaxhighlight lang="cpp">

foreach.a->.b(...);

</syntaxhighlight>

Note that the input set can't be altered by the loop. Any updates to the set will be saved for further usage, but this will not alter the number of iterations.

=== The block statement ''for'' ===

''since v0.7.55''

The block statement ''for'' divides its input into subsets and executes all the statements in the loop body once for every subset.

The input set is broken down as follows: For each element the given evaluator is evaluated and elements with the same value are grouped together. At the beginning of each loop execution, the output set is filled with the relevant subset.

The base syntax is

for (<Evaluator>)

{

<List of Substatements>

}

The input and output set can be specified between ''for'' and the opening parenthesis,

i.e. you set the input set

for.<Name of Input Set> (<Evaluator>)

{

<List of Substatements>

}

or the output set

for->.<Name of Output Set> (<Evaluator>)

{

<List of Substatements>

}

or both

for.<Name of Input Set>->.<Name of Output Set> (<Evaluator>)

{

<List of Substatements>

}

Within the loop, the value of the evaluator is available via the property ''val'' of the output set. I.e., with

<Output Set>.val

you can access the value of the expression for this loop.

With the special evaluator ''keys()'', one can loop over all the keys that exist in the subset.

The respective subset for each key are the elements that have this key set.

Unlike for a usual evaluator, the sets are not mutually distinct in that case.

=== The block statement ''complete'' ===

''since v0.7.55''

The block statement ''complete'' loops through its substatements until the results of the loop stabilize.

This allows to track a group of loosely or tightly connected elements like all sections of a way with the same name or a system of tributary rivers.

The statement delivers the accumulated elements in its output set both at the beginning of each loop execution and as output of the whole statement.

The elements are accumulated from the input set before entering the loop and again from the input set at the end of the loop.

If the input set contains extra elements then the loop is executed again.

The base syntax is

complete

{

<List of Substatements>

}

where <List of Substatements> is a list of substatements.

The maximum number of loops defaults to 4096.

This value can be changed to any value between 1 and 1048576 for this loop.

To do so, put the desired value in parentheses after the "complete" keyword:

complete(<Number>)

{

<List of Substatements>

}

The input and output set can be specified between complete and the opening parenthesis; i.e. you set the input set

complete.<Name of Input Set>

{

<List of Substatements>

}

or the output set

complete->.<Name of Output Set>

{

<List of Substatements>

}

or both

complete.<Name of Input Set>->.<Name of Output Set>

{

<List of Substatements>

}

resp.

complete(<Number>).<Name of Input Set>->.<Name of Output Set>

{

<List of Substatements>

}

=== The block statement ''retro'' ===

''since v0.7.55''

The block statement ''retro'' executes its substatements for the date given in the evaluator.

It is currently undefined whether the content of variables from outside the block is available within the block and vice versa.

Future versions may transfer only derived elements, keep the environments completely apart, or morph elements from one point in time to the other.

The base syntax is<syntaxhighlight lang="cpp">

retro (<Evaluator>)

{

<List of Substatements>

}

</syntaxhighlight>where <Evaluator> is an evaluator and <List of Substatements> is a list of substatements.

=== The block statement ''compare'' ===

''since v0.7.55''

The statement ''compare'' computes the diff of the data of two timestamps.

That diff can consist of any elements as well as only those with specific properties.

The statement can have a block of substatements.

The block of substatements is executed after computing the diff in the second run, once for the old timestamp and then again for the new timestamp.

This allows to do extra computations based on the diff results.

The statement can only be used in diff mode.

In other modes its behaviour is undefined, and in future versions it might be a syntax error to have it elsewhere.

In the first run of a diff query it returns an empty set.

In the second run of a diff query it returns the difference of the elements.

If the statement gets an evaluator as argument then only those elements that have different values on both timestamps are returned.

If the element does not exist on one of the timestamps then its value is regarded as the empty string.

Currently, the only purpose of such a difference is to feed it into an output statement.

The base syntax is

compare();

In addition, an input and/or output set can be specified:

.<Set> compare()->.<Set>;

With the evaluator, the syntax becomes

compare(delta:<Evaluator>);

resp.

.<Set> compare->.<Set>(delta:<Evaluator>);

In all syntax variants a block of substatements can be attached:

compare()

{

<List of Substatements>

};

resp.

.<Set> compare(delta:<Evaluator>)->.<Set>;

{

<List of Substatements>

};

== Standalone statements ==

=== out ===

<small>The ''out'' statement is unrelated to the ''out:'' global setting. Syntax should not be mixed.</small>

The ''out'' statement outputs the contents of a set. It is ''almost always used'' in any Overpass QL query.

<code>out count;</code> is a statement which prints ''only'' the [[#Statistical Count|total ''counts'' of elements]] in the input set by type (nodes, ways, relations, areas). It cannot be combined with anything else.

The simplest form of the out statement has several implied defaults.

<syntaxhighlight lang="cpp">

out; // Simplest form of the out statement

._ out body; // Identical meaning to the above

</syntaxhighlight>

The default input set <code>_</code> can be overridden by prepending a period and a named set name to the out statement.

<syntaxhighlight lang="cpp">

.mystuff out; // Output the named set 'mystuff'

</syntaxhighlight>

The ''out'' statement can be configured with an arbitrary number of parameters that are appended, separated by whitespace, between the word ''out'' and the semicolon.

Allowed values, in any order, are:

* One of the following for the '''degree of verbosity''' of the output; the default is <code>out body</code>:

**<code>out ids</code>: Print only the ids of the elements in the set.

** <code>out skel</code>: Print the minimum information necessary for geometry:

***for nodes: id and coordinates

***for ways: id and the ids of its member nodes

***for relations: id of the relation, and the id, type, and role of all of its members.

** <code>out body</code>: Print all information necessary to use the data. These are also tags for all elements and the roles for relation members.

** <code>out tags</code>: Print only ids and tags for each element and not coordinates or members.

** <code>out meta</code>: Print everything known about the elements. meta includes everything output by body for each OSM element, as well as the version, changeset id, timestamp, and the user data of the user that last touched the object. Derived elements' metadata attributes are also missing for derived elements.

{| class="wikitable"

!

!Own object type

!Own object ID

!For nodes:

Own coordinates

!For ways:

IDs of member nodes

!For relations:

ID, type, role of members

!Own tags

!Timestamp, Version, Changeset, User, User ID

|-

!<code>out ids</code>

|{{yes}}

|{{yes}}

|

|

|

|

|

|-

!<code>out skel</code>

|{{yes}}

|{{yes}}

|{{yes}}

|{{yes}}

|{{yes}}

|

|

|-

!<code>out body</code>

|{{yes}}

|{{yes}}

|{{yes}}

|{{yes}}

|{{yes}}

|{{yes}}

|

|-

!<code>out tags</code>

|{{yes}}

|{{yes}}

|

|

|

|{{yes}}

|

|-

!<code>out meta</code>

|{{yes}}

|{{yes}}

|{{yes}}

|{{yes}}

|{{yes}}

|{{yes}}

|{{yes}}

|}

* The '''modificator''' <code>noids</code> lets all ids to be omitted from the statement. (Note: As of 2021-12-28, there is a [https://github.com/tyrasd/overpass-turbo/issues/547 bug in Overpass Turbo] preventing the usage of noids.)

* One of the following '''modificators for geolocated information'''; default is to print none:

**<code>geom</code>: Add the full geometry to each object. This adds coordinates to each node, to each node member of a way or relation, and it adds a sequence of "nd" members with coordinates to all relations.

** <code>bb</code>: Adds only the bounding box of each element to the element. For nodes this is equivalent to <code>geom</code>. For ways it is the enclosing bounding box of all nodes. For relations it is the enclosing bounding box of all node and way members, relations as members have no effect.

** <code>center</code>: This adds only the centre of the above mentioned bounding box to ways and relations. Note: The center point is not guaranteed to lie inside the polygon ([http://overpass-turbo.eu/s/4rr example]).

* A '''bounding box''' in the format <code>(south,west,north,east)</code> (normally used with the ''geom'' verbosity type). In this case, only elements whose coordinates are inside this bounding box are produced. For way segments, the first or last coordinates outside this bounding box are also produced to allow for properly formed segments (this restriction has no effect on derived elements without any geometry).

* One of the following for the '''sort order''' can be added:

**<code>asc</code>: Sort by object id (default).

** <code>qt</code>: Sort by quadtile index; this is roughly geographical and significantly faster than order by ids (derived elements generated by ''make'' or ''convert'' statements without any geometry will be grouped separately, only sorted by id).

* A non-negative integer, which '''limits the output''' to a maximum of the given number. If not specified, the entire set will be output. For instance, <code>out 12;</code> will output at most 12 features.

=== Item ===

The ''item'' standalone query consists only of an input set prefix.

It takes the input set specified by its prefix. This is in particular useful for union statements: it reproduces its input set as (part of the) result of the union statement.

The most common usage is the usage with the default input set, <code>_</code>, as shown below.

<syntaxhighlight lang="cpp">

._;

</syntaxhighlight>

The following union statement will join all items in the default input set with the default input set's [[Overpass API/Overpass QL#Recurse down (%3E)|recurse down]] result. It will then output the result back to the default input set, overwriting it.

<syntaxhighlight lang="cpp">

(._; >;);

</syntaxhighlight>

But of course other sets are possible too:

<syntaxhighlight lang="cpp">

.a;

</syntaxhighlight>

In the context of a union statement:

<syntaxhighlight lang="cpp">

(.a; .a >;);

</syntaxhighlight>

Note: Subsequent statements in a union statement are not impacted by the ''item'' statement. In particular, <code>.a;</code> does not add the contents of the input set to <code>_</code>, the default item set.

The item statement can also be used as a filter.

=== Recurse up (''<'') ===

The ''recurse up'' standalone query is written as a single less than symbol, "<".

It takes an input set. It produces a result set. Its result set is composed of:

* all '''ways''' that have a '''node''' which appears in the '''input''' set; plus

* all '''relations''' that have a '''node or way''' which appears in the '''input''' set; plus

* all '''relations''' that have a '''way''' which appears in the '''result''' set

Example:

<syntaxhighlight lang="cpp">

<;

</syntaxhighlight>

The input set of the recurse up statement can be chosen with the usual prefix notation:

<syntaxhighlight lang="cpp">

.a <;

</syntaxhighlight>

The result set of the recurse up statement can be redirected with the usual postfix notation:

<syntaxhighlight lang="cpp">

< ->.b;

</syntaxhighlight>

Of course, you can also change both:

<syntaxhighlight lang="cpp">

.a < ->.b;

</syntaxhighlight>

=== Recurse up relations (''<<'') ===

The ''recurse up relations'' standalone statement has a similar syntax to the recurse-up statement, but it is written as a double less than.

In particular, you can change the input and/or result set with the same notation as for the ''recurse up'' standalone query.

In addition to the recurse-up results, it continues to follow backlinks onto the found relations until it contains all relations that point to an object in the input or result set.

Precisely, the ''recurse up relations'' standalone query returns the transitive and reflexive closure of membership backwards.

'''Be aware:''' Done on a node or a way, it will return the parents of that node<ref>[https://overpass-turbo.eu/s/UDY An example of expected behaviour when using << on a node]</ref> or way<ref>[https://overpass-turbo.eu/s/UE0 An example of expected behaviour when using << on a way]</ref> (as expected). Done on a relation, it will return '''both''' the relation itself and its parents<ref>[https://overpass-turbo.eu/s/1D6y An example of UNEXPECTED behaviour when using << on a relation]</ref>.

If you want the parents only, you can use: <code>rel._ -> .a; (.a <<; - rel.a;);</code> instead<ref>[https://overpass-turbo.eu/s/1D6C An example of a successful mitigation against the unexpected behavior when using << on a relation]</ref>. The simpler <s><code>(<<; - rel._;);</code></s> would return an empty result for some relations<ref>[https://overpass-turbo.eu/s/1D6A An example of an unsuccessful mitigation against the unexpected behavior when using << on a relation]</ref>.

Syntax:

<syntaxhighlight lang="cpp">

<<;

</syntaxhighlight>

=== Recurse down (''>'') ===

The ''recurse down'' standalone query is written as a single greater than.

It takes an input set. It produces a result set. Its result set is composed of:

* all '''nodes''' that are part of a '''way''' which appears in the '''input''' set; plus

* all '''nodes and ways''' that are members of a '''relation''' which appears in the '''input''' set; plus

* all '''nodes''' that are part of a '''way''' which appears in the '''result''' set

In particular, you can change the input and/or result set with the same notation as for the ''recurse up'' standalone query.

Example:

<syntaxhighlight lang="cpp">

>;

</syntaxhighlight>

=== Recurse down relations (''>>'') ===

The ''recurse down relations'' statement has a similar syntax to the recurse down statement,

but it is written as a double greater than.

In particular, you can change the input and/or result set with the same notation as for the recurse-down standalone query.

It continues to follow the membership links including nodes in ways until for every object in its input or result set all the members of that object are in the result set as well.

Precisely, the ''recurse down relations'' statement returns the transitive and reflexive closure of membership.

Syntax:

<syntaxhighlight lang="cpp">

>>;

</syntaxhighlight>

=== Query for areas (''is_in'') ===

The standalone query ''is_in'' returns the areas and closed ways that cover

* the given coordinates (when specified) or

* one or more nodes from the input set (when no coordinates are specified).

It takes either an input set or a coordinate and produces a result set. The results are all areas which contain at least one of the nodes from the input set or the specified coordinate.

''is_in'' cannot be directly used with any of the Overpass QL filters. For filtering the ''is_in'' result, a further query is needed (see below): the [square brackets] shown below, indicate optional parts and are not part of the syntax to type.

<syntaxhighlight lang="cpp">

[.input_set] is_in [-> .result_set];

is_in(latitude, longitude) [-> .result_set];

</syntaxhighlight>

In its shortest form, it takes its input set as the locations to search for. Example:

<syntaxhighlight lang="cpp">

is_in;

</syntaxhighlight>

The input set can be chosen with the usual prefix notation:

<syntaxhighlight lang="cpp">

.a is_in;

</syntaxhighlight>

The result set can be redirected with the usual postfix notation:

<syntaxhighlight lang="cpp">

is_in->.b;

</syntaxhighlight>

Of course, you can also change both:

<syntaxhighlight lang="cpp">

.a is_in->.b;

</syntaxhighlight>

Instead of taking existing nodes you can also specify coordinates with two floating point numbers, divided by a comma. They are interpreted as latitude, longitude. In this case, the input set is ignored. Example:

<syntaxhighlight lang="cpp">

is_in(50.7,7.2);

</syntaxhighlight>

Also in this variant, the result set can be redirected with the usual postfix notation:

<syntaxhighlight lang="cpp">

is_in(50.7,7.2)->.b;

</syntaxhighlight>

Area creation depends on some specific extraction rules, there's no area counterpart for each and every OSM relation! For more details see [https://github.com/drolbr/Overpass-API/blob/master/src/rules/areas.osm3s areas.osm3s] and the [[Overpass API/Areas|Areas Wiki page]].

To filter the result returned by ''is_in'' by additional filter criteria, an additional query is needed:

<syntaxhighlight lang="cpp">

is_in(48.856089,2.29789);

area._[admin_level="2"]; // ._ represents the default inputset, which contains all areas returned by ''is_in''

</syntaxhighlight>

=== The statement ''timeline'' ===

''since v0.7.55''

The statement ''timeline'' takes type and id of an object and optionally version as arguments.

It then returns a derived structure containing the meta information of the specified version.

If no version is specified then one object for each known version is returned.

Each of these objects has tags ''ref'', ''reftype'', and ''refversion'' to identify the reference.

In addition, it has tags ''created'' and ''expired'' that contain the relevant timestamps.

The base syntax is

timeline(<Type>, <Ref>);

resp.

timeline(<Type>, <Ref>, <Version>);

where <Type> is one of the three literals node, way, or relation.

In addition, an output set <Set> can be specified:

timeline(<Type>, <Ref>)->.<Set>;

resp.

timeline(<Type>, <Ref>, <Version>)->.<Set>;

=== The statement ''local'' ===

''since v0.7.55''

The statement ''local'' converts the given input into the localized representation of OSM data.

The output parameter controls which classes of data are included.

Without a type parameter local delivers geometry and tags.

This is one object per tagged node plus one object per part of a way plus one object per part of a relation geometry.

With the type parameter "ll", it delivers additionally loose objects.

There are one object per way with tags but without node members

and one object per relation member of any relation without node or way members.

With the type parameter "llb", it delivers even more data:

It delivers the objects that associate the OSM element ids to the aforementioned objects.

The base syntax is

local <Type>

where <Type> is empty, "ll", or "llb". You can also specify other input and/or output sets than "_":

.<Set> local <Type> ->.<Set>

The first set is the input set, the second set is the output set.

=== The statement ''convert'' ===

''since v0.7.54''

The statement ''convert'' produces one output element for every element in its input set. Its input and output sets are always the default set.

The content of each output element is controlled by the parameters of the statement. The statement discards geometry (lat/lon info).

The base syntax is

convert <Type> <List of Tags>

where <code><List of Tags></code> is a comma separated list of items,

each of which must be one the following

<Key> = <Evaluator>

::id = <Evaluator>

:: = <Evaluator>

!<Key>

The first parameter, <code><Type></code>, must have a fixed value. <code><Type></code> must start with a letter, and every following character can be either an alphanumeric character or an "_". <code><Type></code> controls the type of each output element.

The following parameters are used to set an arbitrary number of tags on each output element.

In the below description, each <code><Evaluator></code> is evaluated with an input element in context (see [[Overpass API/Overpass QL#Element Dependent Operators]]).

For each element in the input set:

* <code><Key> = <Evaluator></code> adds a key to the corresponding output element with value <code><Evaluator></code> evaluated with key <code><Key></code> (relevant for the [[#Tag Value and Generic Value Operators|generic evaluator]]).

* <code>::id = <Evaluator></code> sets the id of the corresponding output element to the value of <code><Evaluator></code>

* <code>:: = <Evaluator></code> is equivalent to <code><Key> = <Evaluator></code> for every key in the input element. This is called the generic key mechanism.

* <code>!<Key></code> prevents key <code><Key></code> from being set in the output element by the generic key mechanism.

Keys set explicitly with the <code><Key> = <Evaluator></code> syntax override keys set with the generic key mechanism.

If you do not set an id then a unique id from a global ascending counter is assigned.

It is a syntax error to set the same key twice using the <code><Key>=<Evaluator></code> or <code>!<Key></code> items.

=== The statement ''make'' ===

''since v0.7.54''

The statement ''make'' produces a set containing a single output element. Its output set is always the default set. The statement has no input set.

The content of the output element is controlled by the parameters of the statement. The statement cannot produce geometry (lat/lon info) on its output element.

The base syntax is

make <Type> <List of Tags>

where <code><List of Tags></code> is a comma separated list of items,

each of which must be one the following

<Key> = <Evaluator>

::id = <Evaluator>

<Set>:: = <Evaluator>

!<Key>

Note the difference from the ''convert'' statement syntax. In the ''make'' statement, the generic key mechanism requires an explicit input set.

The first parameter, <code><Type></code>, must have a fixed value. <code><Type></code> must start with a letter, then can contain alphanumeric characters and "_". <code><Type></code> controls the type of each output element.

The following parameters are used to set an arbitrary number of tags on the output element.

A description of each parameter item is below. Note that unlike in a ''convert'' statement, there is no element in context for the evaluators, so element dependent operators cannot be used.

* <code><Key> = <Evaluator></code> adds a key to the output element with value <code><Evaluator></code> evaluated with key <code><Key></code> (relevant for the [[#Tag Value and Generic Value Operators|generic evaluator]]).

* <code>::id = <Evaluator></code> sets the id of the output element to the value of <code><Evaluator></code>

* <code><Set>:: = <Evaluator></code> is equivalent to <code><Key> = <Evaluator></code> for every key that appears at least once in an element in <code><Set></code>. This item is called the generic key mechanism.

* <code>!<Key></code> prevents key <code><Key></code> from being set in the output element by the generic key mechanism.

Keys set explicitly with the <code><Key> = <Evaluator></code> syntax override keys set with the generic key mechanism.

If you do not set an id then a unique id from a global ascending counter is assigned.

It is a syntax error to set the same key twice using the <code><Key>=<Evaluator></code> or <code>!<Key></code> items.

Also, at most one generic key can be set.

=== The Query Statement ===

The most important statement is the ''query'' statement. This is not a single statement but rather consists of one of the type specifiers ''node'', ''way'', ''relation'' (or shorthand ''rel''), ''derived'', ''area'', or ''nwr'' (shorthand for "nodes, ways or relations") followed by one or more filters. The result set is the set of all elements that match the conditions of all the filters.

Example:

<syntaxhighlight lang="cpp">

// one filter

node[name="Foo"];

way[name="Foo"];

rel[name="Foo"];

nwr[name="Foo"];

nw[name="Foo"];

nr[name="Foo"];

wr[name="Foo"];

derived[name="Foo"];

area[name="Foo"];

// many filters

node[name="Foo"][type="Bar"];

</syntaxhighlight>

Here, ''node'', ''way'', ''rel'', ''nwr'', ''derived'', and ''area'' are the type specifier, ''[name="Foo"]'' resp. ''[type="Bar"]'' is the filter and the semicolon ends the statement.

The ''query'' statement has a result set that can be changed with the usual postfix notation.

<syntaxhighlight lang="cpp">

node[name="Foo"]->.a;

</syntaxhighlight>

The individual filters may have in addition input sets that can be changed in the individual filters. Please see for this at the respective filter.

=== The Query Filter ===

The query filter can be added as condition to a query statement.

It has an evaluator as argument and it lets pass only those elements for which the expression returns boolean true.

At the moment, the query filter cannot be the only condition in a query.

This is due to implementation reasons and will change in future versions.

It is technically possible to have multiple query filters in a single query.

But it does not make sense:

Their evaluators can be combined with a conjunction in a single query filter.

This has the same semantics and is faster.

Its syntax is

(if: <Evaluator>)

The whitespace is optional.

== Filters ==

=== By tag (''has-kv'') ===

The ''has-kv'' filter selects all elements that have or have not a tag with a certain value. It supports the basic OSM types node, way, and relation as well as the extended type area.

It has no input set. As for all filters, the result set is specified by the whole statement, not the individual filter.

All variants consist of an opening bracket, then a string literal in single or double quotes. Then the variants differ. All variants end with a closing bracket. If the string literal consists only of letters, the quotes can be omitted.

==== Equals (''='', ''!='') ====

The most common variant selects all elements where the tag with the given key has a specific value. This variant contains after the key literal an equal sign and a further literal containing the value. Examples, all equivalent:

<syntaxhighlight lang=js>

node[name=Foo];

node[name='Foo'];

node[name="Foo"];

node['name'="Foo"];

node["name"="Foo"];

node["name"='Foo'];

</syntaxhighlight>

If you have a digit, whitespace or whatever in the value, you do need single or double quotes:

<syntaxhighlight lang=js>

node[name="Foo Street"];

node["name:fr"="Rue Feau"];

</syntaxhighlight>

Querying for empty values [https://github.com/drolbr/Overpass-API/issues/92 is not possible] using the <i>equals value</i> operator. This can only be achieved by using a regular expression:

<syntaxhighlight lang="cpp">

node[power=""]; // not supported

node[power~"^$"]; // use regular expression instead

</syntaxhighlight>

Likewise, querying empty key values is also not possible using this kind of key-value query and needs to be expressed via regular expressions.

<syntaxhighlight lang="cpp">

node[~"^$"~"."]; // find nodes with empty key ("") and any value

</syntaxhighlight>

<small>NB: Overpass Turbo Wizard already has some logic in place to automatically convert ''""=""'' accordingly.</small>

==== Exists ====

The second variant selects all elements that have a tag with a certain key and an arbitrary value. It contains nothing between the key literal and the closing bracket:

<syntaxhighlight lang="cpp">

node["name"];

node['name'];

node[name];

</syntaxhighlight>

==== Not exists ====

''since v0.7.53''

This variant selects all element, that ''don't'' have a tag with a certain key and an arbitrary value.

<syntaxhighlight lang="cpp">

node[!"name"];

node[!'name'];

node[!name];

</syntaxhighlight>

In previous versions, 'not exists' had to be written as <code>node["name"!~".*"];</code>.

==== Value matches regular expression (''~'', ''!~'')====

The third variant selects all elements that have a tag with a certain key and a value that matches some regular expression. It contains after the key literal a tilde, then a second literal for the regular expression to search for:

{| class="wikitable"

! Statement

! Explanation

|-

| <code lang="cpp">node["name"~"^Foo$"];</code> || Finds nodes, where the tag ''name'' matches exactly ''Foo'' - identical to <code lang="cpp">node["name"="foo"];</code>

|-

| <code lang="cpp">node["name"~"^Foo"]; </code> || Finds nodes, where the tag ''name'' starts with ''Foo''

|-

| <code lang="cpp">node["name"~"Foo$"]; </code> || Finds nodes, where the tag ''name'' ends with ''Foo''

|-

| <code lang="cpp">node["name"~"Foo"]; </code> || Finds nodes, where the tag ''name'' contains the substring ''Foo'' anywhere in the tag value

|-

| <code lang="cpp">node["name"~".*"]; </code> || Finds nodes, where the tag ''name'' matches anything, equal to <code lang="cpp">node["name"];</code>

|-

| <code lang="cpp">node["name"!~".*"]; </code> || Finds nodes without ''name'' tag; does not have key name - identical to <code lang="cpp">node[!"name"];</code>

|-

|}

Please note that in QL you need to escape backslashes: ''["name"~"^St\."]'' results in the regular expression ''^St.'' (which finds every name starting with "St"), while ''["name"~"^St\\."]'' produces the most likely meant regular expression ''St\.'' (which finds every name starting with "St."). This is due to the C escaping rules and doesn't apply to the XML syntax.

Overpass implements the [https://en.wikipedia.org/wiki/Regular_expression#POSIX_basic_and_extended POSIX Extended] regular expression syntax.

===== Case insensitively =====

You can also search case insensitively

<syntaxhighlight lang="cpp">

node["name"~"^Foo$",i]; /* finds "foo", "FOO", "fOo", "Foo" etc. */

</syntaxhighlight>

Both the key and value variants with and without regular expressions can be negated. They then select exactly the elements which have a tag with the given key, but no matching value and the elements that don't have a tag with the given key:

<syntaxhighlight lang="cpp">

node["name"!="Foo"];

node["name"!~"Foo"];

node["name"!~"Foo",i];

</syntaxhighlight>

==== Key/value matches regular expression (~"key regex"~"value regex") ====

The fourth variant selects all elements where both key and value match a regular expression. After an initial tilde (~) the regular expression for the key needs to be provided, followed by another tilde character and eventually the regular expression for the value.

<syntaxhighlight lang="cpp">

node[~"^addr:.*$"~"^Foo$"]; /* finds addr:* tags with value exactly "Foo" */

node[~"^addr:.*$"~"^Foo"]; /* finds addr:* tags with value starting with "Foo" */

node[~"^addr:.*$"~"Foo$"]; /* finds addr:* tags with value ending with "Foo" */

node[~"^addr:.*$"~"Foo"]; /* finds addr:* tags with value containing the substring "Foo" */

node[~"^addr:.*$"~"."]; /* finds addr:* tags with any value */

node[~"^name(:.*)?$"~"."]; /* finds anything with a name or name:lang tag, and with any value */

node[~"^name(:ar|:he)?$"~"."]; /* finds anything with name, name:ar, or name:he tag, and with any value*/

</syntaxhighlight>

This format also supports case-insensitive searches: <code>node[~"^addr:.*$"~"^Foo$",i];</code>. Case-insensitivity applies to both tag key and value searches in this case.

{{Ambox

| type = notice

| text =<div style="text-align:left">

* Regular expressions for values cannot be negated in this variant. However, this can be expressed via the [[Overpass_API/Overpass_QL#Difference|difference]] block statement.

* It's not possible with this syntax to use regular expressions for matching either tag names but matching values by simpler equality or inequality.

</div>

}}

=== Bounding box{{Anchor|boundingboxqueryfilter}} ===

The ''bounding box'' query filter selects all elements within a rectangular bounding box.

It has no input set. As for all filters, the result set is specified by the whole statement, not the individual filter.

<syntaxhighlight lang="cpp">

(south,west,north,east)

</syntaxhighlight>

It consists of an opening parenthesis. Then follow four floating point numbers, separated by commas. The filter ends with a closing parenthesis.

The floating point numbers give the limits of the bounding box: The first is the southern limit or minimum latitude. The second is the western limit, usually the minimum longitude. The third is the northern limit or maximum latitude. The last is the eastern limit, usually the maximum longitude. If the second argument is bigger than the fourth argument, the bounding box crosses the longitude of 180 degrees.

Example:

<syntaxhighlight lang="cpp">

node(50.6,7.0,50.8,7.3);

</syntaxhighlight>

See also: [[#Global bounding box (bbox)]].

=== Recurse (''n'', ''w'', ''r'', ''bn'', ''bw'', ''br'') ===

The ''recurse'' filter selects all elements that are members of an element from the input set or have an element of the input set as member, depending on the given parameter.

The input set can be changed with an adapted prefix notation. As for all filters, the result set is specified by the whole statement, not the individual filter.

It consists of an opening parenthesis. Then follows one of the symbols: ''w'' (forward from ways), ''r'' (forward from relations), ''bn'' (backward from nodes), ''bw'' (backward from ways), or ''br'' (backward from relations). Then follows an optional input set declaration. The filter ends with a closing parenthesis.

Examples with default input set:

<syntaxhighlight lang="cpp">

node(w); // select child nodes from ways in the input set

node(r); // select node members of relations in the input set

way(bn); // select parent ways for nodes in the input set

way(r); // select way members of relations in the input set

rel(bn); // select relations that have node members in the input set

rel(bw); // select relations that have way members in the input set

rel(r); // select relation members of relations in the input set

rel(br); // select parent relations from relations in the input set

</syntaxhighlight>

Example with modified input set:

<syntaxhighlight lang="cpp">

node(w.foo); // select child nodes from ways in the "foo" input set

</syntaxhighlight>

You can also restrict the recurse to a specific role. Just add a colon and then the name of the role before the closing parenthesis.

Examples with default input set:

<syntaxhighlight lang="cpp">

node(r:"role"); // select node members of relations in the input set

way(r:"role"); // select way members of relations in the input set

rel(bn:"role"); // select relations that have node members in the input set

rel(bw:"role"); // select relations that have way members in the input set

rel(r:"role"); // select relation members of relations in the input set

rel(br:"role"); // select parent relations from relations in the input set

</syntaxhighlight>

Example with modified input set:

<syntaxhighlight lang="cpp">

node(r.foo:"role"); // select node members with role "role" of relations in the "foo" input set

</syntaxhighlight>

And you can also search explicitly for empty roles:

<syntaxhighlight lang="cpp">

node(r:""); // select node members with empty role of relations in the input set

node(r.foo:""); // select node members with empty role of relations in the "foo" input set

</syntaxhighlight>

=== Recurse (way_cnt, way_link) ===

These variants of recurse select all nodes that are member of a specific number of way resp. way segments.

Both need a number or a range as second argument and optinally can have an input set.

The ''way_cnt'' criterion selects those nodes that are members of a given number of ways.

E.g. the criterion ''(way_cnt:2)'' selects all crossings between ways and all nodes where two ways join.

By contrast, the ''way_link'' criterion counts way segments.

Inner nodes without a crossing have way link count two,

because there is exactly one segment to connect to the predecessor and one segment to connect to the successor.

Joins also have segment count two.

This is way it is easy to select independently crossings because they have segment count three or greater

or dead ends because they have segment count one.

Examples with default input set:

<syntaxhighlight lang="cpp">

node(way_cnt:2); // select those nodes that are members of exactly two of the given ways

node(way_cnt:3-4); // select those nodes that are members of three to four of the given ways

node(way_cnt:2-); // select those nodes that are members of two or more of the given ways

node(way_link:1); // select those nodes that are members of exactly one segment of the given ways, i.e. are dead ends

node(way_link:4-5); // select those nodes that are members of four to five segments of the given ways

node(way_link:3-); // select those nodes that are members of three or more segments of the given ways, i.e. crossings

</syntaxhighlight>

Example with modified input set:

<syntaxhighlight lang="cpp">

node(way_link.foo:3-); // select those crossing nodes based on the way grid in set foo

</syntaxhighlight>

=== By input set (''.setname'') ===

The "item" filter selects all elements from its input set.

As for all filters, the result set is specified by the whole statement, not the individual filter.

It consists of a dot, followed by the name of the input set.

Examples: The default set:

<syntaxhighlight lang="cpp">

node._;

</syntaxhighlight>

and a named set:

<syntaxhighlight lang="cpp">

node.a;

</syntaxhighlight>

It is also possible to specify several input sets ('''[[#Intersection|set intersection]]'''). For example:

<syntaxhighlight lang="cpp">

node.a.b;

</syntaxhighlight>

: This statement returns all nodes which are '''both''' in input set ''.a'' and input set ''.b''.

=== By element id ===

The ''id-query'' filter selects the element of given type with given id. It supports beside the OSM datatypes node, way, and relation also the type area.

It has no input set. As for all filters, the result set is specified by the whole statement, not the individual filter.

It consists of an opening parenthesis. Then follows a positive integer. The filter is ended with a closing parenthesis.

Examples:

<syntaxhighlight lang="cpp">

node(1);

way(1);

rel(1);

area(1);

</syntaxhighlight>

Area ids are derived from an existing OSM relation by adding 3600000000. There used to be a similar formula for ways, but closed ways can now directly used as areas. You should use the [[Overpass API/Overpass QL#Map way.2Frelation to area .28map to area.29|map_to_area function]] to avoid having to make these calculations manually and depend on any hard-coded constants in your query.

Area creation is subject to some extraction rules, i.e. not all ways/relations have an area counterpart. See [https://github.com/drolbr/Overpass-API/blob/master/src/rules/areas.osm3s areas.osm3s] for details.

Since version 0.7.54, the ''id-query'' filter also supports multiple values. To avoid conflicts with the bounding box filter, a new mandatory ''id:'' prefix has to be used in this case.

<syntaxhighlight lang="cpp">

node(id:1000,1001,1002,1003,1004,1005);

way(id:3998029,3998240,4065354,4065364,4065392,4065421);

rel(id:10815,10816);

area(id:1234);

</syntaxhighlight>

'''Performance hint:''' Try to bundle multiple id queries into one statement, i.e. instead of writing <code>(way(3998029);way(3998240);way(4065354););</code> use <code>way(id:3998029,3998240,4065354);</code>

=== Relative to other elements (''around'') ===

{{Ambox|text=When possible, consider using the ''[[#boundingboxqueryfilter|bounding box]]'' query filter instead of the ''around'' query filter. The bounding box query filter performs faster.|type=notice}}

The ''around'' filter selects all elements within a certain radius in metres around the elements in the input set. If you provide coordinates, then these coordinates are used instead of the input set. The input set can be changed with an adapted prefix notation. As for all filters, the result set is specified by the whole statement, not the individual filter.

A radius of 0 can be used for a way intersection test on outer/inner points.

Syntax: It consists of an opening parenthesis. Then follows the keyword <code>around</code>. Then follows optionally an input set declaration. Then follows a single floating point number that denotes the radius in meters. The filter either ends with a closing parenthesis or is followed by two comma separated floating point numbers indicating latitude and longitude and then finally a closing parenthesis.

<syntaxhighlight lang="cpp">

(around[.input_set]:radius)

(around:radius,latitude,longitude)

</syntaxhighlight>

Since version 0.7.55, it is possible to query for all elements which are within a certain radius of a given linestring, which is given by a list of lat/lon pairs:

<syntaxhighlight lang="cpp">

(around[.input_set]:radius)

(around:radius,latitude_1,longitude_1,latitude_2,longitude_2,...,latitude_n,longitude_n)

</syntaxhighlight>

Example:

<syntaxhighlight lang="cpp">

node(around:100.0);

way(around:100.0);

rel(around:100.0);

</syntaxhighlight>

Example with modified input set:

<syntaxhighlight lang="cpp">

node(around.a:100.0);

</syntaxhighlight>

Example with coordinates:

<syntaxhighlight lang="cpp">

node(around:100.0,50.7,7.1);

way(around:100.0,50.7,7.1);

rel(around:100.0,50.7,7.1);

</syntaxhighlight>

Example with linestring:

{{OverpassTurboExample|loc=50.51201;8.09641;12|query=

way[highway](around:500,50.540853270068986,8.048780365649707,50.53106288705902,8.030823236553783,50.51780737956311,8.019643105996508,50.50287491071276,8.016749912560886,50.48828159051387,8.022534398052139,50.47599950382573,8.036215335651725,50.467689755650376,8.055945038928135,50.46447690759688,8.079058902127825,50.46679590711731,8.102435269947343,50.47433280529453,8.122917034379736,50.48606755168466,8.137738019645033,50.50041288059356,8.144896569557243,50.51542994506574,8.143425882283827,50.529090915610794,8.13352458229042,50.53955268865336,8.11652989500613,50.545404823255616,8.09473704711951,50.545858734919165,8.07108928349599,50.540853270068986,8.048780365649707)

;(._;>;);out meta;

}}

For further use cases, see this [https://www.openstreetmap.org/user/mmd/diary/42055 diary entry].

Example: Find all cinema nodes in Bonn which are at most 100m away from bus stops

{{OverpassTurboExample|query=

area[name="Bonn"];

node(area)[highway=bus_stop];

node(around:100)[amenity=cinema];

out;

}}

Find both cinema nodes and ways in Bonn, which are at most 100m away from bus stop nodes:

{{OverpassTurboExample|query=

area[name="Bonn"];

node(area)[highway=bus_stop]->.bus_stops;

(

way(around.bus_stops:100)[amenity=cinema];

node(around.bus_stops:100)[amenity=cinema];

);

(._;>;);

out meta;

}}

=== By polygon (''poly'') ===

The ''polygon'' filter selects all elements of the chosen type inside the given polygon.

It has no input set. As for all filters, the result set is specified by the whole statement, not the individual filter.

It consists of an opening parenthesis. Then follows the keyword ''poly''. Then follows a string containing an even number of floating point numbers, divided only by whitespace. Each pair of floating point numbers represents a coordinate, in order latitude, then longitude. The filter ends with a closing parenthesis:

<syntaxhighlight lang="cpp">

(poly:"latitude_1 longitude_1 latitude_2 longitude_2 latitude_3 longitude_3 …");

</syntaxhighlight>

An example (a triangle near Bonn, Germany):

<syntaxhighlight lang="cpp">

node(poly:"50.7 7.1 50.7 7.2 50.75 7.15");

way(poly:"50.7 7.1 50.7 7.2 50.75 7.15");

rel(poly:"50.7 7.1 50.7 7.2 50.75 7.15");

</syntaxhighlight>

'''Performance hint:''' A large number of latitude/longitude pairs slows down the <code>(poly: )</code> filter, hence simplifying the polyline geometry before using it in a poly filter is recommended.

=== ''newer'' ===

The ''newer'' filter selects all elements that have been changed since the given date. As opposed to other filters, this filter cannot be used alone. If the underlying database instance supports attic data and the date difference is at most one month, then "changed" is probably a better choice than "newer".

It has no input set. As for all filters, the result set is specified by the whole statement, not the individual filter.

It consists of an opening parenthesis. Then follows a date specification. Please note that this date specification cannot be abbreviated and has to be put in single or double quotes. The filter ends with a closing parenthesis.

Example:

<syntaxhighlight lang="cpp">

node._(newer:"2012-09-14T07:00:00Z");

</syntaxhighlight>

: This finds all nodes that have changed since 14 Sep 2012, 7 h UTC, in the given input set.

=== By date of change (''changed'') ===

The ''changed'' filter selects all elements that have been changed between the two given dates. If only one date is given, then the second is assumed to be the front date of the database.

If only one date is given and it is run with the current timestamp, then it behaves exactly like "newer" with two exceptions: first, it is faster (see note), second, it can also stand as the only filter.

'''Note:''' As of June 2017, a known bug can cause "changed" to be much slower than "newer" in some cases. Consider using "newer" until it is resolved, or consider testing which one runs faster for you. See the following Github issues: [https://github.com/drolbr/Overpass-API/issues/278 <s>#278</s>] (resolved), [https://github.com/drolbr/Overpass-API/issues/322 #322], [https://github.com/drolbr/Overpass-API/issues/346 #346]. See this [https://forum.openstreetmap.org/viewtopic.php?pid=649744#p649744 discussion] too.

It has no input set. As for all filters, the result set is specified by the whole statement, not the individual filter.

It consists of an opening parenthesis. Then follows a date specification. Please note that this date specification cannot be abbreviated and has to be put in single or double quotes. Then can follow a comma and a second date specification. The filter ends with a closing parenthesis.

Example: All changes since the given date and now

<syntaxhighlight lang="cpp">

node._(changed:"2012-09-14T07:00:00Z");

</syntaxhighlight>

Example: All changes between the two given dates

<syntaxhighlight lang="cpp">

node._(changed:"2012-09-14T07:00:00Z","2012-09-14T07:01:00Z");

</syntaxhighlight>

=== By user (''user'', ''uid'') ===

The ''user'' filter selects all elements that have been last touched by the specified user.

It has no input set. As for all filters, the result set is specified by the whole statement, not the individual filter.

It consists of an opening parenthesis. Then follows either the keyword ''user'', a colon and a string literal denoting the user name to search for. Or the keyword ''uid'' followed by the user id of the user to search for. The filter ends with a closing parenthesis.

Example:

<syntaxhighlight lang="cpp">

node(user:"Steve");

node(uid:1);

</syntaxhighlight>

For all elements ever touched by a user use ''user_touched'' or ''uid_touched'':

<syntaxhighlight lang="cpp">

node(user_touched:"Steve");

node(uid_touched:1);

</syntaxhighlight>

Since release 0.7.53 it is also possible to specify multiple user names:

<syntaxhighlight lang="cpp">

node(user:"Mapper1","Mapper2","Mapper 3");

node(uid:1,2,4,8,16);

</syntaxhighlight>