Node.js SDK
Node.js SDK
The official @navvo/sdk package is a server-side TypeScript/JavaScript
client for the Navvo Web Service. It is fully typed, retry-aware, and has
zero runtime dependencies — it uses the built-in global fetch (Node 18+).
It ships a dual ESM + CJS build with complete .d.ts types. There is no
map UI or tile rendering — for rendering a map in the browser use
Navvo Maps.
Requires: Node 18+ · Base URL: https://navvo.io/api/v1
Install
npm install @navvo/sdk
# or: pnpm add @navvo/sdk / yarn add @navvo/sdk
Authenticate
Every call is sent with the x-api-key header. The key is read from the
NAVVO_API_KEY environment variable by default, or pass it explicitly:
import { NavvoClient } from "@navvo/sdk";
const navvo = NavvoClient.fromEnv(); // uses $NAVVO_API_KEY
const navvo2 = new NavvoClient({ apiKey: "nvvo_your_key_here" });
The SDK never puts the key in a URL — except styleUrl(), which builds a
browser-fetchable map style URL where the key must
ride as ?api_key= (browsers cannot set headers on tile/style requests).
Quickstart
import { NavvoClient } from "@navvo/sdk";
const navvo = new NavvoClient();
// Forward geocode — string coordinates are parsed to numbers for you
const hits = await navvo.geocode("Abdali Hospital, Amman", { limit: 5 });
console.log(hits[0].lat, hits[0].lng, hits[0].displayName);
// Plan a route — you pass { lat, lng }; the SDK serialises lon/lat on the wire
const plan = await navvo.route({
locations: [
{ lat: 31.95, lng: 35.91, name: "A" },
{ lat: 31.99, lng: 35.95, name: "B" },
],
costing: "auto",
});
const trip = plan.engine?.data?.trip;
console.log("ETA seconds:", trip?.summary?.time);
// Decode the leg polyline (polyline6) into points
const line = NavvoClient.decodePolyline(trip?.legs?.[0]?.shape ?? "");
// Live, condition-aware extras
const wx = await navvo.weatherPoint(31.95, 35.91);
const inc = await navvo.incidents({ bbox: { west: 35.85, south: 31.9, east: 35.99, north: 31.99 }, limit: 10 });
Coordinates — never backwards
You always supply points as { lat, lng } (a LatLng). The SDK owns every
wire-format difference: { lon, lat } for route()/trafficRoute(),
{ lat, lon } for the routing passthrough payloads, separate lat/lon params
for reverse geocode, west,south,east,north for BBox, [lng, lat] for
GeoJSON, and WKT POINT(lng lat) for place center (parse it with
parseWktPoint(place.center) or NavvoClient.routeTargetFor(place)).
Retries & errors
Transient failures (5xx, 408, 429/quota, network blips) are retried with
exponential backoff and full jitter, honouring Retry-After; client errors
(400/401/403/404) are never retried. All errors subclass NavvoError:
import {
NavvoRateLimitError,
NavvoForbiddenError,
NavvoServiceUnavailableError,
} from "@navvo/sdk";
try {
const r = await navvo.geocode("Abdali Hospital, Amman");
} catch (e) {
if (e instanceof NavvoRateLimitError) {
console.warn("rate limited, retry after", e.retryAfter, "s");
} else if (e instanceof NavvoForbiddenError) {
console.error("scope/quota problem:", e.reason ?? e.message);
} else if (e instanceof NavvoServiceUnavailableError) {
console.error("geocoder upstream is down — fall back");
} else {
throw e;
}
}
The geocoder/routing envelope ({ provider, available, data }) is unwrapped
for you — an available:false body becomes a NavvoServiceUnavailableError —
and an unknown place slug returns null (a soft-null, not an error).
Cancel any call with an AbortSignal:
const ac = new AbortController();
const p = navvo.list({ category: "cafe" }, { signal: ac.signal });
setTimeout(() => ac.abort(), 1000);
Method map
| Area | Methods |
|---|---|
| Tiles & config | styles, styleUrl, mapConfig |
| Search & geocoding | search, geocode, reverseGeocode, geocodeBatch, reverseGeocodeBatch |
| Places | list, iterate, place, thumb, placeCategories, facets, hours, popularTimes, attributes, reviewsSummary, photos, nearby, reachable |
| Routing | route, simpleRoute, matrix, isochrone, mapMatch, routingOptimize, routingProfiles |
| Optimization | optimizeHealth, optimize, reoptimize, binpack, roster, submitJob, job, waitForJob |
| Traffic & incidents | trafficRoute, trafficSummary, incidents, incidentTypes, reportIncident, roadEdits, routeRisk |
| Weather & air quality | weatherPoint, weatherForecast, weatherCities, airQualityCities |
| EV & transit | evStations, transitStops, gbfs |
Each method maps to the endpoint documented in the
API reference. geocode returns typed objects with the
common fields parsed and the full geocoder payload preserved on .raw.
Route optimization (optimize, submitJob, …) requires the opt-in optimize
scope; see Route Optimization.