Overpass API

Find the Overpass API on Ubuntu 24.04 LTS image in the Azure Marketplace and select Create.

Choose your subscription, resource group and region. Select a VM size (Standard_B2s or larger) and provide your SSH public key for the azureuser account.

On the Networking tab, allow inbound 443 and 80 from the networks that should reach the service, and 22 from your management network only.

Leave the data disk that ships with the image in place. It is mounted at /srv/overpass and holds the OpenStreetMap database.

Select Review + create. First boot takes a few seconds while the virtual machine generates its own TLS key pair and starts the API.

az group create --name overpass-rg --location eastus
az vm image terms accept --urn sac1647283583153:overpass-api-ubuntu-24-04:default:latest
az vm create \
  --resource-group overpass-rg \
  --name overpass-vm \
  --image sac1647283583153:overpass-api-ubuntu-24-04:default:latest \
  --size Standard_B2s \
  --admin-username azureuser \
  --generate-ssh-keys \
  --public-ip-sku Standard
az vm open-port --resource-group overpass-rg --name overpass-vm --port 443 --priority 1001
az vm open-port --resource-group overpass-rg --name overpass-vm --port 80 --priority 1002

On first boot, every virtual machine writes its own endpoint details and certificate fingerprint to a root-only file. Read it as root:

sudo cat /root/overpass-credentials.txt

The file contains this machine's own values:

OVERPASS_URL=https://<your VM address>/ OVERPASS_API_ENDPOINT=https://<your VM address>/api/interpreter OVERPASS_STATUS_URL=https://<your VM address>/api/status OVERPASS_TLS_FINGERPRINT=<the SHA-256 fingerprint of this VM's certificate> OVERPASS_TLS_CERT=/etc/nginx/tls/overpass.crt OVERPASS_TLS_KEY=/etc/nginx/tls/overpass.key OVERPASS_DB_DIR=/srv/overpass/db

The certificate is self-signed and unique to this machine, so clients warn on first contact. The warning is meaningful. Compare the fingerprint in the credentials file with the one the server actually presents to confirm you are talking to the right machine:

echo | openssl s_client -connect 127.0.0.1:443 2>/dev/null | openssl x509 -noout -fingerprint -sha256

The two fingerprints must match. Step 14 covers replacing the certificate with one from a certificate authority.

Send Overpass QL queries as a form-encoded data parameter to /api/interpreter. This query asks for named cafes in central Luxembourg City and returns JSON:

curl -sk --data-urlencode 'data=[out:json][timeout:25]; node["amenity"="cafe"]["name"](49.60,6.10,49.63,6.15); out center 5;' https://127.0.0.1/api/interpreter

Real objects come back, with their tags, coordinates and OpenStreetMap identifiers:

Every response carries a copyright field, because Overpass emits the ODbL notice in its JSON and XML output automatically. Read the Data licence and attribution section before you publish anything built from these results.

From another machine, use your virtual machine's own address instead of the loopback address. First boot wrote it to the credentials file:

OVERPASS_URL=$(sudo grep -m1 '^OVERPASS_URL=' /root/overpass-credentials.txt | cut -d= -f2-);
PRIV=$(hostname -I | awk '{print $1}'); echo "From another machine, query: ${OVERPASS_URL}api/interpreter"; echo "Checking the same listener over this VM's own network address (${PRIV}):"; curl -sk --data-urlencode 'data=[out:json][timeout:25];node["amenity"="pharmacy"](49.60,6.10,49.63,6.15);out center 3;' "https://${PRIV}/api/interpreter" | head -12

The check above uses the virtual machine's private address, not the public one printed on the line before it. This is deliberate: an Azure virtual machine generally cannot reach its own public IP address from inside itself, because the address lives on the load balancer rather than on the network interface. A query to the public address from the machine itself hangs. That is not a fault in the server, so test the public address from another machine.

The -k flag tells curl to accept the self-signed certificate. Drop it once you have installed a certificate from a certificate authority (Step 14).

Open https://<your VM address>/ in a browser. The appliance landing page lists every endpoint and carries the data attribution:

Follow the Query form link to open the browser form that ships with Overpass API. Type or paste a query into the box:

Submit the query and the results come straight back in the browser:

Further down, the landing page shows a worked example and explains how to load your own region:

You can point Overpass Turbo at this server instead of a public one. In Turbo, open Settings and set the server to https://<your VM address>/api/. A browser does not trust the self-signed certificate until you accept it once by visiting the server directly, or install a certificate from a certificate authority as described in Step 14.

Query /api/status for the dispatcher's live state: how the server identifies you, the rate limit, how many query slots are free and what is running.

curl -sk https://127.0.0.1/api/status

Query /api/timestamp for the OpenStreetMap timestamp of the loaded data. This tells you how fresh your answers are:

curl -sk https://127.0.0.1/api/timestamp

On the image as shipped, this is the snapshot date of the bundled extract:

2026-09-01T20:20:50Z

The image ships with a generated area index, so you can select by administrative boundary or any named area instead of by coordinates. This query counts the pharmacies in Luxembourg by area name, not by bounding box:

curl -sk --data-urlencode 'data=[out:json][timeout:60]; area["name"="Luxembourg"]["boundary"="administrative"]->.searchArea; node["amenity"="pharmacy"](area.searchArea); out count;' https://127.0.0.1/api/interpreter

A systemd timer regenerates areas daily, using the same command upstream ships:

systemctl list-timers overpass-areas-update.timer --no-pager

After importing a new region, run the update by hand to rebuild the area index immediately instead of waiting for the timer. It takes seconds for a country-sized extract and considerably longer for the planet:

sudo systemctl start overpass-areas-update.service; systemctl show overpass-areas-update.service --property=Result --value

The command prints success. The unit is a oneshot, so it shows as inactive once it has finished, and systemctl status reports exit code 3 for that reason. Read the result property instead.

Overpass QL selects the output format in the query prologue. Use JSON for programmatic access, XML for the OpenStreetMap native format and CSV for spreadsheets and quick analysis.

curl -sk --data-urlencode 'data=[out:xml][timeout:25];node["amenity"="cafe"]["name"](49.61,6.12,49.62,6.13);out 2;' https://127.0.0.1/api/interpreter

curl -sk --data-urlencode 'data=[out:csv(::id,name,::lat,::lon)][timeout:25];node["amenity"="cafe"]["name"](49.60,6.10,49.63,6.15);out 5;' https://127.0.0.1/api/interpreter

The Overpass QL language reference is at https://wiki.openstreetmap.org/wiki/Overpass_API/Overpass_QL.

Check that the services are active, then list every port reachable from off the machine:

systemctl is-active overpass-dispatcher.service overpass-areas-dispatcher.service apache2.service nginx.service overpass-areas-update.timer

ss -tlnH | awk '{print $4}' | grep -vE '^(127\.|\[::1\])' | sed -E 's/.*:([0-9]+)$/\1/' | sort -un | tr '\n' ' '

The output is 22 80 443 and nothing else. Everything else in the appliance is bound to loopback or uses a Unix domain socket:

• apache2 hosts the query CGI on 127.0.0.1:8080 and is reachable only through nginx
• Both dispatchers communicate over Unix domain sockets in /srv/overpass/db plus POSIX shared memory, and open no TCP port at all

Under /api/, nginx serves an explicit allowlist and returns 404 for everything else. Without it, Apache's ScriptAlias would expose the whole cgi-bin directory. Several of its programs need data this image deliberately does not import, or advertise facilities that only the public servers run.

The six allowlisted endpoints are interpreter, status, timestamp, kill_my_queries, convert and map.

for e in interpreter status timestamp kill_my_queries convert map trigger_clone augmented_diff sketch-line; do printf '%-18s ' "$e"; curl -skI -o /dev/null -w '%{http_code}\n' "https://127.0.0.1/api/$e"; done

The six allowlisted endpoints answer; everything else returns 404.

To expose another endpoint, add its name to the allowlist regex in /etc/nginx/sites-available/sac-overpass and reload nginx. Nothing is removed from the installation. Only the front door is narrower than upstream's default.

If one of your queries runs too long, you can cancel your own queries, and only your own:

curl -sk https://127.0.0.1/api/kill_my_queries

Upstream's dispatcher defaults are sized for the public overpass-api.de hardware: 12 GiB of query space, 262,144 time units and no rate limit at all. On a Standard_B2s, the query space alone is three times the machine's RAM. This image therefore starts the dispatcher with limits chosen for the machine:

Setting Value here Upstream default What it does

--space 1 GiB 12 GiB Total memory across all running queries

--time 3600 262144 Total time units across all running queries

--rate-limit 2 0 (disabled) Concurrent queries from one client address

--allow-duplicate-queries yes no Whether an identical repeated query is accepted

Individual queries can ask for less with [timeout:N] (seconds, default 180) and [maxsize:N] (bytes, default 512 MiB) in the query prologue. A query that asks for more than the server allows is refused rather than accepted and then killed.

The last row needs explanation. Upstream refuses a byte-identical query from the same client until the first query's timeout window elapses. That is sound anti-abuse protection for a public server, but on a private appliance it would make a scheduled poll or a refreshing dashboard fail for up to three minutes at a time. This image allows repeats. If you expose the server to untrusted traffic, set the option back to no.

To change any of these limits, edit the unit and restart the service. First, show the current command line:

sudo grep -A2 '^ExecStart=' /etc/systemd/system/overpass-dispatcher.service

Set new values in /etc/systemd/system/overpass-dispatcher.service, then run sudo systemctl daemon-reload && sudo systemctl restart overpass-dispatcher.service. You can also change a limit live, without a restart, by calling the dispatcher with no --db-dir:

sudo /usr/local/overpass/bin/dispatcher --rate-limit=2 && sleep 1 && curl -sk https://127.0.0.1/api/status | grep -i 'rate limit'

nginx adds its own limits in /etc/nginx/conf.d/sac-overpass-limits.conf: 2 requests per second per client address with a burst of 10, and a cap of 4 concurrent connections to /api/. Clients over the limit receive 429.

The bundled Luxembourg extract lets the server work out of the box. Replacing it with your own region is the normal next step.

Pick your extract from Geofabrik at https://download.geofabrik.de/. Anything from a city to a continent works, and the full planet is available from https://planet.openstreetmap.org/. Overpass reads OpenStreetMap XML rather than PBF, so the download is streamed through osmium, which is already installed.

Import takes minutes for a country and many hours for the planet, so run large imports under screen or nohup. Stop the dispatchers first. update_database refuses to touch a database that a dispatcher is holding.

# 1. Download your region and verify it against Geofabrik's published checksum cd /srv/overpass sudo curl -fL -o region.osm.pbf https://download.geofabrik.de/europe/belgium-latest.osm.pbf sudo curl -fL -o region.osm.pbf.md5 https://download.geofabrik.de/europe/belgium-latest.osm.pbf.md5 sudo sed 's/ .*/ region.osm.pbf/' region.osm.pbf.md5 | md5sum -c # 2. Note the data timestamp and replication sequence from the file header osmium fileinfo -g header.option.osmosis_replication_timestamp region.osm.pbf osmium fileinfo -g header.option.osmosis_replication_sequence_number region.osm.pbf # 3. Stop the dispatchers and clear the old database sudo systemctl stop overpass-areas-dispatcher.service overpass-dispatcher.service sudo rm -rf /srv/overpass/db/* # 4. Import. --map-compression-method=lz4 is not optional: without it the .map files are # written uncompressed and a country sized extract produces a database several times # larger than it needs to be.
sudo -u overpass bash -c 'osmium cat -f osm /srv/overpass/region.osm.pbf \
  | /usr/local/overpass/bin/update_database --db-dir=/srv/overpass/db/ --meta \
  --version=2026-09-01T20:20:50Z \
  --compression-method=lz4 --map-compression-method=lz4'
# 5. Put the area rules back, record the replication start point, restart, rebuild areas
sudo cp -pR /usr/local/overpass/rules /usr/local/overpass/templates /srv/overpass/db/ echo 4897 | sudo -u overpass tee /srv/overpass/db/replicate_id
sudo chown -R overpass:overpass /srv/overpass/db
sudo systemctl start overpass-dispatcher.service overpass-areas-dispatcher.service
sudo systemctl start overpass-areas-update.service
sudo rm -f /srv/overpass/region.osm.pbf /srv/overpass/region.osm.pbf.md5

Substitute the timestamp and sequence number you read in part 2 of the script. The --version value is what /api/timestamp reports, so it must be correct for your users to judge how fresh your data is.

Sizing, measured on this image: a 47 MB Luxembourg extract produces a 2.2 GB database with lz4 compression and roughly 17 GB without it. Scale from there and leave headroom. Overpass depends heavily on the page cache, so a database that fits comfortably in RAM answers much faster than one that does not.

A larger region needs a larger volume. You can expand Azure managed disks in place, but you must deallocate the virtual machine first.

# From your workstation, with the VM deallocated az vm deallocate --resource-group overpass-rg --name overpass-vm
DISK=$(az vm show -g overpass-rg -n overpass-vm --query "storageProfile.dataDisks[0].name" -o tsv)
az disk update --resource-group overpass-rg --name "$DISK" --size-gb 256
az vm start --resource-group overpass-rg --name overpass-vm
# Then on the VM, grow the filesystem onto the new space
sudo resize2fs /dev/disk/azure/scsi1/lun0 df -h /srv/overpass

Disks can be grown but not shrunk, so increase the size in steps you are comfortable paying for.

A snapshot ages. Overpass ships a pair of daemons that fetch replication diffs and apply them continuously. Which diffs you want depends on what you imported.

If you imported the full planet, use the OpenStreetMap minute diffs. This is the setup upstream documents, and it keeps a planet database within a couple of minutes of live:

sudo -u overpass mkdir -p /srv/overpass/diffs
sudo -u overpass nohup /usr/local/overpass/bin/fetch_osc.sh auto \
  "https://planet.openstreetmap.org/replication/minute/" "/srv/overpass/diffs/" &
sudo -u overpass nohup /usr/local/overpass/bin/apply_osc_to_db.sh \
  "/srv/overpass/diffs/" auto --meta=yes &

If you imported a regional extract, minute diffs are the wrong source. They are planet-wide, and applying them to a region does not give the result you expect. Geofabrik publishes per-region daily updates instead, at the replication URL recorded in the file header when you imported. The image records both values for the bundled extract, so you do not have to work out where in the stream your snapshot sits:

cat /srv/overpass/db/replicate_id;
cat /srv/overpass/db/replicate_base_url

Point fetch_osc.sh at that base URL instead of the planet one. Region updates are daily, not minutely. Geofabrik's per-region diffs require a free account for some regions, as described at https://download.geofabrik.de/technical.html.

If you prefer not to run diffs, re-import a fresh extract on a schedule (Step 11). This alternative is simpler to reason about.

If the database is updated continuously, the daily area rebuild may be too infrequent. Upstream's rules_loop.sh regenerates areas in a continuous loop. This image uses a daily timer because a database that changes only when you change it does not need a permanent background job on two vCPUs.

The certificate generated at first boot is self-signed, which suits a machine that has no DNS name yet. Replace it once the machine has one.

# With a certificate authority, for example Let's Encrypt sudo apt-get install -y certbot sudo certbot certonly --standalone -d overpass.example.com sudo ln -sf /etc/letsencrypt/live/overpass.example.com/fullchain.pem /etc/nginx/tls/overpass.crt sudo ln -sf /etc/letsencrypt/live/overpass.example.com/privkey.pem /etc/nginx/tls/overpass.key sudo nginx -t && sudo systemctl reload nginx

certbot --standalone needs port 80 free. Stop nginx while the certificate is issued and start it again afterwards, or use the webroot plugin against /var/www/overpass.

To bring your own certificate, put the full chain at /etc/nginx/tls/overpass.crt and the private key at /etc/nginx/tls/overpass.key with mode 0600. Then run sudo nginx -t && sudo systemctl reload nginx.

Run the self test that ships with the image. It exercises the appliance the way a customer meets it: both dispatchers, the TLS front, the certificate identity, every allowlisted endpoint, a real query returning real objects, the area index, the attribution, the database shape and the complete set of network-facing ports.

sudo /usr/local/bin/overpass-selftest

Every line must read ok and the last line must read PASS.

You can also run a few checks by hand:

curl -sk -o /dev/null -w 'landing page: %{http_code}\n' https://127.0.0.1/ ; curl -s -o /dev/null -w 'port 80 redirect: %{http_code}\n' http://127.0.0.1/

du -sh /srv/overpass/db && df -h /srv/overpass | tail -1