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
}
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 switchts
,te
: trip start, trip endss
,se
: stop start, stop end
examples:
ts=ignon;te=ignoff
will start and end a trip based on the ignition labelsts=in1on;ts=in2on;ts=panic;te=ignoff
will start a trip or a stopdd=trpswtch
end current trip and start new onets=ignon;te=idl;te=ignoff
will start a trip with ignition on, and end with idle or ignition off labelts=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
[
{
"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 keysFor 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
{
"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 useoffset
. Theoffset
pops the most recent X amount of segments from the results until you reach the total segments. The total is reached when you havecount
from the response +offset
from the param equaling thetotal
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
{
"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 |
Updated 7 months ago