REST API / V1
Vehicle History
REST API V1 resources, authentication and bounded reads.
Vehicle History provides the historical telemetry reported by an assigned tracking device during a specified time period. The vehicle needs a configured tracking source and available history.
Each history point represents a snapshot of the Vehicle Location model at a particular moment in time.
Historical telemetry is retrieved from the configured tracking provider and normalized into the Fleet Management tracking model.
List Vehicle History
Endpoint
GET https://api.tlgps.athear.ly/v1/vehicles/{vehicle}/history Authorization: Bearer <token> Accept: application/json
Returns a paginated collection of historical tracking points.
History availability
After authentication, ability, permission and visibility checks, the vehicle must have an assigned tracking device. Without one, the response is HTTP 409:
{ "message": "Vehicle history is unavailable because no tracking device is assigned." }
An assigned device without the required tracking configuration also returns HTTP 409, with message equal to Vehicle history is unavailable because tracking is not configured for its assigned device. No provider history request is made in either case. Contact authorized company staff to correct the assignment/configuration, then retry.
An inaccessible vehicle remains 404 and does not reveal its device state. Missing permission or token ability remains 403; missing/invalid authentication remains 401. A correctly configured device with no records for the period returns 200 with data: [] and pagination metadata. Tracker status metadata alone does not prevent a historical read. Genuine provider/internal failures remain server failures (500); they are not converted to empty history or prerequisite conflicts. Invalid dates/ranges/pagination return the normal 422 field validation response.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
vehicle |
UUID | Vehicle UUID |
Note
Resources are resolved by uuid rather than numeric identifiers.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
from |
datetime | Yes | Beginning of the requested period |
to |
datetime | Yes | End of the requested period |
page |
integer | No | Page number (default: 1) |
per_page |
integer | No | Results per page (default: 100, accepts: 1-100) |
Note
fromandtoare interpreted using the Fleet Management server timezone unless an explicit timezone offset is supplied.- Query parameters accept
YYYY-MM-DD HH:MM:SSwhile all response timestamps are returned as ISO-8601.
Example:
GET https://api.tlgps.athear.ly/v1/vehicles/01900000-0000-7000-8000-000000000001/history?from=2026-06-29T10:00:00&to=2026-06-29T12:00:00 Authorization: Bearer <token> Accept: application/json
Successful Response
{ "data": [ { "coordinates": { "latitude": 0.0, "longitude": 0.0 }, "geo_address": null, "speed": { "kmh": 43, "mps": 11.94 }, "gps_status": true, "angle": 174, "altitude": 5, "ignition": { "status": "on" }, "oil": 81, "voltage": 13.7, "mileage": { "km": 2485047, "meters": 2485047000 }, "temperature": "27", "timestamps": { "gps": "2026-06-29T10:02:55+02:00", "received": null, "last_synced": null } } ], "links": { "first": "https://api.tlgps.athear.ly/v1/vehicles/01900000-0000-7000-8000-000000000001/history?from=2026-06-29T10:00:00&to=2026-06-29T12:00:00&page=1", "last": "https://api.tlgps.athear.ly/v1/vehicles/01900000-0000-7000-8000-000000000001/history?from=2026-06-29T10:00:00&to=2026-06-29T12:00:00&page=1", "prev": null, "next": null }, "meta": { "current_page": 1, "last_page": 1, "per_page": 100, "total": 1 } }
Response Fields
| Field | Type | Description |
|---|---|---|
data |
array | Collection of History Point objects |
links |
object | Pagination links |
meta |
object | Pagination metadata |
History Point
History Point extends the Vehicle Location model by representing the state of a vehicle at a specific moment in time.
The primary difference is that each point represents the state of the vehicle at a specific moment in time rather than the current resolved state.
| Field | Description |
|---|---|
coordinates |
GPS coordinates |
geo_address |
Reverse geocoded address |
speed |
Vehicle speed |
gps_status |
GPS validity |
angle |
Vehicle Heading |
altitude |
Altitude |
ignition |
Ignition state |
oil |
Fuel sensor value |
voltage |
Device voltage |
mileage |
Odometer |
temperature |
Temperature sensor |
timestamps |
Tracking timestamps |
History Tracking Timestamps
For historical records:
| Field | Description |
|---|---|
gps |
Time reported by the tracking device |
received |
Always null |
last_synced |
Always null |
Note
- Historical records preserve the timestamp supplied by the tracking provider.
- History responses do not populate the live intake/synchronization timestamps; these values are
null. - Integrations relying on chronological tracking sequences must strictly utilize the device-generated
gpstimestamp for sorting or timeline auditing.
Note
- History preserves source ordering. If chronological order is required, parse and order points by their GPS timestamp.
- Use returned pagination metadata and links rather than assuming a fixed page count.
- Historical availability depends on the configured tracking provider.
- Some telemetry fields may be unavailable depending on the installed tracking hardware.
- Clients should use the returned pagination links when navigating large result sets.