Conventions
Conventions
A few cross-cutting rules apply across the whole API. Reading this page once will save you debugging time later.
Base URL & versioning
All endpoints are served under a versioned prefix:
https://navvo.io/api/v1
Paths in this reference are written in full, e.g. GET /api/v1/search.
Request & response format
- Request bodies are JSON (
Content-Type: application/json), except file uploads. - Responses are JSON unless the endpoint returns a tile or image (vector tiles, PNG/JPEG, SVG, or
.pbfglyphs/sprites) — those return the appropriate binary/image/*content type. - Unknown body fields are silently stripped. The API validates and whitelists request bodies, so extra properties you send are dropped rather than rejected.
POSThandlers return201 Createdon success (a NestJS default), even for compute-only endpoints like routing.
Coordinates
| Where | Format | Notes |
|---|---|---|
| GeoJSON output (overlays, isochrones, incidents, traffic, weather) | [lng, lat] | Standard GeoJSON — longitude first. |
Place center / entrance location | POINT(lng lat) (WKT string) | Longitude first. Parse the string yourself. |
bbox query parameter | west,south,east,north | i.e. minLng,minLat,maxLng,maxLat. |
Routing raw payload (route/matrix/etc.) | { "lat": …, "lon": … } objects | The routing engine's native format — note lon, not lng. |
Routing /plan, Traffic /route | { "lon": …, "lat": … } objects | Navvo-defined; keys named, so order is irrelevant. |
| Geocoding reverse | lat & lon query params | Separate parameters. |
Geo 3D way geometry | POINT/LINESTRING/POLYGON(x y) in EPSG:3857 | Web-Mercator meters, not degrees. |
Bounding boxes
Endpoints that filter by area accept a bbox query parameter as four comma-separated numbers:
bbox=west,south,east,north e.g. bbox=35.85,31.90,35.99,31.99
This is minLng,minLat,maxLng,maxLat. A bbox must satisfy west < east and south < north. Many endpoints cap the bbox span server-side based on zoom to protect performance.
Tiles ({z}/{x}/{y})
Tile endpoints use the standard slippy-map / XYZ scheme: z is the zoom (origin top-left, y measured from the north). Tile coordinates must satisfy 0 ≤ z ≤ 22 and 0 ≤ x,y < 2^z. Some tile routes accept a file extension on {y} (e.g. .png, .pbf, .json) which is stripped before parsing.
For loading bounded areas efficiently, many overlays expose a tile-cover endpoint that returns the exact list of tile URLs covering a bbox.
Pagination
List endpoints that paginate use page (1-based) and limit query parameters and return an envelope:
{ "items": [ ], "total": 137, "page": 1, "limit": 50 }
There is no nextPage cursor — compare page * limit against total to know when to stop. Per-endpoint limit caps apply (see each reference page).
Units
- Distances: kilometers unless an endpoint states otherwise.
- Durations: seconds (some responses also include a rounded
*Minutesfield). - Speeds: km/h in responses; the telemetry ingest input uses m/s.
- Timestamps: ISO-8601 strings (UTC), e.g.
2026-06-09T08:30:00.000Z.
Localization
Navvo is bilingual. Many place objects include both nameEn and nameAr. Where a locale parameter is accepted, en and ar are supported.
Attribution
When you display Navvo map tiles, styles, street-level imagery, or data derived from them, show the Navvo attribution. Navvo style/tile responses carry the attribution string (e.g. 2026 © Navvo) in their attribution / metadata fields, and imagery responses set sourceAttributionRequired: true (Navvo imagery attribution is mandatory). No third-party attribution is required in your app.