Overpass API/Areas

From OpenStreetMap Wiki
Jump to navigation Jump to search
Overpass API logo.svg
edit
Overpass API · Language reference · Language guide · Technical terms · Areas · Query examples · Sparse Editing · Permanent ID · FAQ · more · Web site
Servers status · Versions · Development · Technical design · Installation · XAPI compatibility layer · Public transport sketch lines · Applications · Source code and issues
Overpass turbo · Wizard · Overpass turbo shortcuts · MapCSS stylesheets · Export to GeoJSON · more · Development · Source code and issues · Web site
Overpass Ultra · Overpass Ultra extensions · MapLibre stylesheets ·more · Source code and issues · Web site

Areas are an extension of Overpass API: They constitute a new data type area beside the OSM data types node, way, and relation. So this data is not extracted and updated from the main API, but computed by a special process on the Overpass API server.

Areas can be used in queries according to the language guide and language reference.

We explain here in more detail the computation process: The computation process is executed in an infinite loop on the Overpass API server, where each run lasts between 4 and 12 hours. It used to execute the following script, which is nowadays replaced by a more sophisticated version (see link above):

Note: this script is meant to be exclusively run on the server. Any other Overpass API user (like overpass turbo) can neither trigger the area creation nor directly influence the area creation rules. If you think the area creation rules are incomplete, you should raise a Github issue. The code below is a sample, check the relevant file on Github for an up to date list.


<?xml version="1.0" encoding="UTF-8"?>
<osm-script timeout="86400" element-limit="1073741824">

<union>
  <query type="relation">
    <has-kv k="admin_level"/>
    <has-kv k="name"/>
  </query>
  <query type="relation">
    <has-kv k="type" v="multipolygon"/>
    <has-kv k="name"/>
  </query>
  <query type="relation">
    <has-kv k="postal_code"/>
  </query>
  <query type="relation">
    <has-kv k="addr:postcode"/>
  </query>
</union>
<foreach into="pivot">
  <union>
    <recurse type="relation-way" from="pivot"/>
    <recurse type="way-node"/>
  </union>
  <make-area pivot="pivot"/>
</foreach>

<query type="way">
  <has-kv k="area" v="yes"/>
  <has-kv k="name"/>
</query>
<foreach into="pivot">
  <union>
    <item set="pivot"/>
    <recurse type="way-node" from="pivot"/>
  </union>
  <make-area pivot="pivot"/>
</foreach>

</osm-script>

Let's walk through the file: We derive one area from each relation that

  • have a tag admin_level and a tag name,
  • have a tag type with value multipolygon and a tag name,
  • have a tag postal_code, or
  • have a tag addr:postcode.

This is subject of the first union block.

In the following foreach block, the area is actually created: the shape is built from the way members of the relation, the tags are copied from the relation itself, the pivot object.

The second union block selects all ways that have a tag area with value yes and a tag name. Here, we create one area for each way. The tags are taken here from the respective way, as well as the shape.