Execute a raw Overpass QL query
openstreetmap_query_rawRead-onlyIdempotent
Execute a raw Overpass QL query for advanced spatial queries that the convenience tools do not cover. Use for multi-type queries, union queries, relation membership, historical queries, or any operation requiring full Overpass QL expressiveness. The query must include [out:json]. Example: "[out:json][timeout:15];node"natural"="peak";out body;" Returns one page of the result set: use limit and offset to page through it, and read totalFound and truncated to see how much the query matched. Validate complex queries at overpass-turbo.eu before use. For simple "what's near X?" or "what's in this area?" queries, use openstreetmap_query_nearby or openstreetmap_query_bbox instead.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum elements to return. Applied after the Overpass query — if the query matched more, they are truncated. | |
| query | Yes | Overpass QL query string. Must include [out:json]. The server sets the endpoint and User-Agent; do not include those. Example: "[out:json][timeout:15];node[\"natural\"=\"peak\"](47.5,-122.5,47.7,-122.2);out body;" | |
| offset | No | Number of matching elements to skip before applying limit, for paging through a large result set. The full match set is fetched and cached ~10 minutes keyed by the query, so re-paging at a new offset is deterministic and costs no extra upstream request; a result over 100000 elements is served but not cached, so paging that far re-queries and depends on the endpoint returning the same order. Pass the nextOffset value from a prior truncated response. | |
| timeout_seconds | No | Query timeout in seconds, bounding how long Overpass itself spends on the query. The [timeout:N] directive in the query string takes precedence if present. The client waits for what is requested here, up to 180s, so a long-running query is not cut off early — but the endpoint enforces its own budget and may answer HTTP 504 first. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| error | No | Present when the call failed. Absent on success. | |
| notice | No | Guidance when the page came back empty. Distinguishes a query that matched nothing (check syntax or broaden the filter) from an offset past the end of a non-empty result set (retry at a lower offset). Absent when results were returned. | |
| elements | No | Raw Overpass API response elements for this page, up to the limit. Structure varies by query type — nodes have lat/lon, ways have nodes[], relations have members[]. | |
| truncated | No | True if elements were cut at the limit. Narrow the query, or page with offset to retrieve the rest. | |
| nextOffset | No | Offset to pass on the next call to retrieve the following page of elements. Present only when more elements remain beyond this page. | |
| totalFound | No | Total elements returned by Overpass before limit truncation. | |
| attribution | No | Required data attribution: Data © OpenStreetMap contributors, ODbL 1.0. | |
| data_timestamp | No | OSM data freshness timestamp from the Overpass response. Absent when the endpoint reported no freshness metadata. | |
| effectiveQuery | No | The Overpass QL string as sent to the API (after any timeout injection). | |
| total_elements | No | Number of elements returned on this page. See totalFound for the full match count. | |
| servingEndpoint | No | Overpass endpoint that produced this response, as origin and path. Differs from the first configured endpoint when a mirror answered after the primary failed, and names the endpoint that served a cached response rather than the one this call would have tried. Pair it with data_timestamp when a result looks unexpectedly slow, sparse, or stale. |