Overpass API

https://wiki.openstreetmap.org/wiki/Overpass_API
Admin
The Overpass API is a read-only API that serves custom selected parts of OpenStreetMap (OSM) map...
Tokens:197,911
Snippets:1,540
Trust Score:10
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install NGINX and fcgiwrap

Source: https://wiki.openstreetmap.org/wiki/Overpass_API/Installation

Installs and enables NGINX and fcgiwrap on Ubuntu. fcgiwrap creates a socket file at /var/run/fcgiwrap.socket.

```bash
sudo apt-get install nginx fcgiwrap
sudo systemctl enable --now nginx fcgiwrap

```

--------------------------------

### Compile and install OSM3S from tarball

Source: https://wiki.openstreetmap.org/wiki/Overpass_API/Installation

Compile and install the OSM3S package from the tarball. Set $EXEC_DIR to your desired installation prefix.

```bash
cd osm-3s_v*
./configure CXXFLAGS="-O2" --prefix=$EXEC_DIR
make install

```

--------------------------------

### Regular expression matching examples

Source: https://wiki.openstreetmap.org/wiki/Overpass_API/Overpass_QL

Table of examples showing how to use the ~ and !~ operators to match tag values against regular expressions.

```overpass
node["name"~"^Foo$"];
```

```overpass
node["name"~"^Foo"];
```

```overpass
node["name"~"Foo$"];
```

```overpass
node["name"~"Foo"];
```

```overpass
node["name"~".*"];
```

```overpass
node["name"!~".*"];
```

--------------------------------

### Install Apache2 and enable CGI modules

Source: https://wiki.openstreetmap.org/wiki/Overpass_API/Installation

Install Apache2 and enable the CGI and ext_filter modules required for the Web API. Run these commands as root or with sudo.

```bash
sudo apt-get install apache2
sudo a2enmod cgi ext_filter

```

--------------------------------

### Difference example with result set redirection

Source: https://wiki.openstreetmap.org/wiki/Overpass_API/Overpass_QL

Same as the preceding example, but the result is written into the variable _a_.

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

```

--------------------------------

### Compile and install OSM3S from dev version

Source: https://wiki.openstreetmap.org/wiki/Overpass_API/Installation

Compile and install the OSM3S package from the dev version source.

```bash
cd ../build/
../src/configure CXXFLAGS="-Wall -O2" --prefix=$EXEC_DIR
make install

```

--------------------------------

### Example OSM3S query for pubs in Cologne

Source: https://wiki.openstreetmap.org/wiki/Overpass_API/Installation

Example query that returns all pubs in Cologne. Use after importing the entire planet.

```xml
<query type="node"><bbox-query n="51.0" s="50.9" w="6.9" e="7.0"/><has-kv k="amenity" v="pub"/></query><print/>

```

--------------------------------

### Start dispatcher daemon with meta data

Source: https://wiki.openstreetmap.org/wiki/Overpass_API/Installation

Starts the dispatcher daemon with meta data support. Add the --meta parameter to enable meta data.

```bash
nohup $EXEC_DIR/bin/dispatcher --osm-base --meta --db-dir=$DB_DIR  &

```

--------------------------------

### Diff setting examples

Source: https://wiki.openstreetmap.org/wiki/Overpass_API/Overpass_QL

Compares query results between two dates. The first example compares with the current date; the second compares two specified dates. Output does not include intermediate versions.

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

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

--------------------------------

### Install dependencies on CentOS/RHEL 7

Source: https://wiki.openstreetmap.org/wiki/Overpass_API/Installation

Install the required dependencies for building Overpass API on CentOS or RHEL 7. The first command installs build tools and libraries, the second installs fpm for packaging.

```bash
$ sudo yum install tar make gcc-c++ expat expat-devel zlib-devel bzip2 rpmbuild gcc ruby-devel rpm-install
$ sudo gem install fpm

```

--------------------------------

### Union example with result set redirection

Source: https://wiki.openstreetmap.org/wiki/Overpass_API/Overpass_QL

Same as the preceding example, but the result is written into the variable _a_.

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

```

--------------------------------

### Start dispatcher daemon for attic data

Source: https://wiki.openstreetmap.org/wiki/Overpass_API/Installation

Starts the dispatcher daemon for serving attic data. Use the --attic parameter.

```bash
nohup $EXEC_DIR/bin/dispatcher --osm-base --attic --db-dir=$DB_DIR &

```

--------------------------------

### Start areas dispatcher and set permissions

Source: https://wiki.openstreetmap.org/wiki/Overpass_API/Installation

Start a second dispatcher for areas and set permissions on the areas files. The dispatcher is successfully started when the line "Dispatcher just started." appears in transactions.log with the correct UTC date.

```bash
nohup $EXEC_DIR/bin/dispatcher --areas --db-dir=$DB_DIR &

chmod 666 "../db/osm3s_v0.7.*_areas"
```

--------------------------------

### Body print mode example (Overpass QL)

Source: https://wiki.openstreetmap.org/wiki/Overpass_API/Language_Guide

Overpass QL equivalent of the XML body print example. Uses 'out;' to print in default body mode.

```Overpass QL
node
  ["name"="Gielgen"]
  ["place"="suburb"];
out;

```

--------------------------------

### Install required packages on Ubuntu/Debian

Source: https://wiki.openstreetmap.org/wiki/Overpass_API/Installation

Install the required packages for building Overpass API on Ubuntu or Debian: g++, make, expat, libexpat1-dev, and zlib1g-dev.

```bash
sudo apt-get update
sudo apt-get install g++ make expat libexpat1-dev zlib1g-dev

```

--------------------------------

### Start dispatcher daemon for osm-base

Source: https://wiki.openstreetmap.org/wiki/Overpass_API/Installation

Starts the dispatcher daemon for the osm-base database. Required for automatic diff updates or running the Web API. Do not run as root.

```bash
nohup $EXEC_DIR/bin/dispatcher --osm-base --db-dir=$DB_DIR &

```

--------------------------------

### CSV output example with count row

Source: https://wiki.openstreetmap.org/wiki/Overpass_API/Overpass_QL

Example output showing the additional count row with type 'count' and total count of 5.

```text
@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

```

--------------------------------

### out setting example

Source: https://wiki.openstreetmap.org/wiki/Overpass_API/Overpass_QL

Sets the output format to JSON.

```overpass
[out:json]
```

--------------------------------

### Global bounding box syntax and examples

Source: https://wiki.openstreetmap.org/wiki/Overpass_API/Overpass_QL

Defines the map area for the query using [bbox:south,west,north,east]. The default is the entire world. Examples frame Bonn, Germany and part of Rio de Janeiro, Brazil.

```overpassql
[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]
```

--------------------------------

### Existing XAPI Query

Source: https://wiki.openstreetmap.org/wiki/Overpass_API/XAPI_Compatibility_Layer

An example of a standard XAPI query URL used to fetch OSM data.

```text
https://overpass-api.de/api/xapi?*[bbox=7.1,51.2,7.25,51.3][highway=bus_stop][@uid=65282][@meta]
```

--------------------------------

### Recurse: Get nodes of ways of relations with ref=E61

Source: https://wiki.openstreetmap.org/wiki/Overpass_API

Retrieves the nodes of the ways of relations with ref=E61. Note that this does not include the bus stops themselves, as explained in the union examples.

```overpass-ql
rel[ref="E61"];
way(r);
node(w);
out body;

```

```xml
<osm-script><query type="relation">
  <has-kv k="ref" v="E61"/>
</query>
<recurse type="relation-way"/>
<recurse type="way-node"/>
<print/></osm-script>

```

--------------------------------

### Step-by-step completed ways and relations

Source: https://wiki.openstreetmap.org/wiki/Overpass_API/Overpass_API_by_Example

A manual breakdown of the previous example using specific recursion blocks for nodes, ways, and relations.

```Overpass QL
(
  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;
```

--------------------------------

### Table of object versions with member count (Overpass QL)

Source: https://wiki.openstreetmap.org/wiki/Overpass_API/Advanced_examples

Extends the previous version table by adding a count column using count_members(). The example relation 2632934 had an exceptionally large number of members starting at version 99, as shown in the sample output.

```overpass
[out:csv(version,timestamp,changeset,count)];
timeline(relation,2632934);
for (t["created"])
{
  retro(_.val)
  {
    rel(2632934);
    make stat version=u(version()),timestamp=u(timestamp()),changeset=u(changeset()),count=u(count_members());
    out;
  }
}

```

```text
98	2018-12-10T15:05:22Z	343
99	2018-12-13T16:54:37Z	21002
100	2018-12-13T19:52:55Z	20846
101	2018-12-18T19:52:21Z	20910
102	2018-12-26T00:50:19Z	21161
103	2018-12-26T15:07:55Z	21097
104	2019-01-03T17:17:59Z	21223
105	2019-01-12T19:08:11Z	21223
106	2019-02-11T09:29:28Z	42698
107	2019-02-11T11:22:29Z	350

```

--------------------------------

### Run apply_osc_to_db.sh with --meta

Source: https://wiki.openstreetmap.org/wiki/Overpass_API/Installation

Adds metadata to the database. Use this instead of the basic command when metadata is required.

```bash
nohup ./apply_osc_to_db.sh $REPLICATE_DIR/ $FIRST_MINDIFF_ID --meta &

```

--------------------------------

### Date setting example

Source: https://wiki.openstreetmap.org/wiki/Overpass_API/Overpass_QL

Queries the database state as of the given ISO 8601 timestamp. Attic data is not available before 2012-09-12T06:55:00Z; earlier dates return that state.

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

--------------------------------

### Run apply_osc_to_db.sh with --meta=attic

Source: https://wiki.openstreetmap.org/wiki/Overpass_API/Installation

Updates a database containing attic data. This command includes the --meta=attic parameter.

```bash
nohup ./apply_osc_to_db.sh $REPLICATE_DIR/ $FIRST_MINDIFF_ID --meta=attic &

```

--------------------------------

### Overpass API Map Endpoint Example

Source: https://wiki.openstreetmap.org/wiki/Overpass_API/XAPI_Compatibility_Layer

Example usage of the /api/map endpoint, which is also used by the OpenStreetMap Export feature.

```text
https://overpass-api.de/api/map?bbox=7.04717,50.95702,7.05125,50.95856
```

--------------------------------

### Run fetch_osc.sh to download diffs

Source: https://wiki.openstreetmap.org/wiki/Overpass_API/Installation

Starts a daemon that downloads all diffs from $FIRST_MINDIFF_ID to the present into the replicate directory. If kept running, it will automatically download new diffs as they become available. Omit this command if you obtain diffs through another method.

```bash
nohup ./fetch_osc.sh $FIRST_MINDIFF_ID https://planet.openstreetmap.org/replication/minute/ $REPLICATE_DIR/ &

```

--------------------------------

### Start rules loop daemon

Source: https://wiki.openstreetmap.org/wiki/Overpass_API/Installation

Start the rule batch processor as a daemon. This process generates areas from existing data in batch runs.

```bash
nohup $EXEC_DIR/bin/rules_loop.sh $DB_DIR &
```

--------------------------------

### Create post-install script for RPM package

Source: https://wiki.openstreetmap.org/wiki/Overpass_API/Installation

Post-install script for the RPM package. It moves the systemd unit file to /etc/systemd/system and creates the database directory.

```bash
$ vim post-install
#!/bin/bash
 
mv /usr/local/osm3s/bin/overpass-api.service /etc/systemd/system
mkdir -p /var/lib/osm3s/data/db

```

--------------------------------

### Step-by-step backward recursion

Source: https://wiki.openstreetmap.org/wiki/Overpass_API/Overpass_API_by_Example

Demonstrates manual backward resolution using rel(bn), way(bn), and rel(bw) instead of the < operator.

```Overpass QL
(
  node(50.746,7.154,50.748,7.157);
  rel(bn)->.x;
  way(bn);
  rel(bw);
);
out meta;
```

--------------------------------

### Run apply_osc_to_db.sh with --augmented_diffs=no

Source: https://wiki.openstreetmap.org/wiki/Overpass_API/Installation

Latest versions require the additional parameter --augmented_diffs=no. This command starts the daemon that keeps the database up to date.

```bash
nohup ./apply_osc_to_db.sh $REPLICATE_DIR/ $FIRST_MINDIFF_ID --augmented_diffs=no &

```

--------------------------------

### Body print mode example (Overpass XML)

Source: https://wiki.openstreetmap.org/wiki/Overpass_API/Language_Guide

Example of the default body print mode in XML. It queries for a node with name 'Gielgen' and place 'suburb', then prints the result.

```XML
<osm-script>
  <query type="node">
    <has-kv k="name" v="Gielgen"/>
    <has-kv k="place" v="suburb"/>
  </query>
  <print/>
</osm-script>

```

--------------------------------

### Find ways with tag in bbox (Overpass QL and XML)

Source: https://wiki.openstreetmap.org/wiki/Overpass_API

Overpass QL and XML examples that find ways with a specific tag within a bounding box. The QL shows a longer version using recurse and a shorter alternative; the XML uses bbox-query, recurse, and item in query.

```overpassql
node(51.15,7.0,51.35,7.3);
way(bn);
way._[highway=motorway];
out body;

//shorter alternative://

way(51.15,7.0,51.35,7.3)[highway=motorway];
out body;
```

```xml
<osm-script><bbox-query s="51.15" n="51.35" w="7.0" e="7.3"/>
<recurse type="node-way"/>
<query type="way">
  <item/>
  <has-kv k="highway" v="motorway"/>
</query>
<print/></osm-script>
```

--------------------------------

### Create systemd unit file for Overpass API dispatcher

Source: https://wiki.openstreetmap.org/wiki/Overpass_API/Installation

Create a systemd unit file for the Overpass API dispatcher daemon. The service starts the dispatcher with the --osm-base flag and a database directory, and stops it with --terminate.

```bash
$ vim overpass-api.service
[Unit]
Description=Overpass API dispatcher daemon
After=syslog.target
 
[Service]
Type=simple
ExecStart=/usr/local/osm3s/bin/dispatcher --osm-base --db-dir=/var/lib/osm3s/data/db
ExecStop=/usr/local/osm3s/bin/dispatcher --terminate
 
[Install]
WantedBy=multi-user.target

```

--------------------------------

### Send Overpass QL query via fetch and view JSON response

Source: https://wiki.openstreetmap.org/wiki/Overpass_API

Quick Start example for developers: sends an Overpass QL query with a bounding box, JSON output, and a 90-second timeout to the Overpass API interpreter via a JavaScript fetch POST request, then logs the JSON response. The displayed output is a truncated sample response; the full response can be viewed in the browser's Network tab under the last request's Response tab. The API works with any language and supports many output formats.

```javascript
var query = `
  [bbox:30.618338,-96.323712,30.591028,-96.330826]
  [out:json]
  [timeout:90]
  ;
  way(30.626917110746, -96.348809105664, 30.634468750236, -96.339893442898);
  out geom;
`;
var result = await fetch(
  "https://overpass-api.de/api/interpreter",
  {
    method: "POST",
    body: "data=" + encodeURIComponent(query),
  }
).then((data) => data.json());

console.log(JSON.stringify(result, null, 2));

```

```json
  {
    version: 0.6,
    generator: "Overpass API 0.7.61.5 4133829e",
    osm3s: {
      timestamp_osm_base: "2023-10-17T15:22:15Z",
      copyright: "The data included in this document is from www.openstreetmap.org. The data "...
    },
    elements: [
      {
        type: "way",
        id: 20714383,
        bounds: {
          minlat: 30.6277358,
          minlon: -96.341929,
          maxlat: 30.628834,
          maxlon: -96.340566
        },
        nodes: [ 222454378, 4204990218, 222454386 ],
        geometry: [
          { lat: 30.6277358, lon: -96.340566 },
          { lat: 30.6278459, lon: -96.3407026 },
          { lat: 30.628834, lon: -96.341929 }
        ],
        tags: {
          highway: "service",
          name: "W-X Street",
          postal_code: "77840",
          "tiger:county": "Brazos, TX"
        }
      },
 
 ...

```

--------------------------------

### URL-encoded bbox example

Source: https://wiki.openstreetmap.org/wiki/Overpass_API/Overpass_QL

Shows how to append a bbox as a separate variable in a URL-encoded query. The order is reversed (lon-lat) compared to the global bbox setting. This example finds post boxes in Bonn, Germany.

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

--------------------------------

### Clone Overpass database from dev server

Source: https://wiki.openstreetmap.org/wiki/Overpass_API/Installation

Fastest way to populate the Overpass database by cloning from the dev server. Use --meta=yes to include metadata (version numbers, editing users, timestamps) or --meta=attic for museum data (all old versions since the 2012 license change).

```bash
./download_clone.sh --db-dir=database_dir --source=https://dev.overpass-api.de/api_drolbr/ --meta=no

```

--------------------------------

### Resource management options: timeout and maxsize (Overpass QL and XML)

Source: https://wiki.openstreetmap.org/wiki/Overpass_API

Sets resource management options: timeout to 900 seconds (15 minutes) and element-limit to 1073741824 bytes (1 GiB). The QL version uses bracketed options at the start; the XML version uses attributes on osm-script. Warning: this example retrieves more than 100 MiB of data (flat list of nodes with tags) and may crash the browser tab if rendered on a map. These limits may be refused by the server or cause a query failure with a non-OK HTTP status.

```overpass-ql
[timeout:900][maxsize:1073741824];
node(51.15,7.0,51.35,7.3);
out;

```

```xml
<osm-script><osm-script timeout="900" element-limit="1073741824">
<bbox-query s="51.15" w="7.0" n="51.35" e="7.3"/>
<print/>
</osm-script></osm-script>

```

--------------------------------

### Example output format of Overpass query with area IDs

Source: https://wiki.openstreetmap.org/wiki/Overpass_API/Advanced_examples

Shows the XML output format: each POI node is followed by its area IDs, and full area details are provided at the end. This example uses node 691566183 and area IDs 3600435511 and 3600442466.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<osm version="0.6" generator="Overpass API">
  <node id="691566183" lat="49.7982193" lon="13.4686623">
    <tag k="ele" v="295"/>
    <tag k="information" v="guidepost"/>
    <tag k="name" v="Dolanský most (pravý břeh)"/>
    <tag k="tourism" v="information"/>
  </node>
  <area id="3600435511"/>
  <area id="3600442466"/>
  <node id="691566191" lat="49.8003120" lon="13.4679726">
    <tag k="ele" v="295"/>
    <tag k="information" v="guidepost"/>
    <tag k="name" v="Dolanský most (levý břeh)"/>
    <tag k="tourism" v="information"/>
  </node>
  <area id="3600435511"/>
  <area id="3600442466"/>
[...]
  <area id="3600435511">
    <tag k="admin_level" v="4"/>
    <tag k="boundary" v="administrative"/>
    <tag k="name" v="Jihozápad"/>
    <tag k="name:cs" v="Jihozápad"/>
    <tag k="name:de" v="Südwesten"/>
    <tag k="population" v="1209298"/>
    <tag k="ref" v="CZ03"/>
    <tag k="ref:NUTS" v="CZ03"/>
    <tag k="source" v="cuzk:ruian"/>
    <tag k="source:population" v="csu:uir-zsj"/>
    <tag k="type" v="boundary"/>
    <tag k="wikipedia" v="cs:NUTS Jihozápad"/>
  </area>
  <area id="3600442466">
    <tag k="ISO3166-2" v="CZ-PL"/>
    <tag k="admin_level" v="6"/>
    <tag k="boundary" v="administrative"/>
    <tag k="name" v="Plzeňský kraj"/>
    <tag k="name:cs" v="Plzeňský kraj"/>
    <tag k="name:de" v="Region Pilsen"/>
    <tag k="name:ru" v="Пльзенский край"/>
    <tag k="population" v="572687"/>
    <tag k="ref" v="PL"/>
    <tag k="ref:NUTS" v="CZ032"/>
    <tag k="source" v="cuzk:ruian"/>
    <tag k="source:population" v="csu:uir-zsj"/>
    <tag k="type" v="boundary"/>
    <tag k="wikipedia" v="cs:Plzeňský kraj"/>
  </area>

```

--------------------------------

### Pub tour in Dublin (Overpass QL)

Source: https://wiki.openstreetmap.org/wiki/Overpass_API/Advanced_examples

Finds all pubs within 500m of a starting node, then recursively expands to include pubs within 500m of those, up to 100 iterations. Outputs the center points of the found pubs.

```Overpass QL
node(3470507586);   // starting here...
complete(100) { nwr[amenity=pub](around:500); };
out center;

```

--------------------------------

### Get all nodes newer than date from bbox

Source: https://wiki.openstreetmap.org/wiki/Overpass_API

Gets all nodes newer than a certain date from a bbox. The Overpass QL version uses node(newer:...) with a bbox; the XML version uses a bbox-query followed by a query with an item substatement and newer filter.

```overpass
node(newer:"2026-01-01T00:00:00Z")(51.2,7.05,51.35,7.3);
out body;

```

```xml
<osm-script><bbox-query s="51.2" n="51.35" w="7.05" e="7.3"/>
<query type="node">
  <item/>
  <newer than="2026-01-01T00:00:00Z"/>
</query>
<print mode="meta"/></osm-script>
```

--------------------------------

### Typical settings declaration line

Source: https://wiki.openstreetmap.org/wiki/Overpass_API/Overpass_QL

Shows a typical settings declaration for an Overpass Turbo server, setting output to JSON and timeout to 25 seconds.

```overpass
// This is a typical settings declaration line
// on an Overpass Turbo server
[out:json][timeout:25];
```
Tokens:
Raw