Skip to content
TLGPSDocumentation

Developer documentation

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

  • from and to are interpreted using the Fleet Management server timezone unless an explicit timezone offset is supplied.
  • Query parameters accept YYYY-MM-DD HH:MM:SS while 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 gps timestamp 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.

Public documentation · authorized integration access required

Engineering-maintained documentation. Examples use synthetic data and placeholder credentials.

Back to top