RMap.

01 / 文档

从接口到终端，快速接入

按实际业务能力组织的快速入门文档。点击卡片查看调用入口、核心参数和下一步。

04 冰壶轨迹云在本站阅读：异步上传、沿路里程、结束行程与全轨迹。 ↓

冰壶 / 0.2.11 在线 · 接口 v1

一趟行程，从接入到回放

在本站看完常用接口和调用顺序。Service 属于业务，Terminal 对应司机终端，Trace 对应一次行程。

文档 0.3.1 · 冰壶（Curling）0.2.11 在线；接口路径保持 v1。

常用 API，一眼查阅

入口：https://lbs.lemonbus.cn
前缀：/api/curling/v1

方法路径用途
POST/services开通服务
POSTS/terminals创建终端
POSTT/traces开始行程
POSTR/uploads/prepare兼容检查（可省略）
POSTR/points上传定位点
GETR/uploads/status查询保存阶段（可选）
GETR/mileage只查里程
POSTR/finalize结束行程
GETR/trajectory获取全轨迹

S = /services/{service_id}
T = S/terminals/{terminal_id}
R = T/traces/{trace_id}

其它接口（完整清单）
GET/health健康状态（不带 API 前缀）
GET/demo/config公开示例配置
GET/demo/gcj02-track示例轨迹
POST/contact业务联系
GETS/terminals列出终端
DELETET删除终端及其数据
GETR/latest最新位置
GETR/track旧分页查询
GET/产品首页（本站代理路径 /gj/）

0.2.11已上线：新增原始折线、RM32吸附和去GPS往复后的多值里程；WAL上传与结束单对象归档流程不变。

上传成功表示本地 Trace 文件已可靠保存，不是 R2 归档。结束归档确认后才删除文件；司机建议保留原件至归档完成。里程仍非认证计费值。

客户端迁移：服务端 0.2.8/0.2.10 → 0.2.11（API v1 不变）
  1. 上传：保留 async 请求头、原始 JSON 和幂等键；HTTP 202 后改查 local_persisted=true，并核对 payload_sha256。不要再等待逐点 persisted=true，也不用逐点 prepare/status。没有这些字段时按旧版处理，不能仅凭 202 确认。
  2. 里程：继续读取 trace_distance_meters；0.2.11中它等于 distance_breakdown.cleaned_network_distance_meters，并可同时查看原始折线与清洗前RM32距离。兼容未知新增字段，不用 meter.estimated_distance_mm 覆盖v2业务值。
  3. 结束：先确认所有本地待上传批次，再 POST finalize（可带末批幂等键）；仅在 archived=true 且 persisted=true 后释放行程原件。失败或响应不确定时重试同一 Trace，不另建行程代替。
  4. 默认算法/重试：新 Trace 省略 meter_algorithm 即使用沿路里程，无可路由图返回 422；只有兼容需要才显式旧算法，既有 Trace 不变。升级前保全旧未落盘批次并按顺序重放；超时保留并重发同一字节和键；保留 422 原件排查。生产只访问 lbs.lemonbus.cn。

0.2.11 是服务端版本，不存在必须升级到“0.2.11”的客户端 SDK；需要修改的是调用方的确认、重试、里程取值和结单逻辑。

打开冰壶产品 ↗

推荐流程：一辆车，一次行程

  1. 开通服务 → 创建司机终端

    管理员开通一次，保存返回的 track_key。已有服务直接使用；司机终端可跨行程复用。

    POST /services
POST S/terminals

  2. 开始行程，默认沿路里程

    每单创建一个 Trace；省略算法字段即使用沿路里程，无可路由计量图返回 422，不静默回退。

    POST T/traces
meter_algorithm: omit to use server default

  3. 每 10 秒上传 → 本地保存 → 更新里程

    每批独立幂等键，原件重试不变。本地确认后发下一批，响应已含里程；无需逐点查询状态。

    POST R/points  [async compatible]
local_persisted=true; result.trace_distance_meters
GET R/mileage  [optional]

  4. 结束 → 一次归档 R2 → 获取全轨迹

    带末批幂等键结束行程，确认 archived=true；失败可重试，有争议时读取整条轨迹。

    POST R/finalize  [last batch key]
GET  R/trajectory?output_crs=wgs84
完整示例：Bash + curl + jq + shasum

先设置已有服务的 SID、TRACK_KEY；没有服务则设置 CURLING_ADMIN_TOKEN。管理员令牌仅留在后端。整段在自己的持久目录运行，24 个武汉低速路段示例点分次上传，原件与收据保留在新目录；真实司机 App 每 10 秒上传真实点。

结果不确定时，用保存的 .json 和 .key 原样重试。422 不阻塞下一合法批，保留原件排查。结束失败则重试同一 Trace 的 finalize，文件会保留。

RMAP DOCS