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.

Key	Description	Data type	Unit/Format
device_id	A device identifier in our system or organization_device_identifier	int	NA
locations	The list of locations of the trip	list

The list of locations must contain the following information:

Key	Description	Data type	Unit/Format
id_loc	id or index of the location within the trip	integer	>=0
latitude	Latitude of the location	double
longitude	Longitude of the location	double
bearing	Reported azimuth	double	degrees
speed_kmh	Reported speed	double	km/h
date_time	Location record timestamp in EPOCH	long	milliseconds

Optional fields

Key	Description	Data type
metadata	A map with additional data such as a list of events computed on the edge or any other relavant trip-related information.	dict
organization_trip_identifier	The (id or uid) of the trip in your system.	string
organization_device_identifier	A 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_identifier	A vehicle identifier in your system. If provided, we would create a vehicle and assign it to your organization.	string
driver_id	id of the driver in our system.	integer
vehicle_id	A vehicle identifier in our system.	integer
trip_timezone	Timezone where the trip was done.	str

Example

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:

Key	Description	Data type	Unit/Format
uid	The UID of the trip in our system, in API calls when asked for trip_id, the UID should be provided	string
organization_trip_identifier	The (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 it	string	NA
start_datetime	Trip start datetime in UTC	string	datetime UTC
end_datetime	Trip end datetime in UTC	string	datetime UTC
driver_id	The ID of the driver related to the trip if the driver_id was provided on submission of the trip.	integer	NA
device_id	The 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.	integer	NA
vehicle_id	The 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.	integer	NA
first_location	First location of the trip	dict	location
last_location	Last location of the trip	dict	location

📘
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"
    }
  }

Sending Trip Data

What is a trip?

Getting started

Request payload

Compliancy of trip data for an endpoint

Mandatory fields

🚧
Please note:

Optional fields

Example

Response

📘
Please note:

Example

What is a trip?

Getting started

Request payload

Compliancy of trip data for an endpoint

Mandatory fields

🚧Please note:

Optional fields

Example

Response

📘Please note:

Example

🚧
Please note:

📘
Please note: