What it does
- Live snapshot. The last known position for a driver — coordinates and the time the fix was taken. This is the read behind a dispatch map.
- History. A driver’s positions across a time window you specify, for replaying a day, verifying a route was driven, or evidencing time on site.
- Shareable tracking links. Time-limited, revocable links tied to a delivery stop that a recipient can open without an account or a credential.
- Push instead of polling. Movement-derived events delivered to your endpoint, so you are not asking “where are they now” on a timer.
How it works
Writes never block on reads
When a driver’s device submits a fix, the platform validates it, stamps its own receive time, and acknowledges immediately. Everything downstream — updating the live cache, writing history, checking boundaries — happens independently. The practical effect is that a driver in a tunnel with poor signal, or a burst of a thousand devices reporting at once, does not degrade the app experience or lose positions.
Two questions, two stores
“Where is this driver right now” and “where was this driver at 10:15 this morning” are different questions with very different shapes. The platform answers them from separate stores tuned for each. A dashboard refreshing every few seconds is reading a small, hot store and costs almost nothing; a history replay scans a time-series store built for exactly that. Neither degrades the other, so a busy live map never slows down a report.
Bounded history reads
History requests take an explicit time window and are capped. This is deliberate: an unbounded “give me everything” request is the one that times out at the worst moment. Ask for what you intend to display, and page through if you need more.
You build the map
The platform serves position data; it does not serve a tracking page. That is not an omission — it is the point. A tracking page is your product surface, carrying your brand and your wording, and no two customers want the same one. Mesh gives you the position, the stop it belongs to, and the events that change it.
Scoping and consent
Every position is scoped to your account and to the driver it came from, at every layer. A credential can only read positions for drivers in the account it belongs to. Driver devices receive a credential that can submit telemetry but cannot read anyone else’s.
Permissions
| Permission | What it allows | Needed |
|---|---|---|
| tracking.read | Read live and historical position telemetry — the snapshot and history reads. | Required |
| tracking.write | Submit position fixes. Granted to driver client credentials, not normally to a back-office integration. | Driver clients |
| drivers.read | Resolve a position back to a driver record — name, vehicle assignment, availability. | Recommended |
| tracking-links.read | Read shareable tracking links. The recipient-facing resolve of a link token needs no permission at all. | Optional |
| tracking-links.write | Create, update and revoke shareable tracking links. | Optional |
| subscriptions.read | Read the webhook subscriptions that deliver movement-derived events. | Optional |
| subscriptions.write | Register a webhook endpoint and rotate its signing secret. | Optional |
API reference
Position telemetry is split across four contracts — writes and reads are deliberately separate services.
| Service | What it covers | Reference | Contract |
|---|---|---|---|
| ingest-api | Write side: the mobile position firehose. Write-only — it has no reads. | OpenAPI description | openapi.json |
| tracking-api | Read side: last-known position and history. | OpenAPI description | openapi.json |
| tracking-links-api | Shareable tracking links for a stop, plus anonymous token resolve. | OpenAPI description | openapi.json |
| white-labeling-api | Per-host brand and theme config for the tracking surfaces. | OpenAPI description | 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
Individual position fixes are not delivered as webhooks. A fleet reporting every few seconds would generate millions of deliveries a day to your endpoint, almost all of them telling you nothing changed. Read the live snapshot when you need a position; subscribe to the events below for the moments that actually matter.
| Event | Raised when | Tells you |
|---|---|---|
| geofence.entered | A tracked driver or device crosses into a boundary you defined. | The boundary, the device and driver, the coordinates, and the time of the crossing. Requires the Geofences module. |
| geofence.exited | A tracked driver or device crosses out of a boundary. | The same detail as entry. Requires the Geofences module. |
| stop.arrived | The driver arrives at a stop. | The stop, the run and the driver, with the arrival time. |
| stop.departed | The driver leaves a stop. | The stop, the run and the driver, with the departure time. |
| run.started | A driver starts a run — the point live tracking becomes meaningful for that run. | The run and the driver. |
| run.completed | A driver finishes a run. | The run, the driver, and the completion time. |
The envelope these arrive in, the delivery and retry guarantees, and every other event type are in Events & webhooks — or jump straight to the event catalog.