Skip to content
Documentation menu
docs / api / get-v1-transit-vehicles
Transit

GET/v1/transit/vehicles

Access and price

AuthAn API key, as Authorization: Bearer snk_… or ?api_key=snk_…. Metered. A browser (maps) key may call it.
Price1 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

NameInTypeRequiredDescription
bboxquerystringyesRequired. 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
operatorquerystringnoOnly this operator's vehicles: a National Operator Code such as TFLO (case-insensitive)
linequerystringnoOnly vehicles on this line, as riders see it, e.g. 88 (case-insensitive)
limitqueryintegernoMost 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
FieldTypeRequiredDescription
attributionstringyesLicence attribution (OGL v3.0), to be shown with the data.
countintegeryesFeatures in this answer.
coveragestringyesWhat the feed covers and what it does not.
featuresTransitVehicleFeature[]yesOne Point feature per vehicle.
feedTransitFeedyesHow fresh the feed is. Read it before drawing positions as live.
generated_atstringnoWhen the box built the snapshot this answer reads (RFC 3339). null before the first snapshot exists.
matchedintegeryesVehicles inside the box that matched the filters, before limit.
recorded_at_maxstringnoThe newest vehicle fix in that snapshot (RFC 3339).
truncatedbooleanyesTrue when matched exceeded limit. The features returned are then spread evenly across the matches (in longitude order), not the westernmost limit of them.
typestringyesAlways 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"
}
400bbox missing, malformed, inverted or larger than 4 square degrees; or a malformed operator, line or limit. Not billed

application/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 key

application/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+json

application/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 billed

application/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