There are three different output formats available from Overpass API, and each of these output formats is available in different levels of details for the included data. While the level of detail is controlled with the parameters used for the respective out or print statement, we discuss here the available output formats:
Note that regardless of the chosen output type, the server may return an HTML document in case of a malformed input.
The format generally follows the description in the wiki. It doesn't contain a bounds tag, and it may contain certain additional tags. Anyway, in all cases well-formed XML is returned.
A response (an example) from Overpass API has always the following header and footer:
<?xml version="1.0" encoding="UTF-8"?> <osm version="0.6" generator="Overpass API"> <note>The data included in this document is from www.openstreetmap.org. It has there been collected by a large group of contributors. For individual attribution of each item please refer to http://www.openstreetmap.org/api/0.6/[node|way|relation]/#id/history </note> <meta osm_base="date"/> ... </osm>
The meta tags contains in the attribute osm_base the entry date with a timestamp of the data. That means that all edits that have been uploaded before this date are included. The format is always YYYY-MM-DDThh:mm:ssZ, where YYYY is a four digit year, MM is a two digit month, DD is a two digit day of month. hh:mm:ss is the time with two digits hours, minutes and seconds.
If the query involves area data processing, a second timestamp in the same format is included in the attribute areas:
<meta osm_base="date" areas="date"/>
This date is the date of the latest edit that has been considered in the most recent batch run of the area generation.
Please note also the note tag. This always tells a copyright reminder and can be ignored when parsing the data for other purposes. By contrast, if you find an error tag, something seriously has gone wrong, most likely an internal server error. I suggest to handle this similar to a network outage and additionally to propagate the error message back to the user to make bug reports possible.
The XML data itself, i.e. the tags node, way and relation are returned exactly as from the main server.
If you request areas, you will get for each area an area tag with an attribute id. The tag contains as subtags all the tags that are set on the area or inherited by the area from the object it has been generated from.
Unfortunately, there are several slightly different syntaxes for OSM data in JSON. For that reason, we will describe the syntax used by Overpass API in detail here. At the lowest level, it is well-formed JSON. In particular, the following characters are escaped:
| Character | Escaped as literally |
|---|---|
| " (quotation mark) | \" |
| \ (backslash) | \\ |
| \n (newline) | \n |
| \t (tabulator) | \t |
| \r (line feed) | \r |
Any other character with ASCII value between 0 and 31 is replaced for safety reasons by a question mark. In principle, this can't happen, because these characters are disallowed in the main database. Characters are encoded as UTF-8.
Please note that some Firefox versions do present JSON as if it were ISO-8859-1. This means that non-ASCII characters are presented as random nonsense. You can force Firefox to a conforming presentation by setting it to "Unicode" encoding.
To get a response in format JSON, start the request with a [out:json] directive, for example:
/api/interpreter?data=[out:json];out;
A response (an example) from Overpass API always has the following header and footer:
{
"version": 0.6,
"generator": "Overpass API",
"osm3s": {
"timestamp_osm_base": "date",
"copyright": "The data included in this document is from www.openstreetmap.org. It has there been collected by a large group of contributors. For individual attribution of each item please refer to http://www.openstreetmap.org/api/0.6/[node|way|relation]/#id/history"
},
"elements": [
...
]
}
The payload is contained between the brackets after elements. Each element is contained in a pair of curly braces, and two elements are separate by a comma. The date is constructed in the same way as for the XML format.
We discuss the node representation (and further down the representations of ways and relations) by examples:
An example with the spatial data only:
{
"type": "node",
"id": 1,
"lat": 2.0,
"lon": -3.0
}
The same example, also with meta data:
{
"type": "node",
"id": 1,
"lat": 2.0,
"lon": -3.0,
"timestamp": "2010-01-01T00:00:00Z",
"version": 4,
"changeset": 5,
"user": "somebody",
"uid": 6
}
And again the same example, this time with some tags:
{
"type": "node",
"id": 1,
"lat": 2.0,
"lon": -3.0,
"tags": {
"highway": "bus_stop",
"name": "Main Street"
}
}
The key-value-pairs type:node and id are always present. The key-value-pairs lat, lon, timestamp, version, changeset, user, and uid are present or not depedend on the chosen degree of verbosity and are always printed in this order. id, lat, lon, and uid are numbers, the rest are strings. Then, a key tags may follow if the node has tags and you have chosen to print tags, with a key-value-pair for each tag, and both are always strings, regardless whether their content could be read as a number or not.
Ways follow a similar pattern: They consist of the key-value-pairs type:way, id, timestamp, version, changeset, user, and uid, depending on the chosen degree of verbosity. Then, a key nodes follows with an ordered list as value, containg the ids of the nodes that belong to the way. The last maybe contained key is tags with a map as value as above.
An example:
{
"type": "way",
"id": 1,
"nodes": [
10,
11,
12
],
"tags": {
"highway": "tertiary",
"name": "Main Street"
}
}
Relations also follow a similar pattern: They consist of the key-value-pairs type:relation, id, timestamp, version, changeset, user, and uid, depending on the chosen degree of verbosity. Then, a key members follows with an ordered list as value, containg an entry for each member. A member is always a map with keys type, ref, and role. The last maybe contained key is tags with a map as value as above.
An example:
{
"type": "relation",
"id": 1,
"members": [
{
"type": "relation",
"ref": 1745069,
"role": ""
},
{
"type": "relation",
"ref": 172789,
"role": ""
}
],
"tags": {
"from": "Konrad-Adenauer-Platz",
"name": "VRS 636",
"network": "VRS",
"operator": "SWB",
"ref": "636",
"route": "bus",
"to": "Gielgen",
"type": "route_master",
"via": "Ramersdorf"
}
}
The custom output allows to convert a search for an object into an object id or to show a search result page. This is a rather advanced usage of Overpass API. Thus, we explain it from the simple use case to the complex use case.
The simplest variant is the redirect with potential disambiguation page. We give two examples:
In the first example, no disambiguation is necessary because the search criteria describe an unique object. In the second example, three objects exist and do so for good reason. Thus, a disambiguation page is necessary and therefore displayed.
If you want always a disambiguation page, you can add the directive redirect=no to the end. This forces a disambiguation page to be displayed:
You can of course also change the destination URL. Add url=something to the end. For example, we replace the element view on the main database by a full map view in the above query:
Note that the URL usually depends on the id and the type of the found results. To customize this, you can add the placeholders {{{type}}} and {{{id}}} anywhere in the URL; these will be replaced by the proper type (node, way or relation) and the id of the found object.
You can also change the template that is used for the disambiguation page. There are two standard templates offered:
By default, default.wiki is used as template. To select another template, for example the just introduced base.wiki, use the template=something directive. Please compare:
Technically, the template is taken from the subdirectory templates of the database directory of the server. For the public instances, there exist also a mechanism to upload a completetly custom template from the wiki to this directory. The upload mechanism is explained on the Wiki employment page. The syntax of the template page is explained in the following:
We first list base.wiki and then explain it in detail:
<h1>{{{count}}} results found</h1>
{{node:
<p>Node <strong>{{{id}}}</strong>,{{coords: lat: {{{lat}}}, lon: {{{lon}}},}}<br/>
{{tags:{{{key}}} = {{{value}}}<br/>
}}
<a href="http://www.openstreetmap.org/browse/node/{{{id}}}">Browse on openstreetmap.org</a></p>
}}
{{way:
<p>Way <strong>{{{id}}}</strong>,{{bbox:{{none: no geographic reference}} bounding box south: {{{south}}}, west: {{{west}}}, north: {{{north}}}, east: {{{east}}},}}<br/>
{{tags:{{{key}}} = {{{value}}}<br/>
}}{{members:{{first: members: {{{ref}}}}}, {{{ref}}}}}<br/>
<a href="http://www.openstreetmap.org/browse/way/{{{id}}}">Browse on openstreetmap.org</a></p>
}}
{{relation:
<p>Relation <strong>{{{id}}}</strong>,{{bbox:{{none: no geographic reference}} bounding box south: {{{south}}}, west: {{{west}}}, north: {{{north}}}, east: {{{east}}},}}<br/>
{{tags:{{{key}}} = {{{value}}}<br/>
}}{{members:{{first: members: {{{type}}} <strong>{{{ref}}}</strong> "{{{role}}}"}}, {{{type}}} <strong>{{{ref}}}</strong> "{{{role}}}"}}<br/>
<a href="http://www.openstreetmap.org/browse/relation/{{{id}}}">Browse on openstreetmap.org</a></p>
}}
The entire template will be processed into the body of the returned HTML document.
The content of the block {{node:...}}, i.e. exactly the text after {{node: and before the corresponding closing }} is repeated once for every node in the search results. Similarly, each block {{way:...}} and each block {{relation:...}} is repeated once for every way respectively relation in the search results.
Within a node block, the placeholder {{{id}}} is replaced by the id of the found node. If coordinates are allowed by the chosen level of detail, the block {{coords:...}} is inserted. Otherwise, it is omitted. Inside the block {{coords:...}}, the placeholders {{{lat}}} and {{{lon}}} are replaced by the latitude and longitude.
In the same fashion, the block {{tags:...}} is repeated once for every tag of the node. Inside the block {{tags:...}}, the placeholders {{{key}}} and {{{value}}} are replaced by the key and value of the tag.
The way and relation blocks have slightly different sub-blocks: Instaed of the coordinate block, a block {{bbox:...}} is present. There, the placeholders {{{south}}} and {{{north}}} are replaced by the latitudes from the bounding box, and {{{west}}} and {{{east}}} are replaced by the longitudes of the bounding box. Note that the bounding box is really coarse - it is derived from a database-internal bounding box, not from the coordinates of the actual elements.
After the block {{tags:...}}, which is inserted in the same fashion as into nodes, a block {{members:...}} follows once for each member of the way resp. relation. There, the placeholder {{{ref}}} is replaced by the id of the referenced object. For a relation, also the {{{type}}} and {{{role}}} placeholders are replaced with the corresponding data of the objects.
The blocks {{bbox:...}} and {{members:...}} also accept two special, optional sub blocks: If a block {{none:...}} is present, then this block is printed if the corresponding element doesn't have a bounding box or doesn't have any members. If a block {{first:...}} is present, this block is printed for the first element instead of a copy of the surrouding {{members:...}} block.
In the global file, the placeholder {{{count}}} is replaced by the found number of objects.
The popup output allows to get the full OSM details at every point of the map. Just click somewhere on the example page. Like the custom output, it is an HTML document.
In the basic configuration, like in the example
the results are sorted into several categories. For each object, the entry consists of the value of the name tag (or the Id, if the tag name is not set), and then a list of all the tags with keys and values. If one of the tags has a value that looks like a URL, the headline is equipped with a link to his URL.
In the advanced configuration, you can select the categories yourself. For each category, you must set a headline, specify a filter, and choose the pivot tag. We explain all this with an example:
The part up to the first semicolon, here "Public Transport Stops", is the headline for this category, usually in quotation marks.
All following parts but the last part up to a semicolon are interpreted as the filter: Each part is a sequence of one or more clauses in brackets. The bracket clauses have the same syntax as the has-kv clauses. The are combined by conjunction (with "and"). The so formed expressions are then combined by disjunction (with "or"). This has always exactly these two levels, so you need to bring other logical expressions to this normal form (which is always possible). Our example filter works as follows:
The last part contains the name of the tag whose value shall be used as title. It is almost always name.
You can combine multiple categories by writing them one after another: