What it does
- A basemap you can draw in a web or mobile application — vector map squares, fonts and icons, in five themes.
- Road distance and duration between any set of points, as a single route or as a full matrix of every origin against every destination.
- Snap to road. Attach a loose coordinate to the road it is actually on, and be told whether the result is worth trusting.
- Map matching. Take a recorded GPS trace and work out which roads it actually travelled.
Your Mesh stops, runs and geofences are drawn on top of this map by your own code. The map itself knows nothing about them — see How it works for why that line is drawn where it is.
No satellite or aerial imagery. No live traffic. No turn-by-turn navigation on a driver’s phone. The platform has none of these, and this page says so rather than leaving you to discover it after you have built against the assumption. For navigation, hand the driver off to a consumer navigation app.
How it works
Use the map control, not a map library
Mesh publishes a map control as an npm package, @locate2u/mesh-map. Install that rather than wiring MapLibre, Mapbox GL JS or Leaflet against the basemap contract yourself. The control already handles the parts that are tedious and easy to get wrong: discovering the region and version path segments, putting the credential on every generated map-square request, pinning a build for the session, refreshing a short-lived token, themes, and the attribution notice.
This is the failure that costs people a day. A bad key, a disabled module, an unreadable map square — nearly every one of them returns a success status. What you see is a blank grey rectangle, which is indistinguishable from an empty patch of ocean, and the browser console stays silent. The control emits a mesh-map-error event naming the actual cause; a hand-rolled integration has nothing to tell you. Listen for it.
The control is a custom element, so it works unchanged in React, Vue, Angular, Svelte and plain HTML — there is no framework-specific package to go looking for.
One more trap worth naming: Mapbox GL JS v2 and later requires a billed Mapbox account even when pointed at our own map data, so reaching for it undoes the reason this module exists.
Three kinds of credential, and they are not interchangeable
A map key is locked to the origins you nominate and is safe to put in page source — that is what it is for. A bare host in that list allows any port on it, so localhost covers whatever port your dev server picks; a leading *. matches subdomains as well as the apex, which is how preview deploys are covered. Nominating * removes the only protection a map key has.
A map key cannot be used from server-side rendering or from a mobile app, because neither sends an Origin header and an origin-locked key refuses a caller it cannot place. Mint a short-lived map token for those. A bearer token is for server-to-server calls and must never appear in front-end code.
The road network answers questions; it does not navigate
Routing here is a distance-and-duration service. It returns the path through your points, the line to draw for it, and — given a departure time — the arrival times. It is deliberately not a turn-by-turn navigation engine: there is no instruction list, no rerouting, no voice guidance, and no live traffic feeding the estimate.
That boundary is what makes the matrix endpoint useful to route optimisation, which needs thousands of point-to-point costs quickly and never needs a spoken instruction.
Themes
Five themes ship: two day (light, white), two night (dark, black), and one neutral (grayscale) for when your own data has to stand out against the map rather than compete with it. Map squares, fonts and icons are shared between themes, so switching costs one small document and no new map-square requests.
Automatic day/night switching is available, and it switches at civil twilight rather than sunset — sunset would leave a driver on a bright white screen right through dusk, then flip to night while it is still light out.
The control draws what you hand it
The map control never fetches a Mesh resource. It does not know what a stop, a run or a driver is. You load your own data through the platform APIs and add it as a layer. A control that quietly fetched your runs would be a product surface rather than a platform one, and it would be useless to anyone whose data is shaped differently.
Attribution is not optional
The map is derived from OpenStreetMap, and the OpenStreetMap credit is a licence condition. The control does not let you switch it off. That is deliberate — the credit has to reach the person looking at the map.
Permissions
| Permission | What it allows | Needed |
|---|---|---|
| maps.read | Read the basemap — the style document, map squares, fonts and icons — and mint map tokens for front-end use. | Required to draw a map |
| maps.write | Manage the account’s map credentials, including the origins a map key is locked to. | Required to configure |
| routing.execute | Call the road network: route, distance matrix, snap and map matching. | Required to ask road questions |
The permissions above attach to a server-side credential. The key or token you put in front-end code is minted from that credential and carries only the ability to draw a map — it cannot read your stops, runs or drivers. That is the whole point of the split, and it is why a bearer token must never be shipped to a browser.
API reference
Two contracts: the basemap you draw, and the road network you ask questions of.
| Service | What it covers | Reference | Contract |
|---|---|---|---|
| routing-api | Route, distance matrix, map matching and snap. | OpenAPI description | openapi.json |
| tiles-api | Style document, vector map squares, fonts and icons. Publishes no rendered reference. | — | openapi.json |
Each openapi.json is the generated OpenAPI 3.1 contract, served by the service itself — it is never hand-edited, so it cannot drift from the running API. The OpenAPI description link opens the same contract as a browsable reference. Both resolve to the environment these docs are served from, so a page read on the test site links to the test contract.
Events
This module raises no events.
Maps is a request-and-response surface: you ask for a map square or a road distance and you get an answer. Nothing happens asynchronously, so there is nothing to subscribe to and no webhook to register.
The modules that do put events on the stream are listed with their event types in the event catalog; the envelope they arrive in and the delivery guarantees behind them are in Events & webhooks.