Navvo
API Reference

Telemetry

Submit anonymous trips to improve traffic, and read aggregated traffic data.

Telemetry

Contribute anonymous GPS trips that Navvo map-matches and aggregates into the live/typical traffic layers, and read back aggregated traffic data. If your app has its own location stream (delivery drivers, ride-hail, fleet), submitting it here makes traffic better for everyone — including your own ETAs.

Scope required: telemetry

Units & coordinates. Trip input points use named { lat, lng } fields; speed is in meters per second; capturedAt is an ISO-8601 timestamp. All traffic output speeds are km/h, and output geometry is GeoJSON [lng, lat].

POST /telemetry/trips

Submit a trip. The trip is stored and queued for asynchronous map-matching (via the Navvo routing engine); the call returns immediately.

Request body

points
array required
Ordered GPS points (see point shape below). Must be non-empty.
userId
string
Optional UUID identifying the contributor. If present, must be a valid UUID.
metadata
object
Free-form. Set metadata.consentCaptured = false to flag a trip as missing consent (it is still accepted but counted in the health summary). Consent is assumed true otherwise.

Each points[] element:

FieldTypeRequiredNotes
latnumberyesLatitude.
lngnumberyesLongitude.
speednumbernometers/second.
headingnumbernoDegrees.
capturedAtstringnoISO-8601; defaults to now.
{
  "userId": "8b1f5c2e-3d4a-4e2b-9f10-7c2a1b6d9e44",
  "metadata": { "consentCaptured": true, "device": "ios-17" },
  "points": [
    { "lat": 31.9500, "lng": 35.9100, "speed": 12.1, "heading": 90, "capturedAt": "2026-05-16T12:00:00Z" },
    { "lat": 31.9512, "lng": 35.9123, "speed": 13.4, "heading": 88, "capturedAt": "2026-05-16T12:00:05Z" }
  ]
}

Response (201)

{ "accepted": true, "tripId": "f0a1c3d5-…", "jobId": "12" }

The trip is processed in the background: matched to the road network, then per-edge observed speeds feed the traffic speed profiles that power the Traffic endpoints. status becomes matched or failed.

Privacy. Submit only data you have consent to share, and prefer anonymizing trip endpoints (trim the first/last few points). Trips power aggregate traffic only — they are not exposed as individual tracks through the API.

GET /telemetry/trips

List the 50 most recent trips (no pagination). Each item is a trip with status, consentCaptured, and a routeSummary (point/edge counts and first/last point); the raw points are not included.

GET /telemetry/health

Ingestion quality summary over the most recent 500 trips.

{
  "totalTrips": 500,
  "matchedTrips": 472,
  "failedTrips": 18,
  "consentMissingTrips": 3,
  "sampleRate": 0.944,
  "generatedAt": "2026-06-09T10:15:00.000Z"
}

GET /telemetry/daily

Trip counts per UTC day over the most recent 365 trips.

[ { "day": "2026-06-09", "trips": 14 }, { "day": "2026-06-08", "trips": 31 } ]

GET /telemetry/traffic-overlay

The aggregated traffic layer as a GeoJSON FeatureCollection of road-edge speed profiles with congestion classification — the data source behind the map traffic layer.

Query parameters

mode
string
current (default; last ~6h) or typical (all-time per-edge averages).
bbox
string
west,south,east,north spatial filter.
limit
string
Max features (capped by zoom; up to 5000).
zoom
string
Drives the limit cap and line generalization.
{
  "type": "FeatureCollection",
  "hasData": true,
  "mode": "current",
  "features": [
    {
      "type": "Feature",
      "geometry": { "type": "LineString", "coordinates": [[35.911, 31.951], [35.914, 31.952]] },
      "properties": { "edgeId": "e:128374", "congestion": "moderate", "averageSpeedKph": 28.4, "freeFlowSpeedKph": 55, "sampleCount": 4 }
    }
  ],
  "metadata": { "layerType": "traffic", "source": "navvo-telemetry-speed-profiles", "legend": { "light": { "color": "#188038" }, "moderate": { "color": "#D9A441" }, "heavy": { "color": "#D94B4B" }, "blocked": { "color": "#8B1A1A" } } }
}

congestion ∈ light | moderate | heavy | blocked | unknown.

Tiled access

For bounded loading the overlay is also tile-addressed:

EndpointReturns
GET /telemetry/traffic-overlay/tile-coverList of tile URLs covering a bbox (mode, bbox, zoom, maxTiles).
GET /telemetry/traffic-overlay/tiles/{z}/{x}/{y}The overlay for one tile, as GeoJSON.
GET /telemetry/traffic-overlay/vector/{z}/{x}/{y}The overlay for one tile, as a binary vector tile (application/x-protobuf, layer navvo_traffic).
Use the .../vector/{z}/{x}/{y} route to add traffic as a native Navvo Maps vector source; use the GeoJSON tile route if you prefer to style features yourself.

Traffic & Incidents

Live and typical congestion, traffic-aware ETAs, and crowdsourced road incidents.

Map Tiles & Styles

Navvo Maps styles, vector & raster tiles, glyphs, and sprites — a complete first-party basemap.

Copyright © 2026