Overpass JSON — Roland Olbricht's Query Language for OpenStreetMap Tags

Overpass JSON is the output format of the Overpass API, a read-only query language over OpenStreetMap developed by Roland Olbricht as an AGPL FOSS project since around 2008. Unlike planet PBF dumps that ship everything at once and require local processing on 100+ GB disks, Overpass lets you extract data by tags: «all cafes in the Moscow bbox», «all hospitals inside a region polygon», «all parking lots within a 500-meter radius of a point». Output in [out:json] mode is a compact JSON document with a list of elements (node/way/relation) and their geometry plus tags, parseable directly in JavaScript, Python, R, and any modern language. Overpass JSON became the backbone for overpass-turbo.eu (Martin Raifer's web GUI), osmnx (Geoff Boeing, street networks for academic research), the QGIS QuickOSM plugin, the R osmdata package, and dozens of ETL pipelines where OSM is used not as a map but as a structured geospatial dataset. On osm2cdr.ru the overpass-json export returns raw OSM features from a bbox in native Overpass JSON spec — this lets downstream tooling work with our extract without issuing a separate query to the public Overpass instance.

History: Roland Olbricht 2008 → C++ rewrite 2013 → Geofabrik mirror

Overpass API was born in 2008 as a single-developer project by Roland Olbricht — an independent German developer working on geographic query-engine optimization. The original motivation was that Roland wanted a tool to extract OSM objects via complex tag filters without dumping the entire planet; the standard OSM API (xapi, later the main editing API) was not suited for read-heavy analytical queries, and a planet PBF dump required your own infrastructure. The first version of Overpass was in Perl, a prototype proving the idea of slot-based concurrency and query-cost limits as protection against runaway requests.

In 2013 Roland rewrote the engine in C++, yielding a 10–50x speedup and making production deployment under high load feasible. The same period brought a custom file-based DB with tag indices and spatial indices (R-tree), and 2014 added the attic feature — an indexed history of every OSM change that allows querying the state of the map at an arbitrary date via [date:"2020-01-01T00:00:00Z"]. That requires ~500 GB of disk for full planet history but unlocks temporal analysis like «how did the bicycle network of Berlin evolve from 2015 to 2020».

The public instance overpass-api.de is hosted in Bonn (Germany) by Geofabrik (Frederik Ramm) — a long-time OSM contributor and founder of one of the main commercial OSM-extracts providers. Geofabrik covers hosting, while Roland maintains the codebase and engine. Alternative public mirrors include kumi.systems in Austria (Kumi Systems), lz4.overpass-api.de (LZ4-compressed mirror), and maps.mail.ru/osm/tools/overpass (Russian mirror by Mail.Ru, updated with delay). All synchronize from the master planet every ~60 seconds through diff replication.

In 2014 Martin Raifer (Austria) released overpass-turbo.eu — a web-based GUI for Overpass with a built-in Wizard that turns natural-language hints like «cafe in Vienna» into Overpass QL. Turbo became the de facto front-end for most OSM-data-mining workflows: journalists, urban planners, researchers, and mappers use it daily. By 2026 overpass-turbo processes millions of queries per month and ranks among the most popular OSM tools alongside the iD editor.

Inside Overpass QL: filters, recursive operators, output modes

Overpass QL (Query Language) is a compact-syntax DSL with C-like statement terminators (;). The basic query template is always the same: header settings → filters → output.

[out:json][timeout:25];
node[amenity=cafe](around:1000,55.7558,37.6173);
out body;

This query reads: «return as JSON all nodes with the amenity=cafe tag within a 1000-meter radius of Red Square coordinates, with full data (geometry + tags + metadata)». Timeout is 25 seconds maximum processing.

Output modes. The header [out:json] (or [out:xml], [out:csv], [out:custom]) defines the output format. The final out statement determines the level of detail: out (id + type only), out skel (skeleton with references but no tags), out body (full id + references + tags + metadata, the default for most use cases), out tags (id + type + tags, no geometry references), out geom (adds inline geometry for ways/relations so each node ref resolves to {lat, lon}, making JSON self-contained), out center (for ways/relations returns only bounding-box center, useful for POI markers without the full polygon).

Recursive operators. The most powerful and initially confusing part of Overpass: > («down») adds all member nodes for every selected way/relation, required for getting polygon geometry through out:json without out geom; < («up») adds all ways using a given node and all relations containing it as a member; >> and << are recursive (transitive closure) versions.

Area queries. Overpass can convert relations with boundary=administrative or place=* tags into areas — a special type you can filter contents by. For example:

area[name="Москва"][admin_level=4]->.region;
node[amenity=hospital](area.region);
out body;

That is «all hospitals within the administrative boundary of Moscow», without needing to declare an explicit bbox or polygon. Areas are computed by the Overpass server once a day and stored as a materialized index.

Spatial filters. Three main ones: (south,west,north,east) for bbox; (around:radius,lat,lon) for circle; (poly:"lat1 lon1 lat2 lon2 ...") for an arbitrary polygon. All can combine with tag filters in a single statement.

Attic queries. [date:"2020-01-01T00:00:00Z"] in the header returns OSM state at that date. [diff:"2020-01-01T00:00:00Z","2025-01-01T00:00:00Z"] returns the diff between two dates (what was added/removed/changed). This is a unique Overpass feature — no other OSM API offers temporal queries out of the box.

Use cases: data mining, ETL, real-time editing, academic research

Data exploration via overpass-turbo. The most common use case. A journalist wants to know how many Wildberries pickup points exist in a city — they write node[shop=convenience][brand="Wildberries"]({{bbox}}), see the result on the map, export GeoJSON. An urban planner analyzes school distribution across districts, discovering a deficit in new housing developments. A mapper looks for duplicate POIs after a government-data import. The Wizard in Turbo generates queries from natural-language hints, lowering the entry barrier.

ETL pipelines via osmnx. OSMnx (Geoff Boeing, paper «OSMnx: New methods for acquiring, constructing, analyzing, and visualizing complex street networks», 2017, Computers, Environment and Urban Systems) is a Python library that builds Overpass queries automatically under the hood. You write ox.graph_from_place("Moscow, Russia", network_type="drive"), the library generates Overpass QL, parses the JSON response, builds a NetworkX street graph with topology and attributes, ready for centrality analysis, routing, and accessibility studies. OSMnx has become a standard in the academic urban-research community — cited in thousands of papers on transport, public health, and urban design.

Real-time map editor validation. iD editor (the main OSM web editor) and RapiD (Meta/Facebook fork with ML-suggested geometries) use Overpass for validation queries during editing. When a mapper saves a building, the editor can query nearby OSM objects for cross-validation — does a duplicate building exist, does it intersect an existing building. These validation queries amount to millions of requests per day against public overpass-api.de.

Academic research. Tag statistics for taginfo (Jochen Topf) partly come from Overpass (although the main source is planet PBF). Research papers on tags, brand coverage, completeness analysis — all use Overpass as their primary data source. Example: «coverage of EV charging infrastructure in the EU» — a single Overpass query on node[amenity=charging_station](area.eu).

LLM tool use. Throughout 2024–2025, the practice of connecting Overpass as a tool for LLM agents emerged (via MCP servers, LangChain tools). An agent answering «how many pizzerias are there in Berlin» writes an Overpass query, parses the JSON, returns a count. That is much cheaper and more accurate than calling the Google Places API.

Limits, etiquette, and self-hosting

Public overpass-api.de is a shared community resource with strict usage rules. By default each IP gets 2 slots × 10 seconds of processing time per slot. The slot frees upon query completion; if both are busy, new requests get HTTP 429 Too Many Requests or queue up. Heavy queries (large bbox + complex filters) can consume the entire slot budget and fail with HTTP 504 Gateway Timeout.

Hard limits of the public instance: max query timeout 180 seconds ([timeout:180]), max memory per query ~512 MB ([maxsize:536870912]), slot budget 2 × 10 sec/slot for anonymous, potentially higher for known clients (custom User-Agent with contact email).

Etiquette rules (documented on overpass-api.de): always set User-Agent with contact email or project URL (anonymous requests are rate-limited more aggressively); cache results client-side; for batch processing (thousands of queries per hour) — self-host, do not hammer the public instance; respect Retry-After headers on 429 responses.

Self-hosting. For production workloads with continuous query streams, the single way forward is self-hosted Overpass. The community-maintained Docker image wiktorn/overpass-api (derived from reference build) needs 100–200 GB SSD for full planet without attic, 500 GB with attic history, 8–16 GB RAM. Bootstrap takes ~10–20 hours (download PBF + osm3s converter + indices generation), then continuous replication from planet.openstreetmap.org diff stream with 60-sec lag. After bootstrap a self-hosted instance sustains hundreds of requests/sec on single-server hardware — standard practice for commercial geospatial startups and urban-research institutions.

Strengths and weaknesses

Strengths. Tag-based selectivity is the key advantage over PBF dumps: you do not need to download 100 GB to get all pharmacies in one city. Read-only — no risk of breaking OSM editing, query-only is safe for production. Attic queries — the only OSM API with built-in temporal dimension. Recursive operators — powerful high-level constructs for ways/relations resolution in a single request. Multiple output formats — JSON, XML, CSV, custom templates. A huge ecosystem of downstream tools (overpass-turbo, osmnx, QuickOSM, osmdata). Public instances are free for reasonable use. Self-hosting is documented and production-proven. AGPL license guarantees open-source forever. Active maintenance by Roland plus Geofabrik infrastructure support.

Weaknesses. Read-only — you cannot edit OSM through Overpass, you need the main API. Public-instance rate limits — unsuitable for batch processing. Slot-based cost system, not token-based — hard to predict query cost ahead of execution, only heuristics. Overpass QL learning curve — syntax is non-obvious for beginners (; terminators, ->.set semantics, recursive operators). JSON output overhead — for very large results (millions of elements) JSON parsing is more expensive than PBF. Latency of public instance — typically 1–10 seconds per query due to shared load, slow for real-time UX. Replication lag of ~60 seconds — applications requiring real-time edits need custom infrastructure. Self-hosting is non-trivial — 10–20 hour bootstrap, replication-state maintenance requires monitoring. Documentation sometimes lags behind engine features — community wiki is the primary source.

Workflow in OSM2CDR

Our backend uses its own PostGIS database with the full planet (osm2pgsql import, ~1.4 TB on NVMe) rather than delegating queries to the public Overpass. That gives us predictable latency (< 1 sec for a typical bbox), no rate limits, and the ability to maintain custom indexes for specific workloads (for example, materialized views for popular tag combinations).

At the same time we support export to Overpass JSON format — a user selects overpass-json in the Format Wizard, specifies a bbox and optional tag filter, and gets a downloadable JSON byte-compatible with public Overpass API output. This allows: using our extract as a drop-in replacement for an overpass-api.de query in downstream tooling (osmnx, QuickOSM) — just swap the URL; getting data for bboxes exceeding public-instance limits (we do not have the 180-sec timeout); reproducing exact JSON for archived queries (our DB snapshot does not change until the next planned rebuild, unlike the continuously-replicating public instance).

Step 1: Parse parameters. Frontend sends a bbox {south, west, north, east} and an optional tag_filter as an Overpass-QL fragment ([amenity=cafe]). Backend validates bbox limits per user tier (free — up to 100 km², pro — up to 10000 km²).

Step 2: PostGIS query. From PostGIS we extract nodes/ways/relations falling within the bbox via ST_Intersects(way, ST_MakeEnvelope(...)). The tag filter is applied via JSONB tags @> '{"amenity": "cafe"}'. Materialized views for popular categories (mv_amenities, mv_buildings, mv_highways) accelerate hot queries.

Step 3: Serialization. PostGIS rows convert to Overpass JSON schema: {"version": 0.6, "generator": "osm2cdr Overpass-compatible", "elements": [...]}, where each element has type (node/way/relation), id, lat/lon (for nodes), nodes (array of node refs for ways), members (for relations), tags (dict). Metadata (version, timestamp, user) is optionally included by the include_meta flag.

Step 4: Geometry enrichment. Under the inline_geometry flag (equivalent to Overpass out geom), for each way we resolve node refs into coordinates and embed them as a geometry array, making the JSON self-contained.

Step 5: Stream response. For large results (>10 MB JSON) we use a streaming response with application/json content-type and chunked transfer encoding — the client can begin parsing before the full payload arrives.

Compatibility. Output is validated through the overpy parser (Roland Olbricht, pip overpy) — if overpy successfully parses our JSON into objects, the format is considered compatible. We also test via osmnx — ox.geometries_from_xml(our_output_converted_to_xml) must work without errors.

FAQ

How does Overpass differ from the main OSM API? The main OSM API (api.openstreetmap.org/api/0.6) is an editing API for iD/JOSM/Vespucci: GET/PUT/POST for creating and modifying objects. Overpass is a read-only query API optimized for tag-based and spatial filters over a snapshot database. Editing through Overpass is impossible. Need to edit OSM — main API. Need to extract data — Overpass.

Can I use Overpass commercially? Yes, both the license and terms allow it. The engine is AGPL — if you modify the engine and provide it as a service, you must open the sources. Use of the public instance is bound by the usage policy (rate limits, attribution); commercial use is allowed if you respect limits. Heavy commercial use → self-host is mandatory.

Overpass vs PBF dump — which to pick? A PBF dump (planet.openstreetmap.org or Geofabrik extracts) is for bulk processing locally: you download an 80 GB file and process via osmium, osm2pgsql, pyrosm. Overpass is for selective queries by tags without full download. Rule of thumb: regularly need <10% of planet data — Overpass. Need everything for batch ETL — PBF.

What is a slot and why did my query fail with 504? The public Overpass instance has cost-management through slots. Each IP gets 2 parallel slots, each slot — 10 sec of CPU time. If a query exceeds that (large bbox + complex filter), it returns 504 Gateway Timeout. Solutions: shrink the bbox, simplify the filter, add [timeout:N] (helps if the request times out on the default 180), or self-host for production.

Does Overpass support WebSocket / streaming? No, classic request-response HTTP. Streaming partial results is not possible — a query either completes and returns full JSON, or fails on timeout. For real-time use you need other approaches (webhooks on OSM changesets, custom infrastructure).

What alternatives to Overpass exist? Osmosis + osm2pgsql + PostgreSQL — self-hosted alternative with SQL instead of Overpass QL, requires DBA expertise. pyrosm (Python) — filters PBF files in-memory via PyArrow, fast for known regions. Protomaps Daylight — curated OSM-derivative distribution with ML validation. Geofabrik extracts — regional PBF files if you need countries/cities separately. Overpass is unique exactly as a public query API with low-latency selective access.

Conclusion

Overpass JSON is the lingua franca of OSM data extraction beyond simple cartography. Roland Olbricht created the tool that turned OpenStreetMap from a «map editing platform» into a queryable structured geospatial dataset; Geofabrik provides infrastructure, Martin Raifer built overpass-turbo for casual users, Geoff Boeing integrated it into the academic Python ecosystem via osmnx — and as a result Overpass JSON became the underground standard for everyone working with OSM data analytically rather than as a mapper. Strengths — selectivity, attic queries, a huge ecosystem. Weaknesses — read-only, public-instance rate limits, the QL learning curve.

On osm2cdr.ru we provide Overpass JSON export through /api/render with format overpass-json — byte-compatible JSON with public Overpass output but without rate limits and with predictable latency. Use it as a drop-in for osmnx, QuickOSM, custom Python parsers, or as an archive snapshot for reproducible studies.

Try exporting OSM to Overpass JSON for your region and feed the result into osmnx or QuickOSM for further analysis.

Related

• OSM XML — the primary exchange format of OpenStreetMap
• OSM PBF — compact binary planet dump of OpenStreetMap
• GeoJSON — simple JSON standard for vector geodata
• WKT — OGC well-known text representation of geometry

Sources

• Overpass API official site (Roland Olbricht) — overpass-api.de
• Overpass API GitHub (drolbr/Overpass-API) — github.com/drolbr/Overpass-API
• Overpass Turbo (Martin Raifer) — overpass-turbo.eu
• OSMnx documentation (Geoff Boeing) — osmnx.readthedocs.io
• Boeing G. «OSMnx: New methods for acquiring, constructing, analyzing, and visualizing complex street networks» (Computers, Environment and Urban Systems, 2017)
• OSM Wiki: Overpass API Language Guide — wiki.openstreetmap.org/wiki/Overpass_API/Language_Guide