Documentation menu
Transit
GET/v1/transit/vehicles
Access and price
| Auth | An API key, as Authorization: Bearer snk_… or ?api_key=snk_…. Metered. A browser (maps) key may call it. |
|---|---|
| Price | 1 call per request. Class: standard. Published as unit_rules.default in /pricing.json. |
What it does
GET /v1/transit/vehicles?bbox=<west>,<south>,<east>,<north>.
Call it
bash
curl -fsS -X GET "https://api.mapmap.ai/v1/transit/vehicles?bbox=…" \
-H "Authorization: Bearer $MAPMAP_KEY"Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| bbox | query | string | yes | Required. west,south,east,north in WGS84 degrees, covering at most 4 square degrees (for example 2 by 2 degrees). A box across the antimeridian is not supported |
| operator | query | string | no | Only this operator's vehicles: a National Operator Code such as TFLO (case-insensitive) |
| line | query | string | no | Only vehicles on this line, as riders see it, e.g. 88 (case-insensitive) |
| limit | query | integer | no | Most features to return, 1 to 5000 (default 2000). Past it truncated is true and the features are spread evenly across the matches Limits: at least 0. |
Responses
200GeoJSON FeatureCollection of live bus positions inside the box, with
feed (freshness: ok, stale past 180 s, or unknown), coverage and the OGL v3.0 attribution. A stale feed still returns its features: staleness is a field, never an error. Display only: no arrival, journey-time or delay prediction| Field | Type | Required | Description |
|---|---|---|---|
| attribution | string | yes | Licence attribution (OGL v3.0), to be shown with the data. |
| count | integer | yes | Features in this answer. |
| coverage | string | yes | What the feed covers and what it does not. |
| features | TransitVehicleFeature[] | yes | One Point feature per vehicle. |
| feed | TransitFeed | yes | How fresh the feed is. Read it before drawing positions as live. |
| generated_at | string | no | When the box built the snapshot this answer reads (RFC 3339).
null before the first snapshot exists. |
| matched | integer | yes | Vehicles inside the box that matched the filters, before limit. |
| recorded_at_max | string | no | The newest vehicle fix in that snapshot (RFC 3339). |
| truncated | boolean | yes | True when matched exceeded limit. The features returned are
then spread evenly across the matches (in longitude order), not the
westernmost limit of them. |
| type | string | yes | Always FeatureCollection. |
Example: A response assembled from this schema's own field examples, enums, defaults and types; not a recorded call
json
{
"attribution": "string",
"count": 0,
"coverage": "string",
"features": [
{
"geometry": {},
"id": "string",
"properties": {},
"type": "string"
}
],
"feed": {
"id": "string",
"status": "string",
"threshold_s": 0
},
"matched": 0,
"truncated": false,
"type": "string"
}400
bbox missing, malformed, inverted or larger than 4 square degrees; or a malformed operator, line or limit. Not billedapplication/problem+json · Problem
401Missing or invalid API key. Also: No key, or a missing, malformed, unknown, revoked or expired one (
unauthorized); the body carries signup, docs and a one-call hint for a free keyapplication/problem+json · Problem
402Beyond the included volume with no way to pay this call: an x402 body naming how to pay (provisional key past its allowance, prepaid balance below the price, or a rejected
X-PAYMENT). Not problem+jsonapplication/json · X402PaymentRequired
403The key may not call this: a browser key outside its scope (
scope-insufficient), a request from an origin the key does not allow (origin-not-allowed), or an account restriction (forbidden)application/problem+json · Problem
429Quota or rate limit exceeded. Also: Per-key rate limit (
rate-limited, with Retry-After), or monthly quota exhausted with no payment path (quota-exceeded)application/problem+json · Problem
501Live bus positions not enabled (
SN_TRANSIT_DIR unset). Not billedapplication/problem+json · Problem
504The request did not finish within the gateway's request deadline (
request-timeout)application/problem+json · Problem
Error bodies follow the shared problem model documented on API conventions.
Also under Transit
Generated from https://api.mapmap.ai/openapi.json on 2026-11-12 · operationId get_transit_vehicles