Guides
Display a map
Embed an interactive Navvo Maps basemap in your app.
Display a map
Render an interactive Navvo Maps basemap in the browser. Navvo Maps ships a lightweight GL renderer plus a complete vector style — point it at your style URL and you're done.
Scope required: tiles
1. Add Navvo Maps
Load the Navvo Maps SDK (renderer + styles), served from Navvo:
<link href="https://docs.navvo.io/navvo-maps/navvo-maps.css" rel="stylesheet" />
<script src="https://docs.navvo.io/navvo-maps/navvo-maps.js"></script>
<div id="map" style="width: 100%; height: 480px;"></div>
2. Point it at a Navvo style
Because the browser can't add an x-api-key header to map requests, pass your key on the style URL as api_key:
const map = new NavvoMaps.Map({
container: "map",
style: "https://navvo.io/api/v1/tiles/style?style=standard&api_key=nvvo_YOUR_KEY",
center: [35.9106, 31.9539], // [lng, lat] — Amman
zoom: 12,
});
map.addControl(new NavvoMaps.NavigationControl());
That's a full vector basemap — pan, zoom, labels, and all.
3. Choose a style
Swap the style= value for a different look:
style= | Look |
|---|---|
standard | Light vector basemap (default). |
dark | Dark vector basemap. |
positron | Minimal light basemap. |
satellite | Aerial imagery (raster). |
terrain | Shaded terrain (raster). |
3d | 3D building extrusions (add &terrain=1 for elevation terrain). |
map.setStyle("https://navvo.io/api/v1/tiles/style?style=dark&api_key=nvvo_YOUR_KEY");
4. Add a marker
new NavvoMaps.Marker({ color: "#386BFF" })
.setLngLat([35.9106, 31.9539])
.setPopup(new NavvoMaps.Popup().setText("Amman"))
.addTo(map);
Navvo Maps uses
[lng, lat] order. Navvo place coordinates come back as WKT POINT(lng lat) — already longitude-first, so you can parse and pass them straight through.5. Add an overlay (optional)
Layer live traffic, incidents, or weather on top of the basemap using the overlay endpoints. For example, add live traffic as a GeoJSON source:
map.on("load", async () => {
const res = await fetch(
"https://navvo.io/api/v1/traffic/lines/tiles/14/9826/6656", // an Amman tile
{ headers: { "x-api-key": "nvvo_YOUR_KEY" } }
);
const geojson = await res.json();
// Live traffic is crowd-sourced from Navvo users, so `geojson.hasData` is
// `false` (and `features` is `[]`) wherever no one has reported traffic
// recently — a normal response, not an error. Add the layer regardless;
// it fills in with coloured lines as coverage arrives.
map.addSource("traffic", { type: "geojson", data: geojson });
map.addLayer({
id: "traffic",
type: "line",
source: "traffic",
paint: { "line-color": ["get", "color"], "line-width": 3 },
});
});
An empty traffic response is expected — it's not the base map.
/traffic/lines/tiles/{z}/{x}/{y} is an optional overlay of Navvo's crowd-sourced live congestion, returned as GeoJSON. It responds with { "hasData": false, "features": [] } wherever no Navvo users have recently reported traffic (so it will often be empty today). Your map still renders — the actual basemap tiles come from the /tiles/style endpoint in step 1. See the Live traffic layer guide for loading a whole viewport with tile-cover and handling hasData.See the Live traffic layer guide for loading a full viewport efficiently with tile-cover.
Attribution. The Navvo basemap carries
© Navvo. Display the Navvo credit; no third-party attribution is required in your app. Keep the compact on-map attribution control shown — the SDK displays it by default. GET /map/config returns an attribution object if you build your own attribution UI.No API key? The map is watermarked. Without an API key, the basemap renders with a "Navvo Map Developer (Provide Your API Key)" watermark tiled across every tile on a dark, semi-transparent background. Provide your
api_key (query param on the style URL, or the SDK apiKey) to get a clean, unwatermarked map.