API diagram

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.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(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  
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.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