Submit trip data to the Motion-S API

Submit trip endpoint

This section covers the details to submit full-trip location data to the Motion-S platform through a REST API.

URL

https://api-prod.motion-s.com/platform/v1/trips

Authentication

• The authentication can be done using:
  • Access token
    • in the header as basic authentication header
    • in the query parameters using keyword access_token
  • API key
    • in the header using API key authorization
    • in the query parameters using keyword api_key

Request method

POST

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.

• Content type: application/json

Mandatory fields

NOTICE: Either device_id or organization_device_identifier need to be provided.

Key	Description	Data type	Unit/Format
device_id	A device identifier in our system or organization_device_identifier	string	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
metaDataMap	A map with additional data such as the IMEI of the device.	dict
organization_trip_identifier	The (id or uid) of the trip in your system.	string	NA
organization_device_identifier	A device identifier in your system. 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
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:

{
    "metaDataMap": {"somekey": "somevalue"},
    "device_id": 1,
    "organization_trip_identifier":"cd49e9b1-ee03-4425-aa53-8fcc56e6xyz",
    "locations":[
        {
          "id_loc": 1,
          "latitude":48.952283,
          "longitude":9.136845,
          "bearing":194.344284,
          "speed_kmh":8.8560,
          "date_time":1512454642000
        },
        {
          "id_loc": 2,
          "latitude":48.922283,
          "longitude":9.136845,
          "bearing":194.344284,
          "speed_kmh":9.8560,
          "date_time":1512454652000
        },
    ]
}

Then the request should have the following structure:

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

Response

Successful response

Code

200

Response details

Key	Description	Data type	Unit/Format
uid	The uid of the trip in our system	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

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

Error responses

NOTICE: If you submit the trip with the same trip_organization_identifier as the trip you submitted previously, we will return the trip you submitted previously and not continue to process the one you sent.

• Code: 401 The access token has expired
• Code: 403 Subscription is not active anymore
• Code: 424: There was an error while processing your trip
• Code: 422: Nonexisting entity error
• Code: 500 UNPROCESSABLE ENTRY