Segments (Trips)

Segments and Trips API

Segments help us get summarized data about a collection of events over a span of time grouped in a convenient and natural way, each segment can be thought of a partition of data in a timeline.

One of the way Pegasus summarizes data is using trips, trips are segments of data that have start and end times based on conditions such as time, ignition, distance, etc. Trip data includes totals, max, and averages of information captured during that particular time range, for example the total distance driven, max speed, etc. An entity can have at most 1 trip definition.

Another way Pegasus can group data is using segments, segments are yet another way to use conditions based on the status of the ignition or input to start and end segments, unlike trips you can define multiple definitions of segments to partition the data.

Overview

Segments are defined from the /remote/segment_setup API

POST /api/vehicle/:vid/remote/segment_setup

{
    "segment_type": "trips|hos",
    ...
}

Trips Configure

Via device (tracker)

Trips are calculated by the device and messages are sent in a separate streams to the gps events.
The tracker method is only supported for Syrus and Taurus devices

Tracker method requires mode, partition, and distance

mode can be:

  • 0: use the motion sensor
  • 1: ignition and motion
  • 2: ignition only

partition: how long (seconds) the mode condition must be met before finishing a trip, default is 210 seconds.
distance: how far of a distance (meters) to consider before starting a trip, default is 50 meters.

POST /api/vehicle/:vid/remote/segment_setup

{
    "segment_type": "trips",
    "method": "tracker",
    "mode": 0|1|2,
    "partition": 0-9999,
    "distance": 1-999
}
DeviceModeStartEnd
Taurus1Trips start when motion is detected by the phone's movement sensor and there's a distance traveled of more than 50 meters.Trips end when there's no motion detected and the phone is in the same location for more than 4.5 minutes or manually when the user clicks Stop trip on the app
Syrus0When motion is detected and the distance traveled is more than XXX metersTrip ends when there's no movement detected for more than YYY seconds
Syrus1Trips start when the ignition is ON, and movement is detected, and the distance traveled is more than XXX metersTrip ends when the ignition is OFF and no movement is detected for more than YYY seconds or if the ignition remains ON and the vehicle does not detect movement for more than YYY seconds
Syrus2Trips start when the ignition ON is detected and the distance traveled is more than XXX metersTrip ends when the ignition OFF is detected for more than YYY seconds

Via GPS coordinates

Applies to Syrus and non-Syrus devices.

Internal logic used by Pegasus based on gps to establish whether the vehicle is moving or stopped.

POST /api/vehicles/:vid/remote/segment_setup

{
  "segment_type": "trips",
  "method": "gps"
}
DeviceMethodStartEnd
Applies to Syrus and non-Syrus devicesGPSTrips start when the average speed is greater than 3mphTrips end when the average speed is less than 3mph for more than 4 minutes

For more information on the logic used checkout the following forum.


Via ignition

Trips are started and ended based on the ignition state.
Falls back to GPS if the ignition state is not available.

POST /api/vehicles/:vid/remote/segment_setup

{
  "segment_type": "trips",
  "method": "ignition"
}
DeviceMethodStartEnd
Applies to Syrus and non-Syrus devicesignitionTrips start when the ignition ON is detectedTrips end when an ignition OFF is detected

Via labels

Trips are started and ended based specified labels,
requires labels in the configuration payload
the format is composed of switches, switch=label, you can combine as many of these as you want with ;

allowed switches

  • dd: default switch
  • ts,te: trip start, trip end
  • ss,se: stop start, stop end

examples:

  • ts=ignon;te=ignoff will start and end a trip based on the ignition labels
  • ts=in1on;ts=in2on;ts=panic;te=ignoff will start a trip or a stop
  • dd=trpswtch end current trip and start new one
  • ts=ignon;te=idl;te=ignoff will start a trip with ignition on, and end with idle or ignition off label
  • ts=ignon;dd=in1on will start a trip with ignition on and switch with in1on label

if you do not provide a dd switch, you need to make sure that the start and end conditions are met.
i.e ts|ss require a te|se

POST /api/vehicles/:vid/remote/segment_setup

{
  "segment_type": "trips",
  "method": "labels",
  "labels": "switch1=label1[;switch2=label2[;switch3=...]]"
}
DeviceMethodStartEnd
Applies to Syrus and non-Syrus deviceslabelsTrips start when the ts label occurs, or there's a stop and the dd label occursTrips end when the te label occurs, or there's a trip and the dd label occurs, or the device is coming from a trip and the ss label occurs

Segments Configure

Hours of Service

Hours of Service segments are special segments that are built from a boolean signal that the vehicle reports.
The segments use the signal as a condition to start a segment of type working or resting.

POST /api/vehicles/:vid/remote/segment_setup

{
  "segment_type": "hos",
  "signal": "moving",
  "max_work_hours": 12,
  "min_rest_hours": 6
}

signal can refer to any boolean value on the event,
i.e io_inX io_outX io_ign io_pwr moving etc...
moving uses the movement sensor when supported, if not supported it falls back to ignition and gps speed.

If the signal is moving for example, once movement is detected it will transition into a working segment.
The working segment will continue until the vehicle comes to a stop and the moving signal transitions to false at which point it will switch into a resting segment.

View Segment/Trips Configuration

In order to get the configuration of the trip and segments configured you can use the device package from the device API.

To access this data you can use the vehicles API
https://dev2.pegasusgateway.com/api/vehicles/545?select=device:segments trip_setup

GET /api/vehicles/:vid?select=device:segments trip_setup

{
    "device": {
        "trip_setup": {
            "state": null,
            "_epoch": 1638362977.465545,
            "method": "ignition"
        },
        "segments": {
            "setup": {
                "hos": {
                    "max_work_hours": 12,
                    "signal": "moving",
                    "min_rest_hours": 6
                }
            },
            "_epoch": 1638366757.218667,
            "entries": {
                "hos": {
                    "entity_id": 545,
                    "end_event": null,
                    "start_time": 1635539826.0,
                    "min_rest_hours": 6,
                    "max_work_hours": 12,
                    "state": "resting",
                    "end_time": null,
                    "device": 351580051400972,
                    "start_event": {
                        "lon": -90.55147,
                        "mph": 14,
                        "label": "trckpnt",
                        "count_dev_idle": 1739.0,
                        "lat": 14.52436,
                        "moving": false,
                        "count_dev_dist": 27765.77685635594,
                        "event_time__epoch": 1635539826.0,
                        "valid_gps": true,
                        "io_ign": true,
                        "count_dev_ign": 6301.0
                    }
                }
            }
        },
        "imei": 351580051400972
    },
    "id": 545
}

or you can also use the devices API
https://dev2.pegasusgateway.com/api/devices/351580051400972?select=segments,trip_setup

GET /api/devices/:imei?select=segments,trip_setup

{
    "trip_setup": {
        "state": null,
        "_epoch": 1638362977.465545,
        "method": "ignition"
    },
    "segments": {
        "setup": {
            "hos": {
                "max_work_hours": 12,
                "signal": "moving",
                "min_rest_hours": 6
            }
        },
        "_epoch": 1638366757.218667,
        "entries": {
            "hos": {
                "entity_id": 545,
                "end_event": null,
                "start_time": 1635539826.0,
                "min_rest_hours": 6,
                "max_work_hours": 12,
                "state": "resting",
                "end_time": null,
                "device": 351580051400972,
                "start_event": {
                    "lon": -90.55147,
                    "mph": 14,
                    "label": "trckpnt",
                    "count_dev_idle": 1739.0,
                    "lat": 14.52436,
                    "moving": false,
                    "count_dev_dist": 27765.77685635594,
                    "event_time__epoch": 1635539826.0,
                    "valid_gps": true,
                    "io_ign": true,
                    "count_dev_ign": 6301.0
                }
            }
        }
    },
    "imei": 351580051400972
}

You can also get the data from live websockets via the device package.

Browse segments

Trips

These are the currently supported query params to get trips data:

ParamTypeDescription
idsNumberTrips of interest
fromStringTime from YYYY-MM-DD[Thh:mm:ss]
toStringTime to YYYY-MM-DD[Thh:mm:ss]
durationStringISO_8601 Duration format (PnYnMnDTnHnMnS, PnW, PT) (ex: P1D = Past 1 Day)
vehiclesNumberVehicles to get data from
fieldsStringWhich data fields do you want to include
containedBooleanWhether to return only fully contained trips within 'from' and 'to'
movingBooleanSet to true to view only trips that were moving
distanceStringunit to return distance values in (default: meters)
volumeStringunit to return volume values in (default: liters)
timeStringunit to return time values in (default: second)
speedStringunit to return speed values in (default: distance_unit/time_unit)
exportStringformat to export the trips data (csv or tsv)

🚧

Combining parameters

All requested conditions defined by the parameters are logically ANDed, so invalid conditions will return no trips (eg: requesting ids=12 and vehicles=34 but trip with id=12 belongs to vehicle with id=56).

Request the trips for a vehicle

https://api.pegasusgateway.com/trips?vehicles=45&from=2021-12-25T10:05:00&to=2021-12-25T11:00:00&fields=distance,mean_speed,duration,moving,start_time&distance=km&time=minute&speed=kph

[
    {
        "distance": 13.405,
        "mean_speed": 43.28,
        "start_time": "2015-12-25 10:04:05",
        "moving": true,
        "duration": 18.58
    },
    {
        "distance": 0,
        "mean_speed": 0,
        "start_time": "2015-12-25 10:22:40",
        "moving": false,
        "duration": 5.87
    },
    {
        "distance": 25.33,
        "mean_speed": 36.49,
        "start_time": "2015-12-25 10:28:32",
        "moving": true,
        "duration": 41.65
    }
]

👍

Fields Description

You can view a description of the trips fields here /trips/keys

Note that you can also use data to retrieve only certain results from the trips keys

For example only retrieve units and type from the trips keys:

https://api.pegasusgateway.com/trips/keys?data=units,type

The available options for the data parameter are:

  • all (default)
  • none
  • type
  • short_desc
  • long_desc
  • units

When data=none then no data for the fields is requested and only an array of available fields names is returned.

View the distance, duration, ignition time, idle time, and the average speed per trip

https://api.pegasusgateway.com/trips?from=2016-10-17&to=2016-10-18&vehicles=598,599&fields=distance,duration,ignition,idle,mean_speed

{
  "mean_speed": 13.17,
  "duration": 3483,
  "idle": 0,
  "distance": 45876,
  "ignition": 3483
}

When getting trips, if the fields parameter is undefined, then all available trips' fields data will be returned by default.

HoS

To browse HoS segments you can use the segments API

GET /api/segments?partition=<partition>&entities=<vid>&from=<date>&to=<date>

These are the currently supported query params to get segments data:

ParamDescription
partitionHow the segments are partitioned, for now only: entity_hos & kamaleon are supported
uuidUnique identifier of the segment result
fromTime from YYYY-MM-DD[Thh:mm:ss]
toTime to YYYY-MM-DD[Thh:mm:ss]
durationISO_8601 Duration format (PnYnMnDTnHnMnS, PnW, PT) (ex: P1D = Past 1 Day)
entitiesVehicle IDs to get data from
offsetResult offset to view next segments

📘

Segments Pagination

Note that the response of the segments API is paginated and returns the first 100 results.
The way to navigate the rest of the segments requested when there's more than 100 results is to use offset. The offset pops the most recent X amount of segments from the results until you reach the total segments. The total is reached when you have count from the response + offset from the param equaling the total from the response.

In other words if the total is 147 segments, the normal API response would return the first 100:

  "count": 100,
   ...
  "total": 147,
  "data": []

To get the next 47 you can pop the first 100 using the offset=100

  "count": 47,
   ...
  "total": 147,
  "data": []

🚧

Units in Segments API

Note that the units responded in the Segments API are the default ones reported by the API.

Distance = meters
Time = seconds
Volume = liters
Speed = km/h

https://dev2.pegasusgateway.com/api/segments?partition=entity_hos&entities=563&from=2021-11-07&to=2021-11-12

{
  "count": 48,
  "query": {
    "identifiers": [
      "552"
    ],
    "from": "2022-01-03T00:00:00+00:00",
    "partition": "entity_hos",
    "ids": null,
    "to": "2022-02-03T20:33:56.741155+00:00",
    "identifier": null,
    "data": null
  },
  "total": 48,
  "data": [
    {
      "uuid": "bf5d1c56-72fd-4240-b6c8-00ec994d40e7",
      "start_time": "2022-02-03T03:08:10+00:00",
      "partition": "entity_hos",
      "end_time": "2022-02-03T15:12:04+00:00",
      "identifier": "552",
      "data": {
        "entity_id": 552,
        "end_event": {
          "ecu_idle_fuel": null,
          "count_dev_idle": 653710.1472518444,
          "ecu_distance": null,
          "lon": -90.53777,
          "mph": 5,
          "label": "trckpnt",
          "ecu_hours": null,
          "event_time__epoch": 1643901124.0,
          "moving": true,
          "count_dev_dist": 3020803.8211676353,
          "lat": 14.58804,
          "valid_gps": true,
          "ecu_total_fuel": null,
          "ecu_hours_idle": null,
          "io_ign": true,
          "count_dev_ign": 1345984.1307969093
        },
        "start_time": 1643857690.0,
        "min_rest_hours": 6,
        "max_work_hours": 12,
        "state": "resting",
        "end_time": 1643901124.0,
        "device": 351580050576509,
        "start_event": {
          "ecu_idle_fuel": null,
          "count_dev_idle": 652998.1472518444,
          "ecu_distance": null,
          "lon": -90.53788,
          "mph": 0,
          "label": "trckpnt",
          "ecu_hours": null,
          "event_time__epoch": 1643857690.0,
          "moving": false,
          "count_dev_dist": 3020803.8211676353,
          "lat": 14.58761,
          "valid_gps": true,
          "ecu_total_fuel": null,
          "ecu_hours_idle": null,
          "io_ign": false,
          "count_dev_ign": 1345268.1307969093
        }
      }
    },
    ...

Hours of Service States

For the sake of Hours of Service the following states are derived from segments

StateStatusDescription
WorkingValidWorking less than the max_work_hours
WorkingInvalidWorking more than the max_work_hours
At RestUnfinishedAt rest less than the max_work_hours and the ignition is ON
At RestIgnition is OFF for more than the min_rest_hours