接口文档

面向合作方开放车辆用氢量、里程、实时状态及加氢车辆停留核验数据。每个接口独立说明请求参数、成功返回与异常情况。

Base URL https://open.d.lnoneos.com

认证与授权

所有接口均使用平台管理员签发的 32 位 appKey。appKey 有效期及车辆授权期必须完整覆盖查询时间。

请求头

Authorization: Bearer <YOUR_APP_KEY>
Content-Type: application/json

授权边界：不传车牌时，仅返回该 appKey 在查询日期或时间段内有效授权的全部车辆；显式传入的车牌未授权时，接口返回 403。所有接口响应均以两空格缩进的 JSON 返回，便于直接阅读和留存。

请求体样例

所有接口使用 Content-Type: application/json。以下 JSON 可直接复制；未列出的可选字段可省略。

车辆单日用氢量

/vehicles/hydrogen-consumption/query

{
  "date": "2026-08-06",
  "plateNumbers": ["浙F06618F"]
}

车辆单日里程

/vehicles/mileage/query

{
  "date": "2026-08-06",
  "plateNumbers": ["浙F06618F"],
  "protocolPriority": ["GB32960", "MQTT", "JT808"]
}

车辆区间日里程

/vehicles/mileage/range/query

{
  "startDate": "2026-08-01",
  "endDate": "2026-08-06",
  "pageSize": 100
}

指定时刻总里程

/vehicles/total-mileage/query

{
  "vin": "LA9GG68L2PBAF4790",
  "time": "2026-08-06 10:30:00",
  "protocol": "GB32960"
}

实时位置与状态

/vehicles/realtime/query

{
  "plateNumbers": ["浙F06618F"]
}

加氢车辆停留核验

/vehicles/stationary/query

{
  "startTime": "2026-08-06 10:00:00",
  "endTime": "2026-08-06 12:00:00",
  "longitude": 120.752312,
  "latitude": 30.746281,
  "coordinateSystem": "GCJ02",
  "radiusMeters": 8
}

加氢站地图点位

/hydrogen-stations/query

{
  "province": "浙江省",
  "city": "嘉兴市",
  "cooperateOnly": true
}

历史时刻剩余氢质量 · 1.10.0

POST/api/v1/vehicles/hydrogen-remaining/history/query

仅查询2026-08-01起的真实历史 event_time，不使用未来采样、实时值或日用氢量填补。最近氢相关帧异常或字段不全时显式返回，不跳过它找旧正常值。

请求参数

字段	必填	说明
queries	是	1–200项
queries[].requestId	是	本批唯一非空，最多128字节，原样回显
queries[].vin / time	是	VIN规范化大写17位且不含I/O/Q；北京时间yyyy-MM-dd HH:mm:ss，不可未来或早于2026-08-01
queries[].protocol	否	GB32960 / YUTONG_MQTT / JT808；省略固定GB32960，后两者当前UNSUPPORTED，不跨协议回退
maxTimeDifferenceSeconds	否	整数0–300，默认300；0要求精确命中

应用与逐车授权需同时覆盖查询时刻和采样时刻（结束时间不含端点）；FORBIDDEN不泄露采样元数据。当前appKey无效/过期为401，非法结构400。

请求示例（非真实读数）

{
  "queries": [{
    "requestId": "job-start",
    "vin": "LA9GG68L2PBAF4773",
    "time": "2026-08-03 16:02:43",
    "protocol": "GB32960"
  }],
  "maxTimeDifferenceSeconds": 300
}

合法批量HTTP200/SUCCESS，逐项状态判断：NORMAL、NO_DATA、MISSING、STALE、UNSUPPORTED、INVALID、FORBIDDEN、ERROR。非NORMAL质量null，不丢项，不补零。

每app每实例30批/60秒，最多2个并发批；429读取Retry-After秒后重试。整批9秒预算、4个工作协程，超时项ERROR而不是NO_DATA。200项是结构上限，不保证200个不同点均能按时完成；建议从20个不同点开始，超时缩小批量并退避重试。

历史容量需要历史适用版本；当前表不能回套历史。当前只有REPORTED质量可用，缺历史容量版本时不估算，返回MISSING。同批按规范化VIN+time+protocol去重，同点共享单次查询/授权结果和来源版本，所有requestId独立回显；不同点仍是非原子快照，保留各项版本和原始证据。质量保留原精度，Seeker自行计算两端净减少量并在负差值时归零。

车辆单日用氢量

POST/api/v1/vehicles/hydrogen-consumption/query

查询车辆单日用氢量，单位 kg。NORMAL + OK + PRELIMINARY 仅供初步监控；正式报表要求 FINAL 并核对证据与版本。两个日统计接口没有共同快照，区间缺失或不同不能直接计算百公里氢耗。

请求参数

字段	必填	说明
date	是	日期，格式 yyyy-MM-dd
plateNumbers	否	车牌数组；省略或 [] 时查询全部授权车辆

成功返回 · 200

{
  "code": "SUCCESS",
  "data": [{
    "plateNumber": "浙F06618F",
    "hydrogenConsumptionKg": 12.315,
    "status": "NORMAL"
  }]
}

400：日期或车牌格式不正确
401：appKey 无效、停用或过期
403：指定车辆未授权

车辆单日里程

POST/api/v1/vehicles/mileage/query

返回当日行驶里程、当日累计总里程和实际选用的数据协议，单位 km。

请求参数

字段	必填	说明
date	是	日期，格式 yyyy-MM-dd
plateNumbers	否	省略时查询全部授权车辆
protocolPriority	否	协议选源顺序，例如 ["GB32960","MQTT","JT808"]

缺数规则：日里程按同来源相邻日累计差计算；缺报日沿用累计值、日里程补 0（CARRIED_FORWARD），跨缺报期增量计入恢复日。首次基线、来源切换或累计回退返回 DATA_ANOMALY，日里程为 null。GPS 估算不参与本接口。

成功返回 · 200

{
  "code": "SUCCESS",
  "data": [{
    "dailyMileageKm": 182.437,
    "totalMileageKm": 12345.679,
    "sourceProtocol": "GB32960",
    "status": "NORMAL"
  }]
}

400：日期、车牌或协议参数错误
403：授权期未覆盖查询日
无统计：单车以 NO_DATA 返回

车辆区间日里程

POST/api/v1/vehicles/mileage/range/query

按车辆、日期分页返回区间日里程，最长查询区间为 366 天。

请求参数

字段	必填	说明
startDate / endDate	是	日期区间，yyyy-MM-dd
plateNumbers	否	车牌数组，最多 5000 辆
protocolPriority	否	协议选源顺序
pageSize / cursor	否	分页大小及下一页游标

成功返回 · 200

{
  "code": "SUCCESS",
  "data": [{
    "date": "2026-08-06",
    "dailyMileageKm": 182.437,
    "totalMileageKm": 12345.679
  }],
  "nextCursor": null
}

400：区间超限或游标与原参数不一致
403：授权未完整覆盖查询区间

指定时刻总里程

POST/api/v1/vehicles/total-mileage/query

按 VIN 返回不晚于指定时刻的最近一条总里程及实际采集协议。

请求参数

字段	必填	说明
vin	是	17 位已授权 VIN
time	是	北京时间 yyyy-MM-dd HH:mm:ss
protocol	否	GB32960、MQTT 或 JT808；省略时按默认顺序选取

成功返回 · 200

{
  "code": "SUCCESS",
  "data": {
    "totalMileageKm": 12345.678,
    "protocol": "GB32960",
    "recordTime": "2026-08-06 10:29:45",
    "timeDifferenceSeconds": 15
  }
}

400：VIN、时间或协议不合法
403：VIN 未授权
无记录：返回 NO_DATA

车辆实时位置与状态

POST/api/v1/vehicles/realtime/query

返回位置、在线状态、速度、总里程、储氢及独立 GPS 状态。储氢优先终端上报质量，缺质量可按同帧温压和 VIN 容积估算；百分比采用35 MPa、15°C满充参考，来源和质量分别说明。

比例 = 剩余质量 / PressureHydrogenMassKg(35,15,VIN容积) × 100。参考温度与密度比定义见 UNECE 定义文件；35 MPa 为本次业务参数，非所有车型额定压力的自动认证。

请求参数

字段	必填	说明
plateNumbers	否	省略或 [] 时返回全部当前有效授权车辆

成功返回 · 200

{
  "data": [{
    "vin": "LA9GG68L2PBAF4790",
    "plateNumber": "浙F06618F",
    "protocol": "GB32960",
    "longitude": 120.75,
    "latitude": 30.74,
    "speedKmh": 0,
    "totalMileageKm": 12345.678,
    "recordTime": "2026-08-17 17:40:12",
    "timeDifferenceSeconds": 8,
    "online": true,
    "activeToday": true,
    "motionStatus": "idle",
    "locationAvailable": true,
    "status": "NORMAL"
  }]
}

400：车牌格式错误
403：指定车牌未授权
无实时记录：返回 NO_DATA

加氢车辆停留核验

POST/api/v1/vehicles/stationary/query

按站点坐标、坐标系、时间段和半径，核验速度接近 0 的车辆停留记录，并按匹配度降序返回。

请求参数

字段	必填	说明
startTime / endTime	是	北京时间；查询区间最长 24 小时
longitude / latitude	是	加氢站经纬度；由 coordinateSystem 说明坐标系
coordinateSystem	否	WGS84（默认）或 GCJ02（高德）；GCJ02 自动转换后核验
radiusMeters	否	核验半径，单位 m；1–100，默认 5
plateNumbers	否	省略时核验全部有效授权车辆

匹配规则：速度 ≤ 3 km/h，至少 2 个样本且停留 ≥ 60 秒；相邻定位点间隔超过 10 分钟时拆分停留区间。

成功返回 · 200

{
  "data": [{
    "plateNumber": "浙F06618F",
    "stayStartTime": "2026-08-06 10:16:02",
    "stayEndTime": "2026-08-06 10:42:18",
    "stayDurationSeconds": 1576,
    "matchScore": 93.842
  }]
}

400：时间、坐标、坐标系或半径不合法
403：授权期未覆盖整个时间段
无匹配：data 为空数组

加氢站地图点位

POST/api/v1/hydrogen-stations/query

只读查询有有效坐标的加氢站，可按行政区划和合作属性筛选。

请求参数

字段	必填	说明
province / city	否	行政区划筛选
cooperateOnly	否	true 仅合作站；false 仅外部站

成功返回 · 200

{
  "data": [{
    "id": "1",
    "name": "示例加氢站",
    "longitude": 120.752312,
    "latitude": 30.746281,
    "cooperative": true
  }]
}

400：行政区划参数过长
401：appKey 无效
无符合站点：data 为空数组

返回字段与枚举说明

所有成功响应外层固定包含 code、message、data 和 traceId；以下为 data 内的字段。无数据时按对应接口返回 null、NO_DATA 或空数组。

通用响应与状态

字段／枚举	说明
code = SUCCESS	请求已成功处理。业务数据是否存在由每条数据的 status 判断。
message	成功时固定为 success。
traceId	本次请求唯一追踪标识；异常排查时请完整提供。
status = NORMAL	存在可用数据，相关数值、协议和时间字段有效。
status = NO_DATA	在授权范围内未找到可用数据；可选数值、位置、时间字段为 null 或省略。
status = DATA_ANOMALY	检测到数据异常，里程异常不返回可能错误的里程；用氢 SUSPECT 保留审计数值。原因分别见 dataQuality / qualityReason。
dataQuality = TOTAL_MILEAGE_ROLLBACK	终端累计里程明显回退，已阻止其作为正常累计里程返回。

车辆单日用氢量

字段	说明
vin / plateNumber / date	授权车辆 VIN、车牌与查询自然日（Asia/Shanghai）。
hydrogenConsumptionKg	当日用氢量，单位 kg；无有效数据时为 null。
status / qualityStatus	NORMAL / OK 为可用；DATA_ANOMALY / SUSPECT 保留数值供审计，不参与正常百公里氢耗；NO_DATA 不可用。
calculationPhase / algorithmVersion	PRELIMINARY 为初步监控结果，FINAL 为批量重算结果；历史结果仍可能再重算，保留实际版本。
statisticsStartTime / statisticsEndTime / updatedAt	证据包络起止和统计行更新时间；PRELIMINARY 开始时间为 null，结束为数据水位。与里程无共同快照保证。

车辆单日里程与区间日里程

字段	说明
vin / plateNumber / date	车辆唯一 VIN、车牌和统计自然日。
dailyMileageKm	当日行驶里程，单位 km。缺少当日记录且可前向补齐时为 0。
totalMileageKm	所选协议的日末累计总里程，单位 km；不会用 GPS 日里程估算值替代。
sourceProtocol	实际采用的协议：GB32960、MQTT 或 JT808。
dataTime	实际采用的最后一条车辆源数据时间。
updatedAt	该统计周期的计算时间；前向补齐时保持上一有效统计周期时间。
snapshotId / nextCursor	仅区间接口返回；snapshotId 固定本次分页车辆范围，nextCursor 为下一页游标，最后一页为 null。

指定时刻总里程

字段	说明
vin / queryTime	查询车辆 VIN 与请求的北京时间。
totalMileageKm	不晚于请求时间的最近一条累计总里程，单位 km。
protocol / protocolInput	protocol 为实际命中协议；protocolInput 为请求显式传入的协议，未传则省略。
recordTime / timeDifferenceSeconds	实际命中记录时间，以及请求时间与记录时间的差值，单位秒。
mileageMeaning	该协议累计里程的业务口径；JT808 为定位终端/GPS侧累计值。

车辆实时位置与状态

字段／枚举	说明
protocol	本条位置、速度、累计里程和记录时间实际采用的协议：GB32960、MQTT 或 JT808。
remainingHydrogenKg / remainingHydrogenPercent	全车储氢 kg / %，真实零保留。质量优先终端上报，缺值可用同帧温压和 VIN 容积估算；百分比按35 MPa、15°C满充质量计算，缺条件独立返回 null。
hydrogenRecordTime / hydrogenDataStatus	同帧采集时间和聚合状态 NORMAL / PARTIAL / STALE / MISSING / UNSUPPORTED / INVALID；必须同时检查两个字段级状态。
gpsFixStatus / locationRecordTime / coordinateSystem	真实定位位、位置采集时间和 WGS84 / GCJ02 / UNKNOWN。离线不清除历史 FIXED，陈旧不证明无定位。
longitude / latitude	无有效位置或 NO_FIX 时为 null，locationAvailable 为 false；UNKNOWN 坐标系需由调用方确认后上图。
speedKmh / totalMileageKm	所选来源的瞬时速度（km/h）和累计总里程（km）。
recordTime / timeDifferenceSeconds	所选来源的记录时间，以及与当前查询时间的差值，单位秒。
online	true：任一协议最近 60 秒内上报；false：没有任一协议满足该实时阈值。
activeToday	true：任一协议在当前自然日曾上报；不等同于实时 online。
motionStatus = driving	在线且所选来源速度大于 3 km/h。
motionStatus = idle	在线且所选来源速度不大于 3 km/h。
motionStatus = offline	当前不在线，或没有实时记录。

加氢车辆停留核验

字段	说明
stayStartTime / stayEndTime	满足核验条件的连续停留开始、结束时间。
stayDurationSeconds / stayDurationMinutes	停留时长，分别以秒、分钟表示。
matchScore	0–100；位置越接近、速度越低、停留越久、样本越充分，分数越高。
averageDistanceMeters / maxDistanceMeters	定位点相对输入站点坐标的平均/最大距离，单位 m。
averageSpeedKmh / maxSpeedKmh / matchedSamples	核验区间内速度统计与匹配定位样本数。
sourceProtocols	本停留片段采用过的协议数组，枚举值为 GB32960、MQTT、JT808。

加氢站地图点位

字段	说明
id / name / shortName	站点唯一标识、标准名称和简称；id 为字符串以避免 JavaScript 精度丢失。
address / province / city / district	站点地址及行政区划。
longitude / latitude	站点坐标。
cooperative	true：合作站（内部站或已导入合作名录）；false：外部站。

总里程协议口径

未指定 protocol 时，按 GB32960 > MQTT > JT808 选择第一个有数据的协议；不会跨协议拼接里程。

规范值	总里程含义
GB32960	车辆仪表盘累计总里程，对应 GB/T 32960 整车数据累计里程。
MQTT	车辆仪表盘或车端控制器累计总里程，由 MQTT 平台上报。
JT808	定位终端累计里程，由 GPS／终端侧计算，不等同于车辆仪表盘里程。

异常与状态码

所有响应均包含 code、message 和 traceId；请在工单中提供 traceId 以便排查。

HTTP	code	说明
200	SUCCESS	查询成功；无统计数据时，数据行的 status 为 NO_DATA。
400	INVALID_REQUEST	请求格式、数量、日期、时间、坐标或协议不正确。
401	UNAUTHORIZED	appKey 不存在、停用或已过期。
403	FORBIDDEN	车辆或 appKey 授权期未覆盖请求时间。
500	INTERNAL_ERROR	服务内部异常；请提供 traceId。