Overpass

Overpass

Overpass API supplies everything Relatify knows about the map around a route:

• the roads (ways) a route can run over
• existing bus stops, stop positions and stop_area relations nearby
• which nodes are tagged highway=turning_circle

The relation itself does not come from Overpass. Its tags and members are read straight from the OSM API, so 404 Relation not found is an OSM API problem, not an Overpass one.

How many queries Relatify sends

The main public instance, overpass-api.de, gives each IP address two query slots. A slot is held for as long as the query that took it runs, and the instance hands out roughly two queries a minute per address. A third query while both are in use is refused with HTTP 429 Too Many Requests.

Relatify keeps its own traffic inside that allowance:

Action	Overpass queries
Loading an existing route	2: the route's bounding box, then the area around it. The route masters its ref could join and the country (for driving side) are folded into the area query rather than sent separately.
Panning or zooming out	1, and only for grid cells not already downloaded.
Uploading changes that split a way	1 lookup of the other relations those ways belong to.
Looking up route masters on request (e.g. after changing the ref)	1.

The map is split into a grid of roughly 1 km cells (DOWNLOAD_RELATION_GRID_SIZE), and only cells you haven't fetched yet are queried. A long route is built up bit by bit rather than in one huge request.

Because the allowance is per address, several people using one Relatify server share it. On a busy shared server, expect to fall back to the second instance more often (see What happens on a 429).

Limitations

Regional extracts return nothing, successfully. An instance built from a country or regional extract (overpass.osm.ch, overpass.osm.jp, …) doesn't error outside its own area. It returns an empty result, which looks exactly like "nothing is mapped here". Only use worldwide instances.

Stale instances don't fail either. An instance that has fallen behind answers every query from an old snapshot. Editing from that data makes the app think stops or stop areas added since are missing, and offer to recreate them. overpass.kumi.systems and overpass.private.coffee, which this fork used to default to, both sat on a 2026-06-01 snapshot until September 2026 without returning a single error. Refusing stale data covers how this is now caught.

Not every instance can serve out meta. Splitting a way that belongs to other relations needs each relation's @version, which the OSM API requires to accept the edit. Instances built without metadata can't provide it. That rules out the Britain & Ireland instance (overpass.atownsend.org.uk), which is also IPv6-only.

Even a healthy instance lags live OSM, by seconds to a couple of minutes. Something you've just uploaded may not show up if you reload straight away.

Very large queries can time out. The area query's Overpass timeout grows with the number of grid cells, up to [timeout:180], and the app waits twice that long for the reply. The bounding-box and parent-relation lookups use a 60-second timeout, and the route master lookup 30 seconds. A brand-new relation's first download is limited to 256 grid cells; beyond that the app asks you to zoom in. Once started, panning downloads more as you go.

Public instances are shared. Rate limits and overload are normal, especially on the main instance at busy times. The mirror list and retry logic exist to absorb this.

Configuration

Variable	Purpose	Default
OVERPASS_API_INTERPRETER	Comma-separated Overpass endpoints, tried in order.	https://overpass-api.de/api/interpreter,https://maps.mail.ru/osm/tools/overpass/api/interpreter
OVERPASS_API_ATTEMPTS	Attempts on one endpoint before moving to the next.	2
OVERPASS_MAX_DATA_AGE	How far behind live OSM (in seconds) a reply may be before it's refused. 0 turns the check off.	3600 (1 hour)

The default pair is deliberate. overpass-api.de is the main public instance. maps.mail.ru covers the whole world and was measured about a minute behind live OSM, so it stands in when the main instance is busy or has no free slot.

To use something else, pick a worldwide instance from the wiki's public instance list, or run your own for heavy use. List as many as you like; they're tried strictly in order.

Refusing stale data

Every Overpass reply says how current its data is: timestamp_osm_base in JSON, osm_base on the <meta> element in XML. If that stamp is older than OVERPASS_MAX_DATA_AGE, the reply is thrown away and the next mirror is tried.

A healthy instance is normally seconds to a couple of minutes behind, so the one-hour default should never trigger on a working mirror. It exists for the six-weeks-stale case above.

Retries and fallback

Relatify works through the configured instances in order, making up to OVERPASS_API_ATTEMPTS attempts on each. Between attempts it waits 1 s, then 2 s, then 4 s, and so on, unless the instance has said how long to wait (see below).

What happens depends on the reply:

Reply	What Relatify does
Can't connect within 5 s, DNS or TLS failure, or the reply times out	Retry, then move to the next instance.
429	Ask the instance when a slot frees up (see below).
502, 503 or 504	Retry, then move to the next instance. These mean overload or a gateway timeout and are almost always temporary.
200, but the body is an error	Retry, then move to the next instance.
200 with data older than OVERPASS_MAX_DATA_AGE	Skip the rest of this instance's attempts and move to the next one. Asking again won't make it fresher.
Any other status (400, 401, 403, a 500, …)	Fail immediately, with no retry and no fallback. This usually means a malformed query or similar that another server won't fix.

If every instance is used up, the app returns one of the 503 errors in Errors you might see.

What happens on a 429

A 429 means both of this address's slots are busy. Retrying after a fixed second or two just gets refused again, so Relatify checks the instance's /api/status page, which says how many slots are free and when the next one is released:

• A slot is free, or frees up within 20 seconds: wait until then (plus a second) and retry the same instance.
• The wait is longer than 20 seconds, or the status page doesn't say: move straight to the next instance. It has its own slots, so it's quicker than waiting.

Errors hidden inside a 200

Overpass sometimes answers 200 OK when the query actually failed. Relatify treats both of these as failures:

• An HTML error page, usually when the instance is too busy to start the query:

  runtime error: open64: 0 Success /osm3s_osm_base Dispatcher_Client::request_read_and_idx::timeout. The server is probably too busy to handle your request.

• A remark in otherwise valid JSON/XML, meaning Overpass gave up partway through and returned only what it had so far:

  runtime error: Query timed out in "recurse" at line 1

  Without this check, a cut-off reply would look like an area with nothing in it.

Harmless remarks such as "considered 3 areas" are ignored. Only a remark containing the word "error" counts as a failure.

Errors you might see

The server console logs the reason for every failed attempt as an [OVERPASS] ⚠️ … line: whether the instance was unreachable (and why), returned a bad status, had no free slot, or answered with an error. Check there first.

What you see	Why	Fix
503 "Overpass API is currently unavailable, please try again later"	Every instance failed every attempt: rate-limited, overloaded, or answered with an error.	Wait and retry. If it happens often, add another mirror, raise OVERPASS_API_ATTEMPTS, or run your own instance.
503 "Could not reach any Overpass instance…"	No instance answered at all. This is almost always the network on the Relatify server's side, not Overpass.	Check the server's internet connection, DNS and firewall.
503 "Every Overpass instance is out of date - the closest, <url>, is <n> behind…"	Every instance that answered was older than OVERPASS_MAX_DATA_AGE.	Wait for one to catch up, or add a fresher mirror. Only set OVERPASS_MAX_DATA_AGE=0 if you accept the risk of duplicate stops.
500 Internal Server Error, no useful detail	An instance returned a status outside the retry set, such as its own 500 or a 400 for a malformed query.	Check the server console for the traceback. If the query looks fine, please report it.
400 "Zoom in before creating a relation; the visible area is too large to download."	A brand-new relation's first download would cover more than 256 grid cells. Not an Overpass error.	Zoom in, click Create again, then pan to extend the route.
Data looks out of date right after uploading	Overpass normally lags live OSM by seconds to a couple of minutes.	Wait a moment, then use ↻ Reload in the edit view.
Data is missing in one region, with no error	A regional-extract instance is configured and returns nothing outside its area.	Only list worldwide instances in OVERPASS_API_INTERPRETER.
Browser console: "Failed to fetch", no HTTP response	The browser couldn't reach Relatify's own server. Overpass problems still come back as a proper HTTP error.	Check the Relatify server is running.

In the app, a failed load shows as "❌ Relation load failed - 503" (or the relevant status). The browser console shows POST /query with the message above as the response body.

See also: New relations.