Vehicle Data Platform API Contract

Response Envelope

All platform APIs return the same envelope:

{
  "data": {},
  "traceId": "trace-20260704000000.000000",
  "timestamp": 1783094400000
}

Pagination uses:

{
  "items": [],
  "total": 0,
  "limit": 20,
  "offset": 0
}

Vehicle Keyword

The platform is vehicle-first. Query APIs should accept keyword as the user-facing vehicle selector.

keyword may be:

VIN
plate
JT808 phone

The BFF resolves keyword through vehicle identity data before querying realtime, history, RAW, or mileage data. vin remains accepted as a compatibility alias on data query APIs, but new UI and integrations should send keyword.

If a keyword cannot be resolved to a VIN, data APIs must not fabricate a VIN. They should return empty result pages for vehicle data, while /api/vehicle-service exposes lookupResolved=false and quality issues for follow-up binding work.

Core Query APIs

Vehicle Service

GET /api/vehicle-service?keyword=粤AG18312

Returns one vehicle service view with identity, realtime summary, source coverage, history preview, RAW preview, mileage preview, and quality issues.

/api/vehicles/detail remains available as a compatibility alias. New UI and integrations should use /api/vehicle-service to make the vehicle-first boundary explicit.

Realtime Vehicles

GET /api/realtime/vehicles?keyword=粤AG18312&protocol=JT808&online=online&limit=50&offset=0

Returns VIN-level realtime rows. Protocol is a source filter, not a product boundary.

History Locations

GET /api/history/locations?keyword=粤AG18312&protocol=JT808&dateFrom=2026-07-03%2000:00:00&dateTo=2026-07-03%2023:59:59&limit=20&offset=0

Returns historical location points from TDengine, enriched with plate where possible.

RAW Frames

Short GET query:

GET /api/history/raw-frames?keyword=粤AG18312&protocol=GB32960&limit=20&offset=0&includeFields=true

Large field-filter query:

POST /api/history/raw-frames/query
Content-Type: application/json

{
  "keyword": "粤AG18312",
  "protocol": "GB32960",
  "dateFrom": "2026-07-03 00:00:00",
  "dateTo": "2026-07-03 23:59:59",
  "fields": ["gb32960.vehicle.speed_kmh", "gb32960.vehicle.total_mileage_km"],
  "includeFields": true,
  "limit": 20,
  "offset": 0
}

Use POST when fields may be long. parsedFields is returned only when includeFields=true or specific fields are requested.

Mileage

GET /api/mileage/daily?keyword=粤AG18312&protocol=JT808&dateFrom=2026-07-01&dateTo=2026-07-03&limit=20&offset=0
GET /api/mileage/summary?keyword=粤AG18312&protocol=JT808&dateFrom=2026-07-01&dateTo=2026-07-03

Returns daily mileage rows and aggregate mileage summary.

Compatibility Rule

Existing callers may still send vin. The BFF treats vin as a vehicle lookup value for compatibility, so vin=粤AG18312 still resolves through identity binding. New code should use keyword to avoid implying the value is already a real VIN.

3.0 KiB Raw Blame History