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://<customer-name>.motion-s.com/data_collection/trips

Method

POST

Authentication

  • The authentication can be:
    • by white-listed IP;
    • by http basic authentication header.

Request

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

Mandatory fields

Key Description Data type Unit/Format
startTimestamp Trip start timestamp in EPOCH long milliseconds
endTimestamp Trip end timestamp in EPOCH long milliseconds
device A device identifier (id or uid) string NA
customerTripId The (id or uid) of the trip in your system string NA
origin The fleet name as agreed with motion-s string <customer-name>-<fleet-name>-<fleet-number>
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 long  
latitude Latitude of the location double  
longitude Longitude of the location double  
bearing Reported azimuth double degrees
speedKmh Reported speed double km/h
recordDateUTCTimestamp Location record timestamp in EPOCH long milliseconds

Optional fields

Key Description
metaDataMap A map with additional data such as the IMEI of the device.
finalizedSession A flag indicating whether the system should wait for more locations to this trip before processing

Example

Considering the following raw_trip.json file:

{
    "metaDataMap": {"somekey": "somevalue"},
    "startTimestamp": 1512454642000,
    "endTimestamp": 1512554642000,
    "device": "18bb9f27-54b7-4c1a-95e1-6c538e753xxx",
    "customerTripId":"cd49e9b1-ee03-4425-aa53-8fcc56e6xyz",
    "origin": "customerA-fleetB-1",
    "locations":[
        {
          "id_loc": 1,
          "latitude":48.952283,
          "longitude":9.136845,
          "bearing":194.344284,
          "speedKmh":8.8560,
          "recordDateUTCTimestamp":1512454642000
        },
        {
          "id_loc": 2,
          "latitude":48.922283,
          "longitude":9.136845,
          "bearing":194.344284,
          "speedKmh":9.8560,
          "recordDateUTCTimestamp":1512454652000
        },
    ]
}

Then the request should have the following structure:

curl -d @raw_trip.json \
     -H "Content-Type: application/json" \
     -H "Authorization: Basic token" \
     -X POST https://<customer-name>.motion-s.com/data_collection/trips

Response

Successful response

Code

200

Response details
Key Description Data type Unit/Format
id The id of the trip in our system string  
dateCreatedTimestamp Creation timestamp in EPOCH long milliseconds
startTimestamp Trip start timestamp in EPOCH long milliseconds
endTimestamp Trip end timestamp in EPOCH long milliseconds
customerTripId The id of the trip in your system string  
origin The fleet name as agreed with motion-s string <customer-name>-<fleet-name>-<fleet-number>
consumed true if this trip has been processed by our system boolean  
device A map with information about the device used for data collection map  
metaDataMap The requested metaDataMap map  

The device map contains the following fields:

Key Description Data type
id The id of the device in our system string
dateCreated Creation date in our system string
detailsRequested Always true for api-generated devices string
foreignKey The id of the device in your system string
imei The imei (if provided) string
lastUpdated The timestamp of the last change to this device string
managedUrl The URL for details (if provided) string
metaData Arbitrary metadata (if provided) string
model The model of the device (if provided) string
name The name of the device (if provided) string
origin The fleet name as agreed with motion-s string
Example
{
  "id": "297ea89e602b58fe01602b5dbb740004",
  "dateCreatedTimestamp": 1512556051318,
  "metaData": "{'somekey':'somevalue'}",
  "startTimestamp": 1512454642000,
  "endTimestamp": 1512554642000,
  "device": {
      "id": "297ea89e602b58fe01602b59d5090000",
      "dateCreated": "2017-12-06T10:23:15Z",
      "detailsRequested": true,
      "foreignKey": "18bb9f27-54b7-4c1a-95e1-6c538e753xxx",
      "imei": "990000862471854",
      "lastUpdated": "2017-12-06T10:23:15Z",
      "managedUrl": null,
      "metaData": null,
      "model": null,
      "name": null,
      "origin": "customerA-fleetB-1"
  },
  "customerTripId": "cd49e9b1-ee03-4425-aa53-8fcc56e6xyz",
  "origin": "customerA-fleetB-1",
  "consumed": false
}

Error responses

  • Code: 401 UNAUTHORIZED
  • Code 409: This chunk has already been persisted
  • Code 406: The session id is invalid or incomplete
  • Code 422: The session id has already been persisted
  • Code: 500 UNPROCESSABLE ENTRY