Documentation

overpass.ch runs the standard Overpass API. Everything you know about Overpass QL works unchanged. Only the URL is different, and it carries your API key.

Quick start

1. Create a free account and confirm your e-mail address.
2. Create an API key on the API keys page.
3. Send a query:

curl https://api.overpass.ch/v1/YOUR_API_KEY/interpreter \
  --data-urlencode 'data=[out:json][timeout:25];node["amenity"="drinking_water"](47.36,8.53,47.38,8.55);out;'

The response is a normal Overpass result. Its osm3s.timestamp_osm_base field tells you how fresh the data is.

New to Overpass QL? The query examples explain 93 common queries line by line, with live results.

Endpoints

Your personal base URL is https://api.overpass.ch/v1/<API_KEY>/.

On overpass.ch, /status shows the slots of your key: one for each query your plan can run at the same time. When you have used up the per-minute rate, it shows when the next request is allowed. Reading /status does not count towards the rate. The upstream /api/kill_my_queries endpoint is not available, because it would affect other customers.

Authentication

Put the key in the path, as above. That's the only option for tools that let you set a server URL but no headers. Alternatively, send it in a header:

curl https://api.overpass.ch/v1/interpreter -H "X-API-Key: YOUR_API_KEY" \
  --data-urlencode 'data=node(3470507586);out;'

Treat keys like passwords. For keys used in a browser, restrict them to your websites under API keys → Allowed referers. Requests from other sites then get HTTP 403. Revoked keys stop working immediately.

Limits & plans

Limits apply per account and are shared by all its keys.

• Requests per month count successful (HTTP 2xx) interpreter calls, cache hits included. The counter resets on the 1st of each month (UTC).
• Every account has a Maps plan as well, Maps Free unless you subscribe to another one. Its map tiles and elevation lookups count when they are more than those of your Overpass or Elevation plan; the larger of the two allowances applies.
• Requests per minute: on the free plan, a token bucket: you can send a full minute of requests at once, then it refills continuously. Paid plans have no per-minute limit; the parallel-query limit applies.
• Parallel is the number of queries that may run at the same time.
• Priority: when the server is busy, paid plans are served first. Free accounts can use at most half of the query slots on the server and wait at most 3 seconds for one; otherwise they get HTTP 503 server_busy and should retry a little later.

Every response includes X-RateLimit-Limit and X-RateLimit-Remaining. When a limit is hit you get HTTP 429 with a Retry-After header.

Timeout & maxsize

Overpass lets a query request a run time and memory budget with [timeout:…] and [maxsize:…] (or the timeout and element-limit attributes of <osm-script> in XML). We apply your plan as follows:

• Values above the plan maximum are lowered to it. The query still runs.
• If you set no value, we use the default timeout of your plan and a maxsize of 512 MiB (or the plan maximum, if lower).
• Other settings such as [out:…], [bbox:…], [date:…] and [diff:…] pass through unchanged.

The values that applied are returned in the X-Effective-Timeout (seconds) and X-Effective-Maxsize (bytes) response headers. The settings block must be the first statement of the query. A second settings block is rejected with HTTP 400.

Errors

Errors from Overpass itself (syntax errors, timeouts, “runtime error” remarks) are passed through unchanged; Overpass errors explained covers their causes and fixes. Errors from overpass.ch are JSON: {"error": "rate_limited", "message": "…"}.

Caching

Identical queries within 60 seconds are answered from a cache (X-Cache: HIT). Only successful responses up to 5 MiB are cached. To force a fresh result, send Cache-Control: no-cache.

Clients

Anything that speaks Overpass works. Use https://api.overpass.ch/v1/<KEY>/ for tools that add interpreter themselves, and https://api.overpass.ch/v1/<KEY>/interpreter where a full endpoint is expected.

Overpass Turbo

Open overpass-turbo.eu → Settings → General → Server and enter:

https://api.overpass.ch/v1/YOUR_API_KEY/

Keep the trailing slash. If you restrict the key to referers, add overpass-turbo.eu. More in the Overpass Turbo guide.

JOSM

Edit → Preferences → Download (enable expert mode if needed) → Overpass server URL:

https://api.overpass.ch/v1/YOUR_API_KEY/

JOSM sends no referer. Use a key without referer restrictions.

QGIS (QuickOSM)

QuickOSM → Parameters → Add a custom Overpass server: add https://api.overpass.ch/v1/YOUR_API_KEY/ (with the trailing slash; QuickOSM appends interpreter) and select it. Older versions read it from custom_config.json: see the QuickOSM guide.

Python, R, JavaScript

Step-by-step guides: Python (requests, overpy, overpass), OSMnx, osmdata for R.

import requests

URL = "https://api.overpass.ch/v1/YOUR_API_KEY/interpreter"
query = """
[out:json][timeout:60];
area["name"="Zürich"]["admin_level"="8"]->.a;
nwr(area.a)["shop"="bakery"];
out center;
"""
r = requests.post(URL, data={"data": query}, timeout=120)
r.raise_for_status()
for el in r.json()["elements"]:
    print(el.get("tags", {}).get("name"))

import osmnx as ox

ox.settings.overpass_url = "https://api.overpass.ch/v1/YOUR_API_KEY"
G = ox.graph_from_place("Bern, Switzerland", network_type="drive")

const res = await fetch("https://api.overpass.ch/v1/YOUR_API_KEY/interpreter", {
  method: "POST",
  body: new URLSearchParams({ data: '[out:json];node["amenity"="cafe"](47.36,8.53,47.38,8.55);out;' }),
});
if (!res.ok) throw new Error(await res.text());
const { elements } = await res.json();

library(osmdata)
set_overpass_url("https://api.overpass.ch/v1/YOUR_API_KEY/interpreter")
q <- opq("Lausanne") |> add_osm_feature("amenity", "fountain")
fountains <- osmdata_sf(q)

Elevation API

Height above sea level on land and depth at sea, for any point on Earth, with the same API key. Every plan includes it, and the Elevation plan offers it on its own. The answers follow the format of the Google Elevation API and Open Topo Data, so clients written for those work after changing the URL.

curl 'https://api.overpass.ch/v1/YOUR_API_KEY/elevation?locations=46.0207,7.7491|35.95,-5.6'

{
  "status": "OK",
  "results": [
    { "elevation": 1606.3, "location": { "lat": 46.0207, "lng": 7.7491 },
      "surface": "land", "dataset": "copernicus-glo90", "resolution": 90 },
    { "elevation": -678.3, "location": { "lat": 35.95, "lng": -5.6 },
      "surface": "sea", "dataset": "gebco-2026", "resolution": 460 }
  ],
  "lookups": 2
}

• locations: lat,lon|lat,lon|… or a Google encoded polyline as enc:…. For many locations, POST JSON instead: {"locations": [[lat, lon], …]} (objects with lat and lon or lng work too). Up to 10'000 locations per request on paid plans, 1,000 on Free.
• path with samples: points evenly spread along a line, as in the Google API. Each result then also has its distance from the start in metres.
• elevation is in metres, rounded to 0.1 m; negative at sea. It is null where there is no data. surface is land or sea; lakes and rivers count as land and return their water level.
• Usage: one lookup per location or sample, counted only for successful requests, against the monthly allowance of your plan (separate from Overpass requests). The X-Lookups and X-Lookups-Remaining headers show the count for this request and what is left this month.

Heights in Overpass results

Add elevation=1 to the URL of an Overpass query and every node, centre and geometry point of a JSON result gets an elevation field, right after its lon:

curl 'https://api.overpass.ch/v1/YOUR_API_KEY/interpreter?elevation=1' \
  --data-urlencode 'data=[out:json];nwr["tourism"="alpine_hut"](46.0,7.6,46.2,7.9);out center;'

It uses one lookup per point, on top of the Overpass request. The X-Elevation header says added, or why the result came back unchanged: output other than JSON, more than 200,000 points, an answer larger than 32 MiB, or not enough lookups left this month.

Route profiles

/elevation/profile takes a path (as above, or as a GPX file in the POST body) and samples it every 90 m, the spacing of the data. Set interval (metres, at least 10) or samples to change that. Long routes are sampled more coarsely so that they fit into one request. Besides the points, the answer has a summary:

"profile": { "distance_m": 5087, "ascent_m": 508.4, "descent_m": 338.4,
             "min_m": 2417.2, "max_m": 2913.1, "samples": 58, "interval_m": 89.2 }

curl https://api.overpass.ch/v1/YOUR_API_KEY/elevation/profile --data-binary @track.gpx

import requests

URL = "https://api.overpass.ch/v1/YOUR_API_KEY/elevation"
points = [[46.0207, 7.7491], [45.9763, 7.6586], [46.5300, 8.0000]]
r = requests.post(URL, json={"locations": points}, timeout=30)
r.raise_for_status()
for res in r.json()["results"]:
    print(res["location"], res["elevation"], res["surface"])

const res = await fetch("https://api.overpass.ch/v1/YOUR_API_KEY/elevation/profile", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ path: [[46.53, 10.45], [46.54, 10.43], [46.52, 10.46]] }),
});
const { profile, results } = await res.json();
console.log(`${profile.distance_m} m, +${profile.ascent_m} m / -${profile.descent_m} m`);

Ascent and descent ignore changes of less than 2 m, which filters out noise in the data. To write heights into a GPX file, see add elevation to a GPX file; for profiles of OpenStreetMap routes, the elevation examples.

Elevation data and accuracy

• Land: Copernicus DEM GLO-90, a worldwide 90 m grid from the TanDEM-X radar mission. Heights are above the EGM2008 geoid, which is close to mean sea level.
• It is a surface model: forests and large buildings are part of the height. Values are interpolated between grid points 90 m apart, so sharp summits read lower and narrow valleys higher than the real terrain. On needle-like peaks the difference is a few hundred metres: the Matterhorn reads 4,210 m instead of 4,478 m, Everest 8,696 m instead of 8,849 m. In villages, valleys and rolling terrain it is typically within a few metres (Zermatt: 1,606 m).
• Sea: the GEBCO grid (about 460 m) wherever Copernicus marks the ocean. Depths far from surveyed areas are estimates. Not for navigation.
• Good for altitude bands, regional analysis, long routes, maps and enriching places. Not for engineering, aviation, drones or navigation.

Map tiles

Vector map tiles of the whole world, ready-made MapLibre styles and terrain tiles, with the same key. Every plan includes 100,000 map tiles a month, and the Maps plans have more, with a subscription of their own. For a web page, create a key of the type “Maps only” and set its allowed referers: such a key works for the endpoints below and for nothing else.

new maplibregl.Map({
  container: "map",
  style: "https://api.overpass.ch/v1/YOUR_API_KEY/maps/styles/light.json?lang=de&terrain=1",
  center: [7.6586, 45.9763], zoom: 12, pitch: 60
});

• Outdoor colours trails by their SAC grade, as on Swiss signposts: yellow for hiking trails (T1), red for mountain trails (T2 and T3), blue for alpine trails (T4 to T6); graded trails show from zoom 11. It also shows tracks, via ferratas, huts, campsites, viewpoints, stations and stops, drinking water, peaks with their height, rock, glaciers and cliffs, with hillshading and contour lines. Marine colours the sea by depth and shades the sea floor, with depth contours, the coastline, ferry routes, lighthouses and lights, buoys and beacons in their colours, harbours, marinas, anchorages, wrecks and rocks; protected areas are outlined, since many reach out to sea. Its depths come from a grid of about 460 m and are not for navigation. Driving has wider roads and shows fuel stations, charging stations and car parks. Relief colours the land by height, with hillshading and contour lines, and needs MapLibre GL JS 5.6 or later, as marine does. Light, dark, white, grayscale and black are the Protomaps styles; white, grayscale and black have no points of interest, so that your own data stands out. Outdoor, marine and driving load a second set of icons, as MapLibre allows.
• Label languages for lang: ar, bg, cs, da, de, el, en, es, et, fa, fi, fr, ga, he, hi, hr, hu, id, it, ja, ko, lt, lv, mr, mt, ne, nl, no, pl, pt, ro, ru, sk, sl, sv, tr, uk, ur, vi, zh-Hans and zh-Hant. A region code such as de-CH uses its language. Places without a name in that language show their local name.
• The vector tiles follow the Protomaps basemap schema, version 4, with the layers boundaries, buildings, earth, landuse, places, pois, roads and water. They also contain a landcover layer for zooms 0 to 7, which our styles leave out; if you show it, credit ESA WorldCover (CC BY 4.0). The data comes from OpenStreetMap and Natural Earth and is updated every week; data_date in the TileJSON gives the date.
• Vector tiles go up to zoom 14, and maps enlarge zoom 14 for closer views. At street level this leaves out house numbers and most shops and restaurants. Terrain tiles go up to zoom 10, which matches the 90 m data.
• Terrain tiles store the height in the Mapbox Terrain-RGB format: height = −10000 + (R × 65536 + G × 256 + B) × 0.1 m. The sea is 0 m and lakes have their water level. MapLibre, Mapbox GL, deck.gl and maplibre-contour read this format; in your own style, add {"type": "raster-dem", "url": "https://api.overpass.ch/v1/KEY/maps/terrain.json"} as a source.
• Every vector or terrain tile answered with HTTP 200 counts as one map tile against the monthly allowance of your plan, which is separate from Overpass requests and elevation lookups. Tiles are sent with Cache-Control (one day for vector tiles, 30 days for terrain) and an ETag, so browsers keep them; a revalidation answered with 304 is free. A tile without data answers 204 and is free too.
• The free plans allow up to 1,200 tiles a minute; paid plans have no per-minute limit. When the monthly allowance is used up, tiles get HTTP 429 quota_exceeded until the next month or an upgrade. We send an e-mail at 80% and at 100% of each allowance.
• Other errors: 403 forbidden_referer (the website is not among the allowed referers of the key), 403 key_scope (a maps key used for Overpass or elevation), 403 no_map_tiles, 404 above the highest zoom, and 503 maps_unavailable or server_busy with Retry-After. Errors of map libraries and other tile services are explained in the guide Map tile API errors.

Code for Leaflet, OpenLayers and QGIS, and a live map, are on the map tiles page.

Attribution

The data is © OpenStreetMap contributors and available under the Open Database Licence. If you display or publish data obtained through overpass.ch, credit it as “© OpenStreetMap contributors” with a link to openstreetmap.org/copyright, and respect the share-alike terms for derived databases. We do not remove the copyright notice from responses.

Elevation data: when you publish or display elevation results, credit both sources. Use this notice:

Produced using Copernicus WorldDEM™-90 © DLR e.V. 2010-2014 and © Airbus Defence and Space GmbH 2014-2018 provided under COPERNICUS by the European Union and ESA; all rights reserved. Sea depths: GEBCO Compilation Group (2026) GEBCO 2026 Grid.

The organisations in charge of the Copernicus programme by law or by delegation do not incur any liability for any use of the Copernicus WorldDEM™-90. Neither they nor GEBCO endorse overpass.ch or your use of the data.

Map tiles: our styles and TileJSON carry the credits (overpass.ch, Protomaps, © OpenStreetMap), and MapLibre shows them in a corner of the map. Keep them visible. Maps with terrain show a short form of the Copernicus notice that links to the full notice above; the sea in terrain tiles is flat, so GEBCO is not used there. The marine style and the sea depth tiles credit GEBCO and say that the depths are not for navigation.

Fair use

• Use one account per person or organisation; do not create accounts to get around limits.
• Do not resell raw API access or expose your key publicly in unrestricted form (if you use a key in a public web page, set Allowed referers for it and tick “Reject requests without a referer”; do not publish keys anywhere else, for example in code repositories).
• Prefer bounding boxes and areas over planet-wide scans. For bulk exports of whole countries, planet extracts (for example from Geofabrik) are usually a better fit.

The full rules are in the terms of service. Questions? Contact us.