Segments (Trips)

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
}

Device	Mode	Start	End
Taurus	1	Trips 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
Syrus	0	When motion is detected and the distance traveled is more than `XXX` meters	Trip ends when there's no movement detected for more than `YYY` seconds
Syrus	1	Trips start when the ignition is ON, and movement is detected, and the distance traveled is more than `XXX` meters	Trip 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
Syrus	2	Trips start when the ignition ON is detected and the distance traveled is more than `XXX` meters	Trip 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"
}

Device	Method	Start	End
Applies to Syrus and non-Syrus devices	GPS	Trips start when the average speed is greater than 3mph	Trips 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"
}

Device	Method	Start	End
Applies to Syrus and non-Syrus devices	ignition	Trips start when the ignition ON is detected	Trips 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=...]]"
}

Device	Method	Start	End
Applies to Syrus and non-Syrus devices	labels	Trips start when the `ts` label occurs, or there's a stop and the `dd` label occurs	Trips 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:

Param	Type	Description
ids	Number	Trips of interest
from	String	Time from YYYY-MM-DD[Thh:mm:ss]
to	String	Time to YYYY-MM-DD[Thh:mm:ss]
duration	String	ISO_8601 Duration format (PnYnMnDTnHnMnS, PnW, PT) (ex: P1D = Past 1 Day)
vehicles	Number	Vehicles to get data from
fields	String	Which data fields do you want to include
contained	Boolean	Whether to return only fully contained trips within 'from' and 'to'
moving	Boolean	Set to true to view only trips that were moving
distance	String	unit to return distance values in (default: meters)
volume	String	unit to return volume values in (default: liters)
time	String	unit to return time values in (default: second)
speed	String	unit to return speed values in (default: distance_unit/time_unit)
export	String	format 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:

Param	Description
partition	How the segments are partitioned, for now only: `entity_hos` & `kamaleon` are supported
uuid	Unique identifier of the segment result
from	Time from YYYY-MM-DD[Thh:mm:ss]
to	Time to YYYY-MM-DD[Thh:mm:ss]
duration	ISO_8601 Duration format (PnYnMnDTnHnMnS, PnW, PT) (ex: P1D = Past 1 Day)
entities	Vehicle IDs to get data from
offset	Result 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

State	Status	Description
Working	Valid	Working less than the `max_work_hours`
Working	Invalid	Working more than the `max_work_hours`
At Rest	Unfinished	At rest less than the `max_work_hours` and the ignition is ON
At Rest		Ignition is OFF for more than the `min_rest_hours`