Documentation / Overpass compatibility

Overpass compatibility

Mapsource accepts standard Overpass QL. Authentication, execution limits, and the active dataset determine how an existing application should connect.

On this page

Request formats

Method	Query location	Content type
GET	URL-encoded data parameter	No request body
POST	Form field named data	`application/x-www-form-urlencoded`
POST	Raw Overpass QL	`text/plain` or `application/x-overpass-ql`

The interpreter is https://api.mapsource.io/interpreter. A client that appends /interpreter to a base URL uses https://api.mapsource.io. The /api/interpreter path used by other Overpass servers also works.

The subscription interpreter does not accept an arbitrary JSON request body. JSON with a query field is used by the separate x402 endpoint and MCP tool arguments.

curl --fail-with-body --get https://api.mapsource.io/interpreter \
  -H "Authorization: Bearer $MAPSOURCE_API_KEY" \
  --data-urlencode 'data=[out:json][timeout:30];node["amenity"="cafe"](47.60,-122.34,47.62,-122.31);out meta 20;'

Data and output

The current-data Overpass contract includes tagged nodes, ordered-node ways, and member/role relations. Queries can use spatial selectors, sets, recursion, generated areas, tags, geometry, centers, bounds, and element metadata.

Specify [out:json], [out:xml], or [out:csv(...)] explicitly. Responses are streamed using the requested output content type. Request metadata using out meta; request shape coordinates using out geom.

Queries use the active OpenStreetMap dataset. See service status for its timestamp and replication progress.

Defaults and limits

The gateway adds a 25-second timeout if omitted, and your plan’s memory ceiling if maxsize is omitted. Duplicate or invalid directives are rejected. Values above plan limits are rejected.

The synchronous timeout ceiling is 60 seconds for Core and 120 seconds for Pro and Business. Query bytes and response bytes are limited separately from working memory. See the complete limits table.

Engine version

Mapsource runs the upstream Overpass API engine. The currently deployed engine version is published by GET /status; see overpass.displayVersion. The value identifies the engine build currently serving Mapsource requests and changes automatically when production is upgraded.

The engine also stamps its version in each response’s generator field and XML generator attribute. Interpreter responses carry X-Mapsource-Overpass-Version and X-Mapsource-Overpass-Commit headers with the same values.

The datasets array in the same response lists the engine build and data snapshot behind routing, search, vector and raster tiles, and elevation. Basemap tiles are generated from their own OpenStreetMap cut, so compare dataset.timestamp values rather than assuming every dataset matches the Overpass timestamp.

curl --fail-with-body https://api.mapsource.io/status | jq .overpass.displayVersion

Compatibility differences

No historical attic queries: date, changed, and newer selectors are rejected.
Subscription calls require a valid credential; public Overpass instances have different access rules.
/status returns Mapsource JSON status, not the public Overpass text queue protocol.
Gateway errors have a stable JSON envelope, while upstream and interrupted-stream errors can differ.
Raster tiles and elevation are companion APIs, not output modes or fields inside an OSM query.
Overpass output limits are not pagination tokens. Split large areas carefully and deduplicate by element type and ID.

Test before switching

Compare representative queries against the source and destination using similar dataset timestamps. Check element IDs, tags, geometry, relation members, metadata, generated areas, output formats, and client cancellation handling. Change one application first and monitor errors and usage.

Use the client setup and migration guides for the endpoint change.

Questions about this guide? Contact support.