Sending Trip Data

️Covered in this guide

What is a trip?
Getting started
Compliancy of trip data for an endpoint
Examples

What is a trip?

Collecting driving data is the first step to entering the vehicle telematics world. Our platform is device-agnostic, meaning it supports several data collection sources, from dongles and black boxes to smartphone-based data. The only mandatory requirement is that the data collected must consist of a chain of locations containing:

  • ID (a consecutive integer)
  • Latitude and longitude
  • Speed
  • Bearing
  • Timestamp

Other data fields can be optionally used as location metadata for further analysis.

Getting started

To submit a trip to the platform, use Trip creation.

curl --request POST \
     --url https://api.motion-s.com/platform/v1/trips/ \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json'
[
  {
    "organization_trip_identifier": "test-lucie",
    "uid": "2c9b809177babaa60177c9194a5e006c",
    "organization_id": 1,
    "device_id": 1,
    "driver_id": 2,
    "vehicle_id": 1,
    "trip_timezone": "Europe/Brussels",
    "subscription_id": 1,
    "is_profiled": false,
    "created_at": "2021-02-22T10:36:53.602056",
    "is_faulty": false,
    "metadata": {
      "engine": "diesel",
      "roadtype": "highway"
    },
    "start_datetime": "2020-07-30T05:02:28.999000",
    "end_datetime": "2020-07-30T05:02:45.999000",
    "id": 2,
    "first_location": {
      "id_loc": 1,
      "latitude": 50.4844,
      "longitude": 3.95542,
      "created_at": "2021-02-22T10:36:54.184724",
      "date_time": "2020-07-30T03:02:28.999000+00:00"
    },
    "last_location": {
      "id_loc": 20,
      "latitude": 50.48457,
      "longitude": 3.95197,
      "created_at": "2021-02-22T10:36:54.184724",
      "date_time": "2020-07-30T03:02:45.999000+00:00"
    }
  }
]

Request payload

This section describes the expected request payload for this endpoint, including the mandatory and optional fields and then showing an example of it.

Compliancy of trip data for an endpoint

Mandatory fields

🚧

Please note:

Either device_id(Integer) or organization_device_identifier(String) need to be provided.

  • device_id: ID of the device you created in our system
  • organization_device_identifier: if provided instead of device_id, a device is created in our system and assigned to your organization default fleet. In the case a device with this organization_device_identifier already existed in our system we will use it.
KeyDescriptionData typeUnit/Format
device_idA device identifier in our system or organization_device_identifierintNA
locationsThe list of locations of the triplist

The list of locations must contain the following information:

KeyDescriptionData typeUnit/Format
id_locid or index of the location within the tripinteger>=0
latitudeLatitude of the locationdouble
longitudeLongitude of the locationdouble
bearingReported azimuthdoubledegrees
speed_kmhReported speeddoublekm/h
date_timeLocation record timestamp in EPOCHlongmilliseconds

Optional fields

KeyDescriptionData type
metadataA map with additional data such as a list of events computed on the edge or any other relavant trip-related information.dict
organization_trip_identifierThe (id or uid) of the trip in your system.string
organization_device_identifierA device identifier in your system (e.g., IMEI, MAC). Becomes mandatory field in the case the device_id is not provided. We create a device in our system and assign it to your organization's default fleet.string
organization_vehicle_identifierA vehicle identifier in your system. If provided, we would create a vehicle and assign it to your organization.string
driver_idid of the driver in our system.integer
vehicle_idA vehicle identifier in our system.integer
trip_timezoneTimezone where the trip was done.str

Example

Trip visualizationTrip visualization

Trip visualization

Considering the following raw_trip.json file:

{
   "metadata":{
      "somekey":"somevalue"
   },
   "device_id":1,
   "organization_trip_identifier":"cd49e9b1-ee03-4425-aa53-8fcc56e6xyz",
   "locations":[
      {
         "id_loc":1478,
         "latitude":49.5038847,
         "longitude":6.2793697,
         "bearing":145,
         "speed_kmh":24.44,
         "date_time":"2022-01-27T07:37:07.004Z"
      },
      {
         "id_loc":1479,
         "latitude":49.5038419,
         "longitude":6.27941,
         "bearing":147,
         "speed_kmh":20.77,
         "date_time":"2022-01-27T07:37:08.002Z"
      },
      {
         "id_loc":1480,
         "latitude":49.5038097,
         "longitude":6.279448,
         "bearing":143,
         "speed_kmh":17.13,
         "date_time":"2022-01-27T07:37:09.002Z"
      },
      {
         "id_loc":1481,
         "latitude":49.5037936,
         "longitude":6.2794897,
         "bearing":129,
         "speed_kmh":13.93,
         "date_time":"2022-01-27T07:37:10.002Z"
      },
      {
         "id_loc":1482,
         "latitude":49.5037775,
         "longitude":6.2795366,
         "bearing":114,
         "speed_kmh":12.88,
         "date_time":"2022-01-27T07:37:11.002Z"
      },
      {
         "id_loc":1483,
         "latitude":49.5037827,
         "longitude":6.2795863,
         "bearing":89,
         "speed_kmh":13.284000205993653,
         "date_time":"2022-01-27T07:37:12.002Z"
      },
      {
         "id_loc":1484,
         "latitude":49.5038097,
         "longitude":6.2796386,
         "bearing":61,
         "speed_kmh":15.98,
         "date_time":"2022-01-27T07:37:13.002Z"
      },
      {
         "id_loc":1485,
         "latitude":49.5038472,
         "longitude":6.2796936,
         "bearing":46,
         "speed_kmh":19.69,
         "date_time":"2022-01-27T07:37:14.002Z"
      },
      {
         "id_loc":1486,
         "latitude":49.5038955,
         "longitude":6.2797552,
         "bearing":42,
         "speed_kmh":23.22,
         "date_time":"2022-01-27T07:37:15.002Z"
      },
      {
         "id_loc":1487,
         "latitude":49.5039383,
         "longitude":6.279823,
         "bearing":42,
         "speed_kmh":26.17,
         "date_time":"2022-01-27T07:37:16.001Z"
      }
   ]
}

Then the request should have the following structure:

curl -d @raw_trip.json \
     -L -X POST 'https://api.motion-s.com/platform/v1/trips/?api_key=<API-Key>' \
     -H 'Content-Type: application/json'

Response

Response fields:

KeyDescriptionData typeUnit/Format
uidThe UID of the trip in our system, in API calls when asked for trip_id, the UID should be providedstring
organization_trip_identifierThe (ID or UID) of the trip in our system which would correspond to the organization_trip_identifier you provided when submitting the trip if you provided itstringNA
start_datetimeTrip start datetime in UTCstringdatetime UTC
end_datetimeTrip end datetime in UTCstringdatetime UTC
driver_idThe ID of the driver related to the trip if the driver_id was provided on submission of the trip.integerNA
device_idThe ID of the device related to the trip if device_id was provided on submission of the trip. In the case of organization_device_identifier provided, the ID of the newly created device will be returned.integerNA
vehicle_idThe ID of the vehicle related to the trip if the vehicle_id was provided on submission of the trip. In the case of organization_vehicle_identifier provided, the ID of the newly created vehicle will be returned.integerNA
first_locationFirst location of the tripdictlocation
last_locationLast location of the tripdictlocation

📘

Please note:

The returned UID is the most important field to retrieve further analytics. In API calls when asked for the trip_id, please insert the UID.

Example

  {
    "organization_trip_identifier": "test-trip",
    "uid": "2c9b809177babaa60177c9194a5e006c",
    "organization_id": 1,
    "device_id": 1,
    "trip_timezone": "Europe/Brussels",
    "created_at": "2021-02-22T10:36:53.602056",
    "start_datetime": "2020-07-30T05:02:28.999000",
    "end_datetime": "2020-07-30T05:02:45.999000",
    "id": 2,
    "first_location": {
      "id_loc": 1,
      "latitude": 50.4844,
      "longitude": 3.95542,
      "created_at": "2021-02-22T10:36:54.184724",
      "date_time": "2020-07-30T03:02:28.999000+00:00"
    },
    "last_location": {
      "id_loc": 20,
      "latitude": 50.48457,
      "longitude": 3.95197,
      "created_at": "2021-02-22T10:36:54.184724",
      "date_time": "2020-07-30T03:02:45.999000+00:00"
    }
  }




Did this page help you?