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
- Access token
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