Skip to content
TLGPSDocumentation

Developer documentation

REST API / V1

REST API V1

REST API V1 resources, authentication and bounded reads.

Overview

REST API V1 provides authorized reads of visible companies, vehicles, current vehicle context and available history.

The API is designed for customer portals, mobile applications, enterprise integrations, reporting systems, and third-party software.

All resources are uniquely identified using UUIDs. Clients authenticate using Personal Access Tokens and only receive data they are authorized to access. Protected REST access also requires the REST API service to be enabled for the token owner's Company.

The response model represents supported tracking data. Field availability depends on the configured tracking source and device.


Base URL

Configured public base URL:

https://api.tlgps.athear.ly/v1

Use the base URL supplied for your environment. All identities, vehicles and locations in these examples are synthetic. Credential values are placeholders, not usable tokens.


API Version

Current version: V1

The version is included in the request URL.

Example:

GET https://api.tlgps.athear.ly/v1/vehicles

Future versions may introduce new endpoints or capabilities while maintaining backward compatibility whenever possible.

Changelog

V1.0

  • Companies API
  • Vehicles API
  • Vehicle Location
  • Vehicle History
  • Tracking Filters
  • Personal Access Token authentication

API Conventions

UUIDs

Resource identifiers are UUIDs. Use the UUID returned by TLGPS rather than a numeric database identifier.

Example:

01900000-0000-7000-8000-000000000001

Datetimes

Note

Unless otherwise specified, all datetime values are returned using the Fleet Management server timezone in ISO-8601 format.

Example:

"2026-06-29T23:47:43+02:00"

Null Values

Fields that are unavailable or unsupported by the tracking device are returned as null.

Important

Clients should not assume optional fields are always present.


Rate Limiting

No fixed application-level REST request-rate limit is defined by the current V1 route configuration. Deployment-level limits may differ. Do not assume an unlimited allowance; confirm operational limits with your TLGPS contact.


Authentication

All fleet-resource endpoints require Bearer Token authentication. The health endpoint is public.

Use HTTPS for deployed integrations. A local development environment may use HTTP; transport security is an environment responsibility, not a guarantee made by these routes.

Authorization: Bearer <access-token>

Requests without a valid Personal Access Token receive

401 Unauthorized

Example:

GET https://api.tlgps.athear.ly/v1/vehicles
Authorization: Bearer <access-token>
Accept: application/json

Response

{
    "message": "Unauthenticated."
}

Authorization

Every protected request is evaluated using independent credential, application, and resource-scope layers. A token ability never grants an application permission, and an owner's permission never expands a narrowly scoped token.

After authentication, the token owner's active Company must have REST API access enabled. The owner must have the effective permission for the requested operation. The token ability is an additional restriction; it cannot expand the owner's permissions. Policies and current data visibility constrain the resources returned.

Service or Company access being unavailable returns 403 Forbidden. An invalid or expired credential returns 401 Unauthorized. Contact an authorized company administrator or your TLGPS contact if access needs to be reviewed.

Token Abilities

Each Personal Access Token defines which API capabilities are available.

Current REST operations require these exact abilities:

Operation Required ability
GET /companies companies.view-any
GET /companies/{company} companies.view
GET /vehicles vehicles.view-any
GET /vehicles/{vehicle} vehicles.view
GET /vehicles/{vehicle}/history vehicles.history

telemetry.subscribe is a Gateway ability and does not authorize REST fleet operations.

If a token lacks the required ability, the API returns

403 Forbidden

The token owner must also retain the matching effective application permission within the Company's available capabilities. Permissions, token abilities and resource visibility are separate checks.

The public GET /health endpoint reports API process liveness. It is not a Company entitlement check and remains available without a token or enabled Company service.

Resource Visibility

A valid token does not automatically grant access to every resource. Every authenticated request is filtered according to the authenticated user's visibility. Applications only receive companies and vehicles they are permitted to access. A deactivated source Company and its fleet are excluded from effective visibility even when the directional visibility relationship remains stored. Restoring the source Company restores that relationship without reconfiguration.

A Company may see its own resources and any additional scope explicitly made available to it. Authentication or a token ability alone does not grant visibility. This scope is evaluated on resource reads.


Available Endpoints

Method Endpoint Description
GET /health Public API liveness
GET /companies List visible companies
GET /companies/{company} Get company details
GET /vehicles List vehicles
GET /vehicles/{vehicle} Get vehicle
GET /vehicles/{vehicle}/history Vehicle history

Response Format

Collection endpoints return paginated responses.

{
    "data": [],
    "links": {},
    "meta": {}
}

Single-resource endpoints return

{
    "data": {}
}

Note

The exact structure of each resource is documented in the corresponding endpoint section.

Pagination

Collection endpoints use Laravel's standard pagination format.

Example:

{
    "data": [...],
    "links": {
        "first": "...",
        "last": "...",
        "prev": null,
        "next": "..."
    },
    "meta": {
        "current_page": 1,
        "last_page": 8,
        "per_page": 50,
        "total": 364
    }
}

Important

Clients should use the provided navigation links rather than constructing pagination URLs manually.

Error Handling

The API uses standard HTTP status codes.

Validation failures return a structured error response.

Example:

{
    "message": "The given data was invalid.",
    "errors": {
        "from": [
            "The from field is required."
        ]
    }
}

Note

Error responses may contain one or more validation messages depending on the request.


HTTP Status Codes

Code Message Description
200 OK The request completed successfully.
400 Bad Request The request is malformed or contains invalid parameters.
401 Unauthorized Authentication is required or the provided access token is invalid.
403 Forbidden The authenticated token does not have permission to perform the requested action.
404 Not Found The requested resource does not exist or is not visible to the authenticated user.
422 Unprocessable Entity One or more validation rules failed.
500 Internal Server Error An unexpected server error occurred while processing the request.

Endpoints

Health

GET https://api.tlgps.athear.ly/v1/health

The health endpoint is unauthenticated and returns a minimal process-liveness response. It does not test external tracking providers or expose configuration details.

{
    "status": "ok"
}

Companies

Companies represent fleet owners or customer organizations within the Fleet Management System. The authenticated user only receives companies they are authorized to access.


Company Object

Field Type Description
uuid UUID Unique company identifier
name string Company name
vehicles_count integer Number of vehicles belonging to the company

Example:

{
    "uuid": "01900000-0000-7000-8000-000000000002",
    "name": "Northstar Fleet Operations",
    "vehicles_count": 82
}

List Companies

Returns a paginated collection of companies visible to the authenticated user.

Endpoint
GET https://api.tlgps.athear.ly/v1/companies
Authorization: Bearer <token>
Accept: application/json

Query Parameters

This endpoint currently does not support filtering.


Example:

GET https://api.tlgps.athear.ly/v1/companies
Authorization: Bearer <token>
Accept: application/json

Successful Response
{
    "data": [
        {
            "uuid": "01900000-0000-7000-8000-000000000002",
            "name": "Northstar Fleet Operations",
            "vehicles_count": 82
        },
        {
            "uuid": "01900000-0000-7000-8000-000000000003",
            "name": "Example Fleet Company",
            "vehicles_count": 154
        }
    ],
    "links": {
        "first": "https://api.tlgps.athear.ly/v1/companies?page=1",
        "last": "https://api.tlgps.athear.ly/v1/companies?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "last_page": 1,
        "per_page": 15,
        "total": 2
    }
}
Response Fields
Field Type Description
data array Collection of Company objects
links object Pagination links
meta object Pagination metadata

Get Company

Returns a single company visible to the authenticated user.

Endpoint
GET https://api.tlgps.athear.ly/v1/companies/{company}
authorization: bearer <access-token>
accept: application/json

Path Parameters
Parameter Type Description
company UUID Company UUID

Note

Resources are resolved by uuid rather than numeric identifiers.


Example:

GET https://api.tlgps.athear.ly/v1/companies/01900000-0000-7000-8000-000000000002
Authorization: Bearer <token>
Accept: application/json

Successful Response
{
    "data": {
        "uuid": "01900000-0000-7000-8000-000000000002",
        "name": "Northstar Fleet Operations",
        "vehicles_count": 82
    }
}

Possible Responses
Status Description
200 Company returned successfully
401 Authentication required
403 Token lacks required ability
404 Company not found or not visible to the authenticated user

Note

  • Only companies visible to the authenticated user are returned.
  • Company UUIDs are immutable.
  • vehicles_count reflects the number of vehicles currently associated with the company.

Vehicles

Vehicles represent the primary tracked assets within the Fleet Management System.

Each vehicle contains its static information (plate number, manufacturer, ownership, etc.) together with its latest resolved tracking state, when available.

Only vehicles visible to the authenticated user are returned.


Vehicle Object

Field Type Description
uuid UUID Vehicle identifier
plate_number string | null Vehicle registration number
brand string | null Manufacturer
model string | null Vehicle model
color string | null Vehicle color
chassis_number string | null Vehicle chassis (VIN)
engine_number string | null Engine number
company Company Vehicle owner
location Vehicle Location | null Latest resolved vehicle location.

Example:

{
    "uuid": "01900000-0000-7000-8000-000000000001",
    "plate_number": "NF-241",
    "brand": "Astra",
    "model": "M588FS",
    "color": "White",
    "chassis_number": null,
    "engine_number": null,
    "company": {
        "uuid": "01900000-0000-7000-8000-000000000002",
        "name": "Northstar Fleet Operations"
    },
    "location": {
        "source": "realtime",
        "status": {
            "connection": "online",
            "movement": "moving"
        },
        "coordinates": {
            "latitude": 0.0,
            "longitude": 0.0
        },
        "geo_address": null,
        "speed": {
            "kmh": 62,
            "mps": 17.22
        },
        "gps_status": true,
        "angle": 175,
        "altitude": 12,
        "ignition": {
            "status": "on"
        },
        "oil": 81,
        "voltage": 13.7,
        "mileage": {
            "km": 2485047,
            "meters": 2485047000
        },
        "temperature": "28",
        "timestamps": {
            "gps": "2026-06-29T23:47:43+02:00",
            "received": "2026-06-29T23:47:43+02:00",
            "last_synced": null
        }
    }
}

List Vehicles

Returns a paginated collection of vehicles visible to the authenticated user.

Important

If a client explicitly requests a non-visible uuid (e.g., GET /vehicles/{unauthorized_uuid}), the system will return a 404 Not Found rather than a 403 Forbidden to prevent resource-existence probing across tenants.

Endpoint
GET https://api.tlgps.athear.ly/v1/vehicles
authorization: bearer <access-token>
accept: application/json

Query Parameters

Vehicles may be filtered using one or more query parameters.

When multiple filters are supplied, they are combined using logical AND.


Successful Response
{
    "data": [
        {
            "uuid": "01900000-0000-7000-8000-000000000001",
            "plate_number": "NF-241",
            "brand": "Astra",
            "model": "M588FS",
            "company": {
                "uuid": "01900000-0000-7000-8000-000000000002",
                "name": "Northstar Fleet Operations"
            },
            "location": {
                "source": "realtime",
                "status": {
                    "connection": "online",
                    "movement": "moving"
                },
                "coordinates": {
                    "latitude": 0.0,
                    "longitude": 0.0
                },
                "geo_address": null,
                "speed": {
                    "kmh": 62,
                    "mps": 17.22
                },
                "gps_status": true,
                "angle": 175,
                "altitude": 12,
                "ignition": {
                    "status": "on"
                },
                "oil": 81,
                "voltage": 13.7,
                "mileage": {
                    "km": 2485047,
                    "meters": 2485047000
                },
                "temperature": "28",
                "timestamps": {
                    "gps": "2026-06-29T23:47:43+02:00",
                    "received": "2026-06-29T23:47:43+02:00",
                    "last_synced": null
                }
            }
        }
    ],
    "links": {
        "first": "https://api.tlgps.athear.ly/v1/vehicles?page=1",
        "last": "https://api.tlgps.athear.ly/v1/vehicles?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "last_page": 1,
        "per_page": 15,
        "total": 1
    }
}
Response Fields
Field Type Description
data array Collection of Vehicle objects
links object Pagination links
meta object Pagination metadata

Identification Filters
Parameter Type Description
uuid UUID Vehicle UUID
plate_number string Exact plate number

Example:

GET https://api.tlgps.athear.ly/v1/vehicles?plate_number=NF-241
Authorization: Bearer <access-token>
Accept: application/json

Company Filters
Parameter Type Description
company UUID Company UUID
company_name string Partial company name

Example:

GET https://api.tlgps.athear.ly/v1/vehicles?company=<company_uuid>
Authorization: Bearer <access-token>
Accept: application/json

Vehicle Filters
Parameter Type Description
brand string Vehicle manufacturer
model string Vehicle model
tracked boolean Only tracked or untracked vehicles

Example:

GET https://api.tlgps.athear.ly/v1/vehicles?tracked=true
authorization: bearer <access-token>
accept: application/json
GET https://api.tlgps.athear.ly/v1/vehicles?brand=Astra
authorization: bearer <access-token>
accept: application/json

Tracking Filters

Tracking filters operate on the latest resolved vehicle state index, not historical records.

connection, movement and ignition accept only the values listed below. Missing or empty optional values do not filter the collection. Invalid values, including array-shaped values, return HTTP 422 with the normal message and errors object; the error key is the affected filter. Valid filters can be combined and their matches are intersected.

{
    "message": "The selected connection is invalid.",
    "errors": { "connection": ["The selected connection is invalid."] }
}

Human-readable validation messages may vary; use the status and field keys.

Connection

Value
online
offline

Example:

GET https://api.tlgps.athear.ly/v1/vehicles?connection=online
authorization: bearer <access-token>
accept: application/json

Movement

Value
moving
parked
idling
no_gps

Example:

GET https://api.tlgps.athear.ly/v1/vehicles?movement=moving
authorization: bearer <access-token>
accept: application/json

Ignition

Value
on
off

Example:

GET https://api.tlgps.athear.ly/v1/vehicles?ignition=on
authorization: bearer <access-token>
accept: application/json

GPS

Value
true
false

Example:

GET https://api.tlgps.athear.ly/v1/vehicles?gps=false
authorization: bearer <access-token>
accept: application/json

The search parameter performs a case-insensitive search across multiple vehicle fields and partial matches are supported.

Supported fields

  • Plate number
  • Company name
  • Brand
  • Model
  • Engine number
  • Chassis number

Example:

GET https://api.tlgps.athear.ly/v1/vehicles?search=Mercedes
authorization: bearer <access-token>
accept: application/json

Sorting

Supported sort fields

  • plate_number
  • brand
  • model

Important

  • Descending order is indicated using a leading -
  • Only one sort field may be specified per request.

Example:

GET https://api.tlgps.athear.ly/v1/vehicles?sort=plate_number
authorization: bearer <access-token>
accept: application/json
GET https://api.tlgps.athear.ly/v1/vehicles?sort=-model
authorization: bearer <access-token>
accept: application/json

Combining Filters

Multiple filters may be combined.

Example:

GET https://api.tlgps.athear.ly/v1/vehicles?company=<company_uuid>&connection=online&movement=moving&ignition=on&gps=true&tracked=true&sort=plate_number
authorization: bearer <access-token>
accept: application/json

Important

This request returns only vehicles that satisfy all supplied filters.

Caution

Replace <company_uuid> with a Company UUID visible to the token owner.


Successful Response
{
    "data": [
        {
            "uuid": "01900000-0000-7000-8000-000000000001",
            "plate_number": "NF-241",
            "brand": "Astra",
            "model": "M588FS",
            "company": {
                "uuid": "01900000-0000-7000-8000-000000000002",
                "name": "Northstar Fleet Operations"
            },
            "location": {
                "source": "realtime",
                "status": {
                    "connection": "online",
                    "movement": "moving"
                },
                "coordinates": {
                    "latitude": 0.0,
                    "longitude": 0.0
                },
                "geo_address": null,
                "speed": {
                    "kmh": 62,
                    "mps": 17.22
                },
                "gps_status": true,
                "angle": 175,
                "altitude": 12,
                "ignition": {
                    "status": "on"
                },
                "oil": 81,
                "voltage": 13.7,
                "mileage": {
                    "km": 2485047,
                    "meters": 2485047000
                },
                "temperature": "28",
                "timestamps": {
                    "gps": "2026-06-29T23:47:43+02:00",
                    "received": "2026-06-29T23:47:43+02:00",
                    "last_synced": null
                }
            }
        }
    ],
    "links": {
        "first": "https://api.tlgps.athear.ly/v1/vehicles?company=<uuid>&connection=online&movement=moving&page=1",
        "last": "https://api.tlgps.athear.ly/v1/vehicles?company=<uuid>&connection=online&movement=moving&page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "last_page": 1,
        "per_page": 15,
        "total": 1
    }
}
Response Fields
Field Type Description
data array Collection of Vehicle objects
links object Pagination links
meta object Pagination metadata

Get Vehicle

Returns a single vehicle.

Endpoint
GET https://api.tlgps.athear.ly/v1/vehicles/{vehicle}
Authorization: Bearer <token>
Accept: application/json

Path Parameters
Parameter Type Description
vehicle UUID Vehicle UUID

Note

Resources are resolved by uuid rather than numeric identifiers.


Example:

GET https://api.tlgps.athear.ly/v1/vehicles/01900000-0000-7000-8000-000000000001
Authorization: Bearer <token>
Accept: application/json

Successful Response
{
    "data": {
        "uuid": "01900000-0000-7000-8000-000000000001",
        "plate_number": "NF-241",
        "brand": "Astra",
        "model": "M588FS",
        "company": {
            "uuid": "01900000-0000-7000-8000-000000000002",
            "name": "Northstar Fleet Operations"
        },
        "location": {
            "source": "realtime",
            "status": {
                "connection": "online",
                "movement": "moving"
            },
            "coordinates": {
                "latitude": 0.0,
                "longitude": 0.0
            },
            "geo_address": null,
            "speed": {
                "kmh": 62,
                "mps": 17.22
            },
            "gps_status": true,
            "angle": 175,
            "altitude": 12,
            "ignition": {
                "status": "on"
            },
            "oil": 81,
            "voltage": 13.7,
            "mileage": {
                "km": 2485047,
                "meters": 2485047000
            },
            "temperature": "28",
            "timestamps": {
                "gps": "2026-06-29T23:47:43+02:00",
                "received": "2026-06-29T23:47:43+02:00",
                "last_synced": null
            }
        }
    }
}

Possible Responses
Status Description
200 Vehicle returned successfully
401 Authentication required
403 Token lacks required ability
404 Vehicle not found or not visible to the authenticated user

Note

  • Vehicles are always filtered according to the authenticated user's visibility.
  • Tracking filters operate on the latest resolved vehicle state.
  • Vehicles without an assigned tracking device may return location: null.
  • Real-time state is automatically preferred over the last synchronized database state whenever available.

Vehicle Location

The location object represents the latest resolved state of a vehicle.

REST V1 formats timestamps.gps, timestamps.received and timestamps.last_synced as ISO-8601 strings in the configured application timezone, at second precision, or null. For example: 2026-10-20T09:08:09+02:00. Formatting does not alter the source state. Gateway V1 retains UTC with six fractional digits for these same state timestamps; compare parsed instants at the precision provided, not raw strings.

For the same resolved snapshot, both transports use the same coordinate numbers, speed/distance units and rounding, status values, optional booleans and nulls. A missing address is null. REST's address contains display_name, city, state, country and country_code; Gateway additionally retains place_id, osm_type and osm_id for V1 compatibility. Those are geocoder references, not private TLGPS database/device identifiers. Serialization uses the already available snapshot address and does not perform reverse geocoding. The REST resource and Gateway message envelopes remain different.

It represents supported tracking data in the TLGPS response model. Whenever possible, the Fleet Management System returns the latest Real-time state. If Real-time data is unavailable, the most recently synchronized database state is returned.

If the vehicle has no assigned tracking device or no location is available, the value will be null.


Vehicle Location Object
Field Type Description
source string Origin of the resolved location
status object Vehicle operational state
coordinates Coordinates | null Latest GPS coordinates
geo_address Geo Address | null Reverse geocoded address
speed Speed | null Current speed
gps_status boolean | null Indicates whether the GPS fix is valid
angle integer | null Vehicle Heading in degrees
altitude number | null Altitude reported by the tracking device
ignition Ignition | null Ignition state
oil number | null Fuel level or fuel sensor reading
voltage number | null Device or vehicle voltage
mileage Distance | null Total reported distance
temperature string | null Temperature sensor reading
timestamps Tracking Timestamps Relevant tracking timestamps

Example:

{
    "location": {
        "source": "realtime",
        "status": {
            "connection": "online",
            "movement": "moving"
        },
        "coordinates": {
            "latitude": 0.0,
            "longitude": 0.0
        },
        "geo_address": null,
        "speed": {
            "kmh": 62,
            "mps": 17.22
        },
        "gps_status": true,
        "angle": 175,
        "altitude": 12,
        "ignition": {
            "status": "on"
        },
        "oil": 81,
        "voltage": 13.7,
        "mileage": {
            "km": 2485047,
            "meters": 2485047000
        },
        "temperature": "28",
        "timestamps": {
            "gps": "2026-06-29T23:47:43+02:00",
            "received": "2026-06-29T23:47:43+02:00",
            "last_synced": null
        }
    }
}

Source

Indicates where the resolved location originated.

Value Description
realtime Live telemetry received through the Real-time gateway
database Last synchronized state stored in Fleet Management

Note

Real-time data is always preferred over synchronized database data whenever available.

Status

The status object summarizes the current operational state of the vehicle.

{
    "status": {
        "connection": "online",
        "movement": "moving"
    }
}

Connection Status

Represents communication between the tracking device and the platform.

Possible values

Value Description
online Device is currently communicating with the platform
offline Device has not reported recently

Movement Status

Represents the interpreted movement state.

Possible values

Value Description
moving Vehicle is moving
idling Engine is running but vehicle is stationary
parked Vehicle is stationary
no_gps The resolved state lacks a usable GPS/speed basis for movement classification

Coordinates

GPS coordinates expressed in decimal degrees.

{
    "latitude": 0.0,
    "longitude": 0.0
}

Geo Address

Human-readable address obtained through reverse geocoding. This field is null when an address is unavailable on the resolved snapshot.

{
    "display_name": "...",
    "city": "...",
    "state": "...",
    "country": "...",
    "country_code": "ly"
}

Speed

Current vehicle speed.

{
    "kmh": 80,
    "mps": 22.22
}

GPS Status

Boolean indicating whether the GPS coordinates represent a valid satellite fix.

Value Description
true Valid GPS fix
false Invalid GPS fix

Heading

angle represents the vehicle heading in degrees.

Value
0–359

Example:

0   = North
90  = East
180 = South
270 = West

Altitude

Height above sea level reported by the tracking device. Units: metres.


Ignition

Represents the interpreted ignition state.

{
    "ignition": {
        "status": "on"
    }
}

Possible values

Value
on
off

Oil

Fuel sensor value reported by the tracking device. Availability depends on installed hardware. May be null.


Voltage

Battery or external power voltage reported by the tracking device. Availability depends on the installed hardware. May be null.


Mileage

Vehicle odometer.

{
    "km": 2485047,
    "meters": 2485047000
}

Temperature

Temperature sensor reading reported by the tracking device. Availability depends on installed hardware. May be null.


Tracking Timestamps

Tracking timestamps represent different stages in the lifecycle of a telemetry record.

Field Description
gps Time reported by the GPS device
received Time the Real-time gateway received the telemetry
last_synced Time Fleet Management synchronized the database record

Note

All timestamps are returned using the Fleet Management server timezone.


Note

  • The Vehicle Location object uses the TLGPS response model.
  • Real-time data is preferred over synchronized database data whenever available.
  • Not all tracking devices support every telemetry field.
  • Optional fields may be null depending on the capabilities of the installed hardware.
  • Consumers should not assume every field is always available.

Vehicle History

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