Get your first query running

Your endpoint

Every Overspan account has one endpoint. Your key arrives by email after checkout; there is no account to create and nothing to log into, because the key is the identity.

https://api.overspan.dev/YOUR_KEY/api/interpreter

That path mirrors the public servers deliberately. Anywhere a tool asks for an Overpass server, giving it the Overspan equivalent is a find-and-replace.

Passing your key

Three forms are accepted. They are equivalent; pick whichever your client makes easy.

First query

Cafes in central Auckland, with full metadata, to prove the key works:

curl -G https://api.overspan.dev/YOUR_KEY/api/interpreter \
  --data-urlencode 'data=[out:json][timeout:60];
    node[amenity=cafe](-36.86,174.75,-36.84,174.78);
    out meta 5;'

Elements come back carrying version, timestamp, changeset, user, and uid. That is out meta working, and it means output matches the public servers element for element.

To check how current the data is, read the base timestamp in the response envelope, or call the endpoint your client already uses for status. Overspan tracks the live OSM replication feed and normally sits within a couple of minutes of it.

Client setup

Note the trailing segments. Each of these tools appends something different to the base you give it, so the strings below are not interchangeable.

osmnx

osmnx appends /interpreter, so give it the /api base:

import osmnx as ox

ox.settings.overpass_url = "https://api.overspan.dev/YOUR_KEY/api"
ox.settings.requests_timeout = 60        # your tier's [timeout:] cap: 60 / 180 / 300
ox.settings.overpass_rate_limit = False  # the key is the identity; no /status probe

gdf = ox.features_from_place("Dunedin, New Zealand", {"amenity": "cafe"})

The two extra lines matter (verified against a real osmnx 2.1.1 run): osmnx writes requests_timeout into every query as its [timeout:], and a value above your tier's cap is rejected, which osmnx reports only as KeyError: 'elements'. And with overpass_rate_limit left on, osmnx probes a /status endpoint this API does not have before every query. On osmnx 1.x the URL setting is named ox.settings.overpass_endpoint and takes the same value.

JOSM

JOSM appends api/interpreter, so it wants the bare host and key:

https://api.overspan.dev/YOUR_KEY/

overpass-turbo

overpass-turbo appends interpreter:

https://api.overspan.dev/YOUR_KEY/api/

Plain Python

import requests

QUERY = """
[out:json][timeout:60];
area[name="Wellington"]->.a;
node[amenity=drinking_water](area.a);
out meta;
"""

r = requests.post(
    "https://api.overspan.dev/api/interpreter",
    data={"data": QUERY},
    headers={"Authorization": "Bearer YOUR_KEY"},
    timeout=90,          # leave room above the query's own timeout
)
r.raise_for_status()
data = r.json()

Your tier limits

All limits are enforced at the front door and none of them bill as overage. When you exceed one you get a clear error, not a larger invoice.

• Monthly quota counts one unit per accepted request and resets at the start of each month, UTC. Rejected requests do not consume quota.
• Rate is a token bucket, so short bursts above the per-minute figure are fine as long as the average holds.
• Concurrency counts queries in flight for your key. A finished query frees a slot immediately.

Checking your usage

Two ways, and neither needs an account. Both read the same metering records and both keep working when the Overpass backend is down, which is exactly when you want to look.

Quota headers on every response

Every keyed response carries where you stand, so you never have to go and ask:

X-Overspan-Quota-Limit:     250000
X-Overspan-Quota-Remaining: 249843
X-Overspan-Quota-Reset:     2026-09-01T00:00:00Z

They appear on rejections too, so a 429 tells you whether you are out of monthly quota or merely going too fast this minute.

The usage endpoint

curl -H "Authorization: Bearer YOUR_KEY" \
  https://api.overspan.dev/api/usage

Returns JSON with your tier and its limits, month-to-date quota, a 24-hour summary (counts by outcome, mean and 95th-percentile latency, bytes returned), 30 days of daily figures, and your twenty most recent requests. It accepts the same three key forms as the interpreter, does not consume query quota, and has its own generous rate limit so polling it costs you nothing.

Prefer to look rather than parse? The usage dashboard renders the same data in a browser. Paste your key and it calls this endpoint directly from your machine; the website is static and never sees your key.

Differences from the public servers

Short list, and none of it changes query semantics. This section exists so nothing surprises you after you switch.

• A query with no [maxsize:] gets 256 MB. Set it explicitly to go higher, up to your tier cap.
• Over-cap values are rejected, not clamped. Asking for [timeout:600] on Indie returns a 400 naming the 60 second maximum. We would rather fail loudly than quietly give you different results than you asked for.
• Errors are JSON, not HTML. Every rejection has the shape {"error": {"code": "...", "message": "..."}} with an appropriate status and, where useful, a Retry-After header. See the error reference.
• Attic queries are not enabled. Current data with full metadata is served; historical [date:] queries against past versions are not available yet. Tell us if you need them, since demand is what decides whether we turn them on.
• No access logs. We record per-request metering (which key, when, outcome, duration, bytes) but never the content of your queries. See the privacy page.

Looking after your key

A leaked key can be used by anyone until it is replaced, and the damage is bounded by that key's own limits rather than your card. Keep it in an environment variable or a secret manager, not in a committed config file or a notebook you will share.

Need a rotation? Email hello@overspan.dev and we will issue a replacement and revoke the old one. Self-serve rotation arrives when it becomes a chore rather than a rarity.

Attribution

Overspan serves OpenStreetMap data. That data is licensed under the Open Database License, and the obligation to credit it travels with the data to whatever you build. Anything you publish that shows or is derived from this data needs a visible credit that gives readers a way to reach openstreetmap.org/copyright. On a web page or in an app, make the credit a link:

Map data © <a href="https://www.openstreetmap.org/copyright">OpenStreetMap contributors</a>

Map data © OpenStreetMap contributors, openstreetmap.org/copyright

One distinction worth knowing: a map image, an app, or an analysis (something people are not meant to extract the raw data back out of) needs attribution only. A dataset or database you publish built on this data must itself be offered under the ODbL.

Your subscription pays for hosting and access, not for the data, and it does not change your licence obligations. If your use is unusual, take your own advice on it.

Something here wrong, unclear, or missing? Mail hello@overspan.dev. Documentation gaps are treated as bugs.