Skip to main content

Get Vehicle Trip Status by Client

GET 
/vehicles/status/trip/by-client

Returns the latest location and current trip status data (if trip in progress) for each vehicle under a specific client or clients.

Following are two examples for using this request:

  1. Returns the location status data for all clients accessable to the user of the API: /api/v1/vehicles/status/trip/by-client/all
  2. Returns the location status data for the client id 555. If the user of the API is a client level user, the id will be ignored and only accessable data will be returned: /api/v1/vehicles/status/trip/by-client/555

Note: If it seems that you are receiving duplicate records it is because a vehicle may be fitted with multiple GPS device/tracking units. In order to only see the data of the primary device (recommended as backup devices often have less data available) you can add the ?unit_assigned_as=primary filtering parameter, for example:

/api/v1/vehicles/status/location/by-client/all?unit_assigned_as=primary

The request returns an array of objects having the following fields:

  • id (int): The vehicle's database id.
  • reg_no (string): Vehicle's registration number.
  • fleet_no (string|null): Vehicle's fleet number.
  • vehicle_make (string|null): Vehicle's make.
  • vehicle_model (string|null): Vehicle's model.
  • client_name (string): Client/customer name.
  • driver_name (string|null): Active or assigned Driver name.
  • vehicle_group_name (string|null): Vehicle's group name.
  • unit_assigned_as (string): Can be primary, backup_1, backup_2.
  • local_time (ISO 8601 date and time string|null): The local time of the GPS recording, local meaning the timezone where the GPS device finds itself in. It can be null if no GPS data has been captured by the device yet.
  • timezone (string): The configured/active timezone of the GPS device.
  • latitude (float): The decimal latitude in degrees.
  • longitude (float): The decimal longitude in degrees.
  • speed (int|float): The current GPS speed in km/h.
  • heading (int|float): The current GPS heading in degrees where 0 = North.
  • gps_fix (array of strings): Can be an empty array or have a combination of the following values: "fixed", "predicted", "diff_corrected", "last_known", "2d", "logged", "invalid_time", "on_no_fix", "sleep". In most cases the array will be empty or only contain "on_no_fix" if there is no GPS fix.
  • odometer (int): Odometer in meters. This is currently only availble if the GPS device is configured to supply the odometer, returns 0 if no odometer is available.
  • address (int|null): Current address of the vehicle if available.
  • hours_behind (float): Can be used to determine how long ago the device transmitted a GPS location, the device's timezone is taken into account.
  • comms_status_code (string): Current communication status. Can be "online", "inactive", "offline", "never".
  • day_trip_no (int): The trip number of the day if a trip is active.
  • active_trip (Object|null): The active trip data object if a trip is active, null if no trip is active.

The active_trip object contains the following fields and sub-fields:

  • avg_speed (float): The average speed of the active trip in km/h.

  • max_speed (float|int): The maximum speed in km/h reached during the active trip.

  • started_at (ISO 8601 date and time string|null): The local time when the GPS trip started.

  • distance_km (float): The distance travelled in the active trip.

  • start_address (string|null): The starting address of the active trip.

  • durations (Object): The various durations in "HH:MM:SS" recorded during the active trip.

Request​

Responses​

OK