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_countreflects 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
Search
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_numberbrandmodel
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
nulldepending 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
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.