实时追踪

实时追踪会在你已发布的地图上显示车辆现在在哪里、今天在哪里停靠：例如餐车的路线、接驳车环线、流动诊所。访客会看到每辆在班车辆在地图上移动，今天的站点带有就在这里、营业中或今日停业，以及距下一站还有多久的预计。访客看到的内容请参阅实时布局。

它由三部分组成，都在 Kaleidr Studio 中：

部分	是什么
一个站点集合	时刻表：每个站点、其地址及每周的服务时段。它和其他地点资料库集合一样。
一个车队	你的车辆、它们的班次，以及访客看到它们的精度。在数据、车队下管理。
位置	每辆车的位置，来自以下四种来源之一：司机的签到链接、司机模式下的手机、你自己的追踪器，或连接你的车载信息服务提供商的连接器。

只有车辆在班时才会显示其位置。 在该车辆所有班次之外记录的位置会在到达时被丢弃：从不存储、从不显示，只计数。参阅班次。

车队

在数据下选择车队标签页，然后选择新建车队。为它命名并设置时区，如果有站点集合，则选择其站点集合。Studio 会创建一个同名的车辆集合：这个集合就是你地图上的车队，你可以像添加任何集合一样把它添加到地图。它不包含导入的地点；其中的车辆就是车队的车辆。

车队页面上的添加车辆可添加一辆：

字段	访客可见	用途
名称	是	车辆在地图和面板中的标签，例如“1 号餐车”。在车队内唯一。
类型	是	卡车、厢式货车、轿车、公交车、接驳车、船、小推车或自行车。
颜色	是	车辆在地图上的颜色。
描述	是	卡片上的一行简短说明，最多 200 个字符。
外部 ID	否	你自己的 ID，供连接器以及站点的车辆列匹配使用。
班次时间	否	按计划时间运营的车队中，班次所遵循的每周时间。参阅班次。

停用的车辆从不显示，其位置也会被丢弃。车队页面会以完整精度绘制车队的实时地图，仅供你查看。

所有者、管理员和成员管理车队和车辆；查看者可以查看。只有所有者和管理员可以删除车队、清除车辆的历史以及管理连接器。删除车队会删除车队及其车辆、设备、链接、班次、历史和连接器，然后删除其车辆集合。

站点时刻表

时刻表是一个站点集合。每个站点都是一个带有名称以及地址或坐标的地点，以下字段决定它何时提供服务：

字段	含义
营业时间	站点每周的服务时段，写法与营业时间相同：每天最多四个时段。时段可以跨越午夜，并归属于其开始的那一天。
时区	时段所用的时区。为空时使用集合的时区。
状态	`paused` 会让站点在每一天都停止。任何其他值或为空则保留。
车辆	服务该站点的车辆的名称或外部 ID。为空时为车队中的任意车辆。
服务日期	`YYYY-MM-DD` 格式的日期，用逗号或空格分隔。存在时，站点只在这些日期运营。

在某个日期，站点的时段为：

状态为 paused，或时区无效时：无；
有服务日期但该日期不在其中时：无；
没有营业时间时：如果服务日期列出了该日期则为全天，否则为无；
其他情况：当天是星期几就用哪天的营业时间。

当今天的某个时段包含当地时间，或昨天某个跨越午夜的时段包含当地时间时，站点即为正在营业。“今天”是车队时区中的日期。

站点	查询时间	时段	营业
营业时间周一 11:00–14:00	周一 12:00	11:00–14:00	是
同上	周一 15:00	11:00–14:00	否
同上，加上服务日期 `2026-11-02`	周一 2026-11-09，12:00	无	否
服务日期 `2026-11-02`，无营业时间	2026-11-02，09:00	全天	是
营业时间周一 11:00–14:00，状态 `Paused`	周一 12:00	无	否
营业时间周五 22:00–02:00	周六 01:00	周五的 22:00–02:00	是
营业时间周一 11:00–14:00，时区无效	周一 12:00	无	未知
服务日期 `2026-11-02, 2026-11-03 2026-11-04`，营业时间周一 11:00–14:00	周二 2026-11-03	周二的营业时间：无	否

模板生成器中的 Location 模板和下载示例表格可让你从一个已填写好的站点集合开始。

签到链接

签到链接让司机无需应用、无需账户，就能用任意手机浏览器标记车辆已到达某个站点。

在车队页面上创建一个：选择车辆，签到链接，创建链接。Studio 只显示一次该链接，并提供复制链接和可扫描的二维码。链接形如 https://map-embed.kaleidr.com/checkin.html#…。

每辆车一个链接， 有效期 180 天。替换链接会生成新链接并立即使旧链接失效；在手机丢失或司机离职时使用。撤销链接会使其失效。之后，Studio 只显示链接的最后四个字符、到期时间和上次使用时间。
链接就是钥匙。 任何持有它的人在站点附近都能为车辆签到。只与司机分享。
请在浏览器中打开。 该页面在其他页面的框架中无法工作。

司机页面显示车辆、今天的站点及其状态：

我已到达会读取一次手机位置，并在可及范围内的站点签到：范围为 250 米加上该读数的精度，且精度必须在 100 米以内。当范围内有多个站点或没有站点时，页面会列出今天的站点，由司机选择一个，该站点必须在 2,000 米以内。开启了允许在站点以外签到的车队还会提供非计划站点。
今日收工会把该车辆今天剩余的站点标记为今日停业并结束其班次。今日恢复营业可在当天清除这些标记，但不会开始班次。

签到会开启一个班次，持续到站点时段结束后 30 分钟，并在站点自身的位置显示车辆，而不是手机的位置。手机位置只用于查找站点，之后即被丢弃。在站点以外签到时，车辆会在手机位置（四舍五入到约 10 米）显示四个小时；如果车队的公开精度更粗，则按该精度取整。

司机模式下的手机

装有 Kaleidr 应用的司机手机会在司机班次期间共享车辆位置。在车队页面上选择车辆的配对手机，再选择显示配对码，会显示一个二维码和一个八位代码，有效期 10 分钟，且只能使用一次。司机用手机相机扫描二维码，或在应用中输入代码。司机这一侧的操作请参阅司机模式。

设备列出每辆车的手机和追踪器。取消配对会立即移除一个设备：它的下一次调用会被拒绝，由它开始的班次也会结束。

追踪器和位置 API

追踪器是你自己的任何发送位置的设备或系统：带 HTTP 客户端的 GPS 设备，或你自己的调度软件。在车队页面上选择车辆的添加定位器并为其命名，Studio 只会显示一次它的密钥。该密钥属于这辆车。

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"
  }'

字段	规则
`positions`	1 到 100 个点，顺序不限。正文最大 64 KiB。
`lat`, `lng`	必填。在有效范围内，且不能同时为 0。
`heading`	以正北为起点的角度。
`speed`	米每秒。
`accuracy`	米。精度差于 100 米的点会被丢弃。
`recorded_at`	必填。测量位置的时间：RFC 3339，或自 1970 年起的毫秒数。
`sent_at`	按设备时钟记录的批次发送时间。如果与 Kaleidr 的时钟相差超过 5 秒但不到一天，每个 `recorded_at` 都会按差值校正；相差一天或以上时，该批次会被拒绝。

响应：

{
  "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
}

丢弃原因	说明
`off_shift`	记录时间不在该车辆的任何班次内，或车辆已停用。从不存储。
`stale`	记录于 12 小时以前。
`future`	记录时间比 Kaleidr 的时钟超前 30 秒以上。
`inaccurate`	精度差于 100 米，或速度、精度为负值。
`rate`	与该车辆上一个点的时间间隔短于你套餐的更新间隔。
`duplicate`	已保留一个具有相同 `recorded_at` 的点。

GET /live-api/v1/device 返回设备、其车辆、车队和进行中的班次。POST /live-api/v1/device/shift 搭配 { "action": "start" } 或 { "action": "end" }，可从设备开始或结束车辆的班次。

状态	`error`	含义
400	`invalid_request`	正文格式错误；`field` 指出出错的部分。
400	`clock_invalid`	`sent_at` 与 Kaleidr 的时钟相差一天或以上。
401	`unauthorized`	没有密钥，或密钥未知。
401	`device_revoked`	设备已在 Studio 中被移除。停止发送。
409	`off_shift`	批次中有点，但没有一个落在班次内，且没有进行中的班次。在班次开始前停止发送。
413	`batch_too_large`	超过 100 个点，或超过 64 KiB。
429	`rate_limited`	此设备每分钟的请求超过 12 次。等待 `Retry-After` 指定的秒数。

错误的格式为 { "error": <code>, "message": <sentence> }。行驶中请每 10 到 30 秒发送一次：一批多个点比每个点一个请求更好。

连接器

连接器从你的车辆已在上报的车载信息服务系统获取位置。所有者和管理员可在车队页面的连接器、添加连接器中添加。连接器适用于 Pro 和 Enterprise。

连接器	你需要提供	位置如何到达
Samsara	一个对车辆位置有读取权限的 API 令牌	Kaleidr 按获取间隔向 Samsara 请求新位置。
Geotab	服务器（一个 `geotab.com` 主机）、数据库、用户名、密码	Kaleidr 按获取间隔向 Geotab 请求新的日志记录。
Traccar	无需提供：Studio 会显示接收 URL 和密钥	你的 Traccar 服务器转发每个位置。
Webhook	无需提供：Studio 会显示接收 URL 和密钥	你的系统发送已签名的批次。

凭据只写不读。 Studio 在保存 Samsara 或 Geotab 凭据前会调用一次进行检查，之后不再显示。替换凭据可更换它。
接收密钥只显示一次。 更换密钥会生成新密钥；旧密钥会继续有效 24 小时。
匹配方式决定提供商的车辆如何对应你的车辆：外部 ID（默认）或名称。没有匹配的提供商车辆会列在未匹配车辆下，并提供添加为车辆；其位置会被丢弃。
获取间隔至少 30 秒，且不短于你套餐的更新间隔。
状态：正常；已暂停，由你暂停或因你的套餐允许的连接器更少；出错，连续五次轮询失败后进入，仍会重试；无效，提供商拒绝凭据时进入，直到你替换凭据。已暂停或无效的 Traccar 或 webhook 连接器会拒绝发给它的数据。

来自连接器的位置同样要经过班次规则。

Traccar

使用 Studio 显示的 URL 和密钥，将以下几行添加到 Traccar 服务器的配置文件 traccar.xml 中，然后重启 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>

Traccar 设备通过其唯一 ID（外部 ID）或名称与车辆匹配。Traccar 标记为无效的位置会被丢弃。

Webhook

每个请求最多向接收 URL 发送 100 个点，并用连接器的密钥签名：

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-Signature 为 t=<unix seconds>,v1=<hex HMAC-SHA256(secret, "<t>.<raw body>")>，即预订 webhook 的方案，只是方向相反。t 必须在 Kaleidr 时钟的 5 分钟以内，签名必须覆盖你发送的确切字节。
vehicle 是车辆的外部 ID 或名称，取决于匹配方式。speed 以米每秒为单位，accuracy 以米为单位，recorded_at 为 RFC 3339 或自 1970 年起的毫秒数。
签名错误会以 401 signature_invalid 被拒绝。

班次

班次是车辆可以被显示的时间。每辆车最多只有一个进行中的班次，最长持续 16 小时。班次通过以下四种方式之一开始和结束：

由谁开始	何时结束
司机模式中的开始当班	结束当班，或 16 小时后
一次签到	站点时段结束后 30 分钟、今日收工，或 16 小时后
Studio 中车辆的开始当班	Studio 中的结束当班，或 16 小时后
当班模式为计划时间的车队中，车辆的班次时间	这些时间结束时

不在班时，不发布也不保留任何内容。 在所有班次之外记录的位置会在到达时被丢弃。只保留被丢弃位置的数量，用于用量部分。
结束班次会让车辆从你的地图上消失， 在地图下一次刷新时生效。
连接器和追踪器一直在上报，因此由班次决定。 在手动车队中，只有在由司机、签到或 Studio 开启的班次进行期间，它们的位置才会通过。在计划时间车队中，车辆的班次时间会开启和结束其班次。
移除设备会结束由它开始的班次。

公开精度

车队页面上的隐私与显示设置访客看到你车辆的精度：

公开精度	访客看到	方向和速度
精确	精确到约 1 米的位置	显示
街道，约 100 米（默认）	四舍五入到约 100 米的位置	显示
区域，约 1 公里	四舍五入到约 1 公里的位置	不显示

在站点签到的车辆显示在站点自身的位置。
标记为过时的时间（30 到 900 秒；默认 120）：超过这个时间未上报的车辆会显示 5 分钟前出现。
隐藏的时间（60 到 3,600 秒；默认 900）：超过这个时间未上报的车辆不再显示。
访客只能看到每辆车的名称、类型、颜色、描述、状态、四舍五入后的位置和距上次上报的时间；精度不是区域，约 1 公里时，还能看到方向和速度。设备、外部 ID 和历史从不公开。

历史与保留

你可以在历史下以完整精度查看每辆车某一天的轨迹。历史最多每 30 秒保留一个点（如果你套餐的更新间隔更长，则按该间隔），另外还会保留距上一个保留点 200 米或以上的任何点。超过你套餐的历史天数后，点会被删除，最长不超过 90 天。

清除历史（所有者和管理员）会一次删除车辆的所有位置和已结束的班次。
删除车辆或车队会一并删除其历史。取消设备配对不会删除车辆的历史。
历史天数较少的套餐会在下一次每日清理时删除多出的历史。

司机不是 Kaleidr 账户。这里除了你输入的设备名称外，没有任何能识别某个人的信息。

到达时间预计

实时布局会显示车辆到达下一站需要多久，或到达询问到我这里要多久？的访客需要多久。每一个这样的时间都是估计：

它根据道路距离和常规速度计算。不包含交通状况， 车辆的实际路线也可能不同。
它从访客看到的位置出发，即车队公开精度下的位置。
它以时长显示，例如 约 12 分钟，绝不显示为到达时刻。没有道路路线时显示 无法估计。
访客自己的位置只用于这次预计，从不存储或记录。

预计的次数限制为每位访客每分钟 20 次、每张地图每天 2,000 次。它们不计入你的 Kaleidr AI 用量。

仅限 Kaleidr 地图

实时车辆会绘制在使用 Kaleidr 自有底图的地图上：所有嵌入的 viewer 以及 Studio。Kaleidr Map 在显示其他提供商的地图时，不会绘制车队的车辆。任何车辆位置都不会发送给第三方地图提供商。

限制

限制	Free	Pro	Enterprise
整个组织的活跃车辆	2	25	按你的协议设定
位置历史天数	1	30	90
车辆相邻两点的最短间隔	30 秒	10 秒	5 秒
连接器	无	3	按你的协议设定

一个车队最多 500 辆车。限制只会阻止新的操作：超出限制的组织会保留已有内容，但超出套餐天数的历史会被删除，超出套餐的连接器会被暂停。

车队页面上的用量显示今天的计数：已接受的位置、被丢弃的位置及原因、访客读取次数和预计次数。

车队​

站点时刻表​

签到链接​

司机模式下的手机​

追踪器和位置 API​

连接器​

Traccar​

Webhook​

班次​

公开精度​

历史与保留​

到达时间预计​

仅限 Kaleidr 地图​

限制​

相关内容​

车队