REST API / V1
Vehicles
REST API V1 resources, authentication and bounded reads.
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.