/trips/
A trip is an ephemeral activity that in most cases entails movement of an asset to a different location. Therefore, trips have a beginning and an end in terms of time, and a set of coordinates that represent the movement of the asset.
Trips are composed using events, and location trackings coming from our devices. This information shows when the trip took place, and the geographic route it took.
Boundaries – START and STOP events
Trips are constrained by START and STOP events coming from our devices, which are used to determine the start and end boundaries of a trip.
Trip Classification
Trips are categorized into two different aspects.
Asset State
The state of the assets involved in a trip during its creation tells us if it is regular rider activity, or being used by fleet operators. This affects how metrics are calculated, or how routes are shown in the Fleet Management System.
Today, there are two states that can be assigned to a specific trip:
In Maintenance: If any of the assets involved in the trip –bicycle, tracker or lock– is in maintenance mode, the trip will be flagged as in maintenance.
In Service: In all other situations, a trip is considered normal activity by users.
Trip Type
Trips are also classified according to their intrinsic characteristics, such as duration, distance or start and end times. Trips can be:
Suspicious: If the system determines that the trip in question follows patterns considered harmful or outside of normal behaviour.
Regular: Trip behaviour is normal.
Trip Model
The trip model contains the following properties:
| Property | Description |
|---|---|
| uuid | Unique identifier of the trip. |
| type | Trip type. REGULAR or SUSPICIOUS. |
| asset_state | State of the asset during the trip. One of IN_MAINTENANCE, PRIVATEor IN_SERVICE. |
| serial_number | Device identifier. |
| created | Date of processing and creation of the trip. |
| bicycle | Link to the bicycle associated to the device at the time of the trip. |
| started | Point in time at which the trip started. Corresponds with the date of the device system status message containing the start event for the trip. |
| ended | Point in time at which the trip ended. Corresponds with the date of the device system status message containing the end event for the trip. |
| duration_sec | Duration of the trip in seconds. |
| distance_m | Distance covered by the asset during the trip. Calculated using the location messages ordered chronologically. |
| state_of_charge_start | Represents the state of charge of the battery at the beginning of the trip, expressed as a percentage. |
| state_of_charge_end | Represents the state of charge of the battery at the end of the trip, expressed as a percentage. |
| route | A collection of location coordinates representing the path that the asset took, formatted using GeoJSON. |
| is_valid | Whether the trip is considered to be valid or not. |
GET Fetch Trips
In this example, the first page of trips for the given bicycle is requested.
GET /trips/?page=1&bicycle=<bicycle_uuid>
Authorization: JWT <token>
Accept: application/json;version=1.0
The list of allowed parameters is as follows:
| Parameter | Description |
|---|---|
| page | Number of the page to fetch. |
| bicycle | A UUID referencing the bicycle the trips belong to. |
The response contains a list of trips:
[{
"uuid": "4fd39d9e-1f87-4fca-939d-9e1f87cfca88",
"created": "2017-03-27T08:37:14Z",
"start_date": "2017-03-27T08:36:24Z",
"end_date": "2017-03-27T08:37:54Z",
"route": {
"type": "LineString",
"coordinates": [
[13.402935028076172, 52.52756881713867],
[13.402868270874023, 52.5275993347168],
[13.40289306640625, 52.52756881713867],
[13.403008460998535, 52.527584075927734],
[13.40302562713623, 52.52763366699219]
]
},
"duration": "00:01:30",
"distance_m": 24,
"serial_number": "0201040003",
"asset_state": "in_service",
"type": null,
"is_valid": true
},]