接口文档

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

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
}

车辆单日用氢量

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

查询车辆单日用氢量，单位 kg。

请求参数

字段	必填	说明
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；累计总里程沿用上一个有效统计周期，计算时间也显示该周期时间。

成功返回 · 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

返回最新位置、在线状态、速度、总里程、实际协议和记录时间。

请求参数

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

成功返回 · 200

{
  "data": [{
    "vin": "LA9GG68L2PBAF4790",
    "plateNumber": "浙F06618F",
    "sourceProtocol": "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	检测到数据异常，当前不返回可能错误的里程；dataQuality 给出原因。
dataQuality = TOTAL_MILEAGE_ROLLBACK	终端累计里程明显回退，已阻止其作为正常累计里程返回。

车辆单日用氢量

字段	说明
plateNumber / date	车牌与查询自然日（Asia/Shanghai）。
hydrogenConsumptionKg	当日用氢量，单位 kg；无有效数据时为 null。
status	NORMAL 表示已计算；NO_DATA 表示无可用统计。

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

字段	说明
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侧累计值。

车辆实时位置与状态

字段／枚举	说明
sourceProtocol	本条位置、速度、累计里程和记录时间实际采用的协议：GB32960、MQTT 或 JT808。
longitude / latitude	最新有效经纬度；无有效位置时为 null，locationAvailable 为 false。
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	当前不在线，或没有实时记录。
protocol	旧版兼容字段；新接入请使用 sourceProtocol。

加氢车辆停留核验

字段	说明
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。