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://<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