Documentation / Hosted Overpass API

Hosted Overpass API

Query OpenStreetMap nodes, ways, relations, tags, and geometry with standard Overpass QL.

On this page

Find cafés in a bounding box

Send Overpass QL to https://api.mapsource.io/interpreter with a Bearer API key (an /api prefix also works). Use spatial filters and OSM tags to select features, and request geometry for map overlays.

curl --fail-with-body https://api.mapsource.io/interpreter \
  -H "Authorization: Bearer $MAPSOURCE_API_KEY" \
  -H 'Content-Type: text/plain' \
  --data '[out:json][timeout:30];nwr["amenity"="cafe"](47.60,-122.34,47.62,-122.31);out geom 100;'

Selectors, geometry, and metadata

Use node, way, relation, or nwr selectors with OSM tags. A bounding box uses south, west, north, east in decimal degrees. Tags are community-maintained and coverage varies; an absent tag does not prove a real-world feature is absent.

[out:json][timeout:30];
(
  way["building"](47.60,-122.34,47.61,-122.33);
  relation["building"](47.60,-122.34,47.61,-122.33);
);
out geom 100;

Use out geom for geometry, out center for representative points, and out meta for edit metadata. Centers are not building footprints. Recursion can retrieve referenced nodes or members when your output format needs them.

Working with query results

Object	How to use it
Node	Render a point using lon, lat and retain its tags and ID.
Way	Use ordered geometry or resolve referenced nodes. Distinguish linear features from tagged areas.
Relation	Interpret members and roles, including multipolygon outer and inner rings. Do not flatten every relation into one polygon.

Overpass JSON is not GeoJSON. Convert it before adding a GeoJSON source to MapLibre, and preserve element type alongside ID because IDs can overlap between nodes, ways, and relations. Use a tested converter for complex relations.

Output limits are not pagination. For larger work, split the area, bound concurrent requests, and deduplicate results by type and ID. Query cost also depends on selectors and recursion, not just the number of returned objects.

See compatibility for GET, form POST, raw text, output modes, and default directives; client setup provides executable requests.

Access and limits

Supports arbitrary OSM tags, set operations, recursion, generated areas, geometry, metadata, and JSON/XML/CSV output. Historical attic queries are not supported.

Plan limits apply to query size, timeout, memory, response size, request rate, and concurrency. Output limits cap returned objects; they do not provide pagination or total match counts.

See plan limits for request allowances and error handling for quota and retry behavior.

Responses and examples

JSON responses include generator, osm3s, and elements. Each element is an OSM node, way, or relation. osm3s.timestamp_osm_base identifies the dataset timestamp.

Engine version: the currently deployed Overpass engine version is published by GET /status as overpass.displayVersion. It is read from the engine binary serving Mapsource requests and changes automatically when production is upgraded. The same engine stamps generator in every JSON and XML response, and each interpreter response carries X-Mapsource-Overpass-Version and X-Mapsource-Overpass-Commit headers.

Example responses and timing measurements · Current service status

Attribution

OSM data is © OpenStreetMap contributors under the ODbL. Display attribution and review the license obligations for derived databases.

Source and reference · Mapsource attribution guide

Questions about this guide? Contact support.