Live tracking
Live tracking shows where your vehicles are and where they stop today, on your published maps: a food truck's route, a shuttle loop, a mobile clinic. Visitors see each vehicle that is on shift move on the map, today's stops with Here Now, Open Now or Closed Today, and an estimate of how long until the next stop. See the live layout for what a visitor sees.
It has three parts, all in Kaleidr Studio:
| Part | What it is |
|---|---|
| A Stops collection | The schedule: each stop, its address and its weekly service windows. A Places Library collection like any other. |
| A fleet | Your vehicles, their shifts, and how precisely visitors see them. Managed under Data, Fleet. |
| Positions | Where each vehicle is, from one of four sources: a driver's check-in link, a phone in Driver Mode, a tracker of your own, or a connector to your telematics provider. |
Positions are shown only while a vehicle is on shift. A position recorded outside every shift of its vehicle is dropped when it arrives: it is never stored and never shown, only counted. See Shifts.
Fleets
Under Data, choose the Fleet tab, then New Fleet. Give it a name and a time zone, and choose its Stops Collection if you have one. Studio creates a Vehicles collection of the same name: that collection is the fleet on your maps, and you add it to a map like any collection. It holds no imported places; its vehicles are the fleet's.
Add Vehicle on the fleet's page adds one:
| Field | Shown to visitors | Use |
|---|---|---|
| Name | Yes | The vehicle's label on the map and in the panel, such as "Truck 1". Unique in the fleet. |
| Kind | Yes | Truck, van, car, bus, shuttle, boat, cart or bike. |
| Color | Yes | The vehicle's color on the map. |
| Description | Yes | A short line on its card, up to 200 characters. |
| External ID | No | Your own id, matched by connectors and by the Vehicle column of your stops. |
| Shift hours | No | The weekly hours a scheduled fleet's shifts follow. See Shifts. |
A vehicle turned inactive is never shown, and its positions are dropped. The fleet's page draws a live map of it, at full precision, for you only.
Owners, admins and members manage fleets and vehicles; viewers can see them. Only owners and admins delete a fleet, erase a vehicle's history, and manage connectors. Delete Fleet deletes the fleet, its vehicles, devices, links, shifts, history and connectors, then its Vehicles collection.
Stops schedules
The schedule is a Stops collection. Each stop is a place with a name and an address or coordinates, and these fields set when it is served:
| Field | Meaning |
|---|---|
| Hours | The stop's weekly service windows, written like opening hours: up to four windows a day. A window can cross midnight, and belongs to the day it starts. |
| Time Zone | The zone the windows are written in. Empty, the collection's. |
| Status | paused takes the stop out of every day. Any other value, or none, keeps it. |
| Vehicle | The name or external ID of the vehicle that serves the stop. Empty, any vehicle of the fleet. |
| Service Dates | Dates as YYYY-MM-DD, separated by commas or spaces. When present, the stop runs only on those dates. |
On a given date, a stop's windows are:
- none when its status is
paused, or its time zone is not a valid one; - none when it has Service Dates and the date is not among them;
- without Hours: the whole day when Service Dates list the date, else none;
- otherwise the Hours of that day of the week.
A stop is open now when a window of today contains the local time, or a window of yesterday that crosses midnight does. "Today" is the date in the fleet's time zone.
| Stop | Asked | Windows | Open |
|---|---|---|---|
| Hours Monday 11:00–14:00 | Monday 12:00 | 11:00–14:00 | Yes |
| The same | Monday 15:00 | 11:00–14:00 | No |
The same, with Service Dates 2026-11-02 | Monday 2026-11-09, 12:00 | None | No |
Service Dates 2026-11-02, no hours | 2026-11-02, 09:00 | All day | Yes |
Hours Monday 11:00–14:00, Status Paused | Monday 12:00 | None | No |
| Hours Friday 22:00–02:00 | Saturday 01:00 | Friday's 22:00–02:00 | Yes |
| Hours Monday 11:00–14:00, an invalid time zone | Monday 12:00 | None | Unknown |
Service Dates 2026-11-02, 2026-11-03 2026-11-04, hours Monday 11:00–14:00 | Tuesday 2026-11-03 | Tuesday's hours: none | No |
The Location template in the template builder and Download Sample Sheet start you with a filled-in Stops collection.
Check-in links
A check-in link lets a driver mark the vehicle at a stop from any phone browser, with no app and no account.
Create one on the fleet's page: a vehicle, Check-In Link, Create Link. Studio shows the link once,
with Copy Link and a QR code to scan. It looks like https://map-embed.kaleidr.com/checkin.html#….
- One link a vehicle, valid for 180 days. Replace Link issues a new one and ends the old one at once; use it when a phone is lost or a driver leaves. Revoke Link ends it. Afterwards Studio shows only the link's last four characters, when it expires and when it was last used.
- The link is a key. Anyone who holds it, near a stop, can check the vehicle in. Share it with the driver only.
- Open it in a browser. The page refuses to work inside another page's frame.
The driver's page shows the vehicle, today's stops and their status:
- I'm Here Now reads the phone's location once and checks in at the stop within reach: 250 meters plus the reading's accuracy, which must be 100 meters or better. When more than one stop, or none, is within reach, the page lists today's stops and the driver picks one, which must be within 2,000 meters. A fleet with Allow Check-In Away From Stops on also offers Not a Scheduled Stop.
- Closed for Today marks the vehicle's remaining stops today Closed Today and ends its shift. Reopen Today, the same day, clears those marks; it does not start a shift.
A check-in opens a shift until 30 minutes after the stop's window ends, and shows the vehicle at the stop's own position, not the phone's. The phone's location is used to find the stop and then discarded. A check-in away from a stop shows the vehicle at the phone's position for four hours, rounded to about 10 meters, or more coarsely when the fleet's public precision is coarser.
Phones in Driver Mode
A driver's phone with the Kaleidr app shares the vehicle's position while the driver's shift is on. On the fleet's page, a vehicle, Pair Phone, Show Pairing Code shows a QR code and an eight-character code, valid for 10 minutes and once. The driver scans the QR with the phone's camera, or types the code in the app. See Driver Mode for the driver's side.
Devices lists the phones and trackers of each vehicle. Unpair removes one at once: its next call is refused, and a shift it started ends.
Trackers and the positions API
A tracker is any device or system of yours that sends positions: a GPS unit with an HTTP client, or your own dispatch software. On the fleet's page, a vehicle, Add Tracker, give it a name, and Studio shows its key once. The key belongs to that vehicle.
curl https://api.kaleidr.com/live-api/v1/positions \
-H "Authorization: Bearer YOUR_DEVICE_KEY" \
-H "Content-Type: application/json" \
-d '{
"positions": [
{ "lat": 40.74110, "lng": -73.98970, "heading": 90, "speed": 8.3, "accuracy": 12,
"recorded_at": "2026-10-22T15:04:05Z" }
],
"sent_at": "2026-10-22T15:04:06Z"
}'
| Field | Rule |
|---|---|
positions | 1 to 100 points, in any order. The body is at most 64 KiB. |
lat, lng | Required. In range, and not both 0. |
heading | Degrees from north. |
speed | Meters per second. |
accuracy | Meters. A point less accurate than 100 meters is dropped. |
recorded_at | Required. When the position was measured: RFC 3339, or milliseconds since 1970. |
sent_at | When the batch was sent, by the device's clock. When it differs from Kaleidr's by more than 5 seconds and less than a day, every recorded_at is corrected by the difference; by a day or more, the batch is refused. |
The answer:
{
"accepted": 1,
"dropped": { "off_shift": 0, "stale": 0, "future": 0, "inaccurate": 0, "rate": 0, "duplicate": 0 },
"shift": { "id": "…", "state": "on", "ends_at": "2026-10-23T03:04:05Z" },
"min_interval_s": 10
}
| Dropped as | Why |
|---|---|
off_shift | Recorded outside every shift of the vehicle, or the vehicle is inactive. Never stored. |
stale | Recorded more than 12 hours ago. |
future | Recorded more than 30 seconds ahead of Kaleidr's clock. |
inaccurate | Less accurate than 100 meters, or a negative speed or accuracy. |
rate | Closer in time to the vehicle's previous point than your plan's update interval. |
duplicate | A point with the same recorded_at was already kept. |
GET /live-api/v1/device answers the device, its vehicle, the fleet and the open shift.
POST /live-api/v1/device/shift with { "action": "start" } or { "action": "end" } starts or ends the vehicle's
shift from the device.
| Status | error | Meaning |
|---|---|---|
| 400 | invalid_request | The body is malformed; field names the part. |
| 400 | clock_invalid | sent_at is a day or more from Kaleidr's clock. |
| 401 | unauthorized | No key, or an unknown one. |
| 401 | device_revoked | The device was removed in Studio. Stop sending. |
| 409 | off_shift | The batch had points, none fell in a shift, and no shift is open. Stop sending until a shift starts. |
| 413 | batch_too_large | More than 100 points, or more than 64 KiB. |
| 429 | rate_limited | More than 12 requests a minute from this device. Wait for Retry-After seconds. |
Errors are { "error": <code>, "message": <sentence> }. Send every 10 to 30 seconds while moving: a batch of
points is better than a request per point.
Connectors
A connector brings positions from a telematics system your vehicles already report to. Owners and admins add one on the fleet's page under Connectors, Add Connector. Connectors are on Pro and Enterprise.
| Connector | You give | How positions arrive |
|---|---|---|
| Samsara | An API Token with read access to vehicle locations | Kaleidr asks Samsara for new positions every Poll Every interval. |
| Geotab | Server (a geotab.com host), Database, Username, Password | Kaleidr asks Geotab for new log records every Poll Every interval. |
| Traccar | Nothing: Studio shows an ingest URL and a secret | Your Traccar server forwards each position. |
| Webhook | Nothing: Studio shows an ingest URL and a secret | Your system posts signed batches. |
- Credentials are write-only. Studio checks a Samsara or Geotab credential with one call before saving it, and never shows it again. Replace Credentials swaps it.
- The ingest secret is shown once. Rotate Secret issues a new one; the old one keeps working for 24 hours.
- Match By decides how a provider's vehicle finds yours: External ID (the default) or Name. A provider vehicle that matches none is listed under Unmatched Vehicles, with Add as Vehicle; its positions are dropped.
- Poll Every is at least 30 seconds, and never shorter than your plan's update interval.
- Status: Active; Paused, by you or because your plan allows fewer connectors; Failing after five failed polls in a row, still retried; Invalid when the provider refuses the credential, until you replace it. A paused or invalid Traccar or webhook connector refuses what is sent to it.
Connector positions still pass the shift rule.
Traccar
Add these lines to your Traccar server's configuration file, traccar.xml, with the URL and secret Studio showed,
and restart Traccar:
<entry key='forward.enable'>true</entry>
<entry key='forward.url'>https://api.kaleidr.com/live-api/v1/ingest/YOUR_CONNECTOR_ID/traccar</entry>
<entry key='forward.json'>true</entry>
<entry key='forward.header'>X-Kaleidr-Connector-Secret: YOUR_CONNECTOR_SECRET</entry>
A Traccar device matches a vehicle by its unique id (External ID) or its name. A position Traccar marks invalid is dropped.
Webhook
Post up to 100 points a request to the ingest URL, signed with the connector's secret:
import { createHmac } from 'node:crypto';
const body = JSON.stringify({
positions: [
{ vehicle: 'TRUCK-1', lat: 40.7411, lng: -73.9897, heading: 90, speed: 8.3, accuracy: 12,
recorded_at: '2026-10-22T15:04:05Z' },
],
});
const t = Math.floor(Date.now() / 1000);
const v1 = createHmac('sha256', process.env.KALEIDR_CONNECTOR_SECRET).update(`${t}.${body}`).digest('hex');
await fetch('https://api.kaleidr.com/live-api/v1/ingest/YOUR_CONNECTOR_ID/webhook', {
method: 'POST',
headers: { 'Content-Type': 'application/json', 'Kaleidr-Signature': `t=${t},v1=${v1}` },
body,
});
Kaleidr-Signatureist=<unix seconds>,v1=<hex HMAC-SHA256(secret, "<t>.<raw body>")>, the scheme of booking webhooks in the other direction.tmust be within 5 minutes of Kaleidr's clock, and the signature over the exact bytes you send.vehicleis the vehicle's external ID or name, as Match By says.speedis in meters per second,accuracyin meters, andrecorded_atRFC 3339 or milliseconds since 1970.- A bad signature is refused with 401
signature_invalid.
Shifts
A shift is the time a vehicle may be shown. At most one is open per vehicle, and it lasts at most 16 hours. It opens and closes in one of four ways:
| Opened by | Ends |
|---|---|
| Start Shift in Driver Mode | End Shift, or 16 hours later |
| A check-in | 30 minutes after the stop's window ends, Closed for Today, or 16 hours later |
| Start Shift on the vehicle in Studio | End Shift in Studio, or 16 hours later |
| The vehicle's shift hours, in a fleet whose Shift Mode is Scheduled Hours | The end of those hours |
- Off shift, nothing is published or kept. A position recorded outside every shift is dropped as it arrives. Only the count of dropped positions is kept, for the Usage fold.
- Ending a shift removes the vehicle from your maps at their next refresh.
- Connectors and trackers report all the time, so the shift decides. In a Manual fleet, their positions pass only while a shift opened by a driver, a check-in or Studio is open. In a Scheduled Hours fleet, the vehicle's shift hours open and close its shifts.
- Removing a device ends the shift it started.
Public precision
Privacy & Display on the fleet's page sets how precisely visitors see your vehicles:
| Public Precision | Visitors see | Heading and speed |
|---|---|---|
| Exact | The position to about 1 meter | Shown |
| Street, About 100 m (the default) | The position rounded to about 100 meters | Shown |
| Area, About 1 km | The position rounded to about 1 kilometer | Withheld |
- A vehicle checked in at a stop is shown at the stop's own position.
- Mark Stale After (30 to 900 seconds; 120 by default): a vehicle that has not reported for longer shows Last Seen 5 Min Ago.
- Hide After (60 to 3,600 seconds; 900 by default): a vehicle that has not reported for longer is not shown.
- Visitors see only each vehicle's name, kind, color, description, status, rounded position and the age of its last report, plus its heading and speed except at Area, About 1 km. Devices, external IDs and history are never published.
History and retention
You see each vehicle's track for a day under History, at full precision. History keeps at most one point every 30 seconds, or every update interval of your plan when that is longer, plus any point 200 meters or more from the last one kept. Points are deleted after your plan's history days, and never kept more than 90 days.
- Erase History (owners and admins) deletes every position and ended shift of a vehicle at once.
- Deleting a vehicle or a fleet deletes its history with it. Unpairing a device keeps the vehicle's history.
- A plan with fewer history days removes the extra history at the next daily cleanup.
Drivers are not Kaleidr accounts. Nothing here names a person beyond the device names you type.
Arrival estimates
The live layout shows how long a vehicle would take to reach its next stop, or a visitor who asks How Long to Me?. Every such time is an Estimate:
- It is worked out from the road distance and typical speeds. Traffic isn't included, and the vehicle's actual route may differ.
- It starts from the position visitors see, at the fleet's public precision.
- It is shown as a duration, About 12 Min, never as a time of arrival. With no road route, No Estimate.
- A visitor's own location is used for that estimate only, never stored or logged.
- Road routes are built from OpenStreetMap data, © OpenStreetMap contributors, under the ODbL.
Estimates are limited to 20 a minute for one visitor and 2,000 a day for one map. They do not count toward your Kaleidr AI usage.
Kaleidr maps only
Live vehicles draw on maps that use Kaleidr's own basemap: every embedded viewer, and Studio. Kaleidr Map does not draw a fleet's vehicles while it shows another provider's map. No vehicle position is sent to a third-party map provider.
Limits
| Limit | Free | Pro | Enterprise |
|---|---|---|---|
| Active vehicles across the organization | 2 | 25 | Set in your agreement |
| Days of position history | 1 | 30 | 90 |
| Shortest interval between a vehicle's points | 30 seconds | 10 seconds | 5 seconds |
| Connectors | None | 3 | Set in your agreement |
A fleet holds at most 500 vehicles. A limit stops new work only: an organization above one keeps what it has, except history past its plan's days, and connectors beyond its plan, which pause.
Usage on the fleet's page shows today's counts: positions accepted, positions dropped and why, visitor reads and estimates.