Skip to content
TLGPSDocumentation

Developer documentation

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

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.

Public documentation · authorized integration access required

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

Back to top