This section covers the details to send trip data to the data augmentation process.

Augment trip data endpoint

URL

https://<customer-name>.motion-s.com/data_augmentation/trips

Method

POST

Authentication

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

Request

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

Mandatory fields

Key Description Data type Unit/Format
origin The fleet name as agreed with motion-s string <fleet-name>-<fleet-number>
locations A list of coordinates of the trip. list NA

The locations list must contain the following information:

Key Description Data type Unit/Format
id id or index of the location within the trip to match back after processing long NA
latitude Latitude of the location double Decimal
longitude Longitude of the location double Decimal
recordDateUTCTimestamp location record timestamp in seconds long seconds
bearing Reported azimuth, measured in degrees.    
speedKmh Reported vehicle speed, measured in km/h.    

Optional fields

Key Description Data type Unit/Format
properties A selection of the names of the properties which are to be returned List of strings NA
device A device identifier (id or uid) in external system string NA
foreignKey The (id or uid) of the trip in external system string NA

If no properties list is provided, all available properties will be returned.

Example

Considering the following body.json:

{
   "origin": "testing-example",
   "properties":[
      "adminPlacesAll",
      "speedLimit"
   ],
   "locations":[
     {
        "id":0,
        "latitude":49.54784,
        "longitude":6.36105,
        "bearing":36.54818,
        "speedKmh":1.21685,
        "recordDateUTCTimestamp":1571128562000
     },
     {
        "id":1,
        "latitude":49.54782,
        "longitude":6.36107,
        "bearing":127.3642,
        "speedKmh":2.27809,
        "recordDateUTCTimestamp":1571128563000
     }
   ]
}

Then, the call to the data augmentation endpoint would be:

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

Response

Error response

Code

| Http Status Code | Possible causes | | ———|———-| | 400 Bad Request | Multiple possible reasons such as empty location list, bad JSON syntax, or missing mandatory properties in the POST body. | | 401 Unauthorized | Missing or invalid authorization. | | 413 Request Entity Too Large | Exceeded the maximum number of allowed locations. | | 422 Unprocessible Entity | Not enough valid locations for the map-matching service. | | 424 Failed Dependency | Errors in the communication with the Here.com servers. | | 500 Internal Server Error | Multiple possible reasons. |

Error response details

| Key | Description | Data type | Unit/Format | | ———|———-|———-|———- | | timestamp | Timestamp of the error | long | milliseconds | | status | Http Status Code | integer | NA | | error | Http Status Code description | string | NA | | message | Error message | string | NA | | path | Server path of the requested ressource | string | NA |

Successful response

Code

200

Response details
Key Description Data type Unit/Format
status Response state, usually “success” string NA
version Version of the contextualizer used for this trip string NA
warnings Warnings encountered during trace matching, f.e. “Suspicious u-turn”, “Forbidden driving direction”, and a list of ignored location entries List NA
locationCount Number of locations successfully contextualized integer NA
distanceInKm Total distance of the contextualized trip in km decimal km
weather Weather information for the trip json NA
pois Points of interest in the trip area list NA
results Contextual information per location list NA

The default results properties contain the following contextual information:

Property name Description    
index position of the location inside the location set sent to contextualizer    
distanceFromStartKm distance measured from start of the trip until the current location in km decimal kilometer
elapsedTimeFromStartSec time measured from start of the trip until the current location in seconds integer second
linkId Unique identifier of the segment of the road to which the location belongs long NA
routeLinkSeqNum Here.com sequence number of the link in the route integer NA
lat latitude originally sent decimal decimal degree
lon longitude originally sent decimal decimal degree
latMatched closest latitude matching the road network decimal decimal degree
lonMatched closest longitude matching the road network decimal decimal degree
locId unique identifier of the location in the trip integer NA
illegalTurn indicates an illegal turn on the link (warnings code 8) boolean NA
illegalUTurn indicates an illegal u-turn on the link (warnings code 6) boolean NA
illegalDirection indicates an illegal driving direction on the link (warnings code 3) boolean NA
isIntersection indicates an intersection at the location boolean NA
distanceToIntersection distance to the intersection in m. null if there is no intersection present on the link. integer meter
speedLimit legal speed limit at the location integer km/h
possibleSpeed recommended speed limit at the location computed using slope and curvature on that location integer km/h
speedLimitTrucks legal speed limit applicable to trucks at the location json NA
fc Here.com functional class, used to classify roads depending on the speed, importance and connectivity of the road.    
The higher the number, the smaller the road integer NA  
clazz Internal mapping to OpenStreetMap road class (clazz)    
urban Boolean indicating if location belongs to urban area    
country ISO code of the country    
speedCategory Classifies the general speed trend of a navigable link based on posted or legal speed.    
routeTypesMask Mapped to functional class fc string NA
typeName Road type classification including Urban Area, Motorway, ExpressHighway, Inter, Highway, Unclassified string NA
laneCategory Classifies a navigable link based on the number of lanes in each travel direction string NA
intersectionCategory Identifies the type of intersection string NA
lowMobility Indication if the navigable link is a Low Mobility link string NA
isRoundabout Boolean indicating if the location is inside a roundabout string NA
controlledAccess Boolean indicating if the link has controlled access string NA
limitedAccessRoad Identifies roads that feel and function as a Controlled Access road string NA
ramp Indicates if the navigable link represents a ramp string NA
overpassUnderpass Indicates if the navigable link represents an overpass or underpass string NA
divider Description of the divider on the road string NA
dividerLegal Boolean indicating if the divider is a legal or physical divider string NA
minLinkId The link id where the road segment started long NA
curvature radius of curvature at the location. Value indicated is equal to (1 / radius) [10^-6 1/meter] integer NA
heading Heading at the location decimal [10^-3 degree]
slope Vertical road direction RAW at location points along the link in the direction of driving decimal [10^-3 degree]
slopeDegree Vertical road direction at location points along the link in the direction of driving decimal [10^-3 degree]
slopePercent Vertical road direction at location points along the link in the direction of driving integer percent
radius radius of curvature at the location in meters decimal NA
possibleSpeedWithSlope recommended speed limit at the location computed using slope and curvature on that location (not capped to legal speed limit) integer NA
possibleSpeedWithCurvature recommended speed limit at the location computed using curvature only on that location (not capped to legal speed limit) integer NA
trafficFrom HERE.com traffic vector FROM the reference node string NA
trafficTo HERE.com traffic vector TO the reference node string NA
trafficDirection Indicator, which values belong to the current location string NA
traficInKmh Historical speed of the traffic flow at the location and time integer NA
signs List of traffic signs associated to the location list NA
isTunnel Boolean indicating if the location belongs to a tunnel string NA
isBridge Boolean indicating if the location belongs to a bridge string NA
roadName Literal road name at the location string NA
isLongHaul Boolean indicating if the location is a long haul string NA
iri International roughness index of the link to which the location belongs to integer NA
pois Contains the details on Points of Interests associated to the location (incl. EV chargers) list NA
capitalsOnLink List of the capital city or capital cities associated to the location if applicable list NA
federalStatesOnLink Array containing the ID of the region or federal state associated to the location list NA
citiesOnLink Array containing the ID or name of the city associated to the location list NA
adminPlacesAll Provides the IDs or names of the different administratives levels associated to the location json NA
Example
{
    "status": "success",
    "version": "release-06-12-19.1",
    "distanceInKm": 5.37,
    "locationCount": 159,
    "warnings": [
        {
            "text": "Ignored 4 locations with too big distances from input.",
            "ignoredIds": [
                163,
                167,
                199,
                200
            ]
        }
    ],
    "weather": {
        "sunrise": "04:15 AM",
        "sunset": "08:09 PM",
        "temperature": 24,
        "skyInfo": "Partly cloudy",
        "iconName": "partly_cloudy",
        "windSpeed": 10,
        "windDegree": 357,
        "windDirection": "N",
        "pressure": 1019,
        "precipitation": 0.0,
        "humidity": 55,
        "cloud": 13,
        "feelsLikeTemperature": 26,
        "windChillTemperature": 24,
        "heatIndex": 26,
        "dewPoint": 15,
        "visibility": 10,
        "gustSpeed": 11,
        "timestamp": 1562246032000
    },
    "pois": [
        {
            "POI_ID": "2_AUT_49994",
            "CAT_ID": "5540",
            "NAME": "ABB Schnelllader Panzerhalle",
            "LINK_ID": "55898097",
            "SIDE": "L",
            "lat": 47.8064,
            "lon": 13.01024,
            "CATEGORY": "Petrol/Gasoline Station",
            "data": {
                "open24Hours": true,
                "privateAccess": false,
                "connectorTypes": [
                    {
                        "typeValue": "IEC 62196-2 type 2 (Mennekes)",
                        "numberOfConnectors": 1,
                        "chargeMode": "3",
                        "chargeCapacity": "380-480VAC, 3-phase at max. 63 A",
                        "fixedCable": false,
                        "customerConnectorName": "AC EV connector (Mennekes - type 2)"
                    },
                    {
                        "typeValue": "IEC 62196-2 type 2 combo (Mennekes)",
                        "numberOfConnectors": 1,
                        "chargeMode": "4",
                        "chargeCapacity": "500VDC, at max. 100 A",
                        "fixedCable": true,
                        "customerConnectorName": "AC/DC combo (Mennekes - type 2)"
                    },
                    {
                        "typeValue": "JEVS G 105 (CHAdeMO)",
                        "numberOfConnectors": 1,
                        "chargeCapacity": "500VDC, at max. 100 A",
                        "fixedCable": false,
                        "customerConnectorName": "DC TEPCO connector"
                    }
                ],
                "percentFromRefnode": "70",
                "paymentMethod": {
                    "other": "TRUE"
                }
            }
        }
    ],
   "results": [ ..., {
     "index": 50,
     "distanceFromStartKm": 1.98,
     "linkId": 726161491,
     "routeLinkSeqNum": 53,
     "lat": 47.801,
     "lon": 13.042,
     "latMatched": 47.80104,
     "lonMatched": 13.04194,
     "locId": 58,
     "speedLimit": 30,
     "possibleSpeed": 30,
     "speedLimitTrucks": null,
     "fc": 3,
     "clazz": 15,
     "urban": "Y",
     "country": "AUT",
     "speedCategory": "7",
     "routeTypesMask": "0",
     "typeName": "Urban",
     "laneCategory": "1",
     "intersectionCategory": "0",
     "lowMobility": "3",
     "isRoundabout": "N",
     "controlledAccess": "N",
     "limitedAccessRoad": "N",
     "ramp": "N",
     "overpassUnderpass": null,
     "divider": "NO DIVIDER",
     "dividerLegal": "N",
     "minLinkId": 0,
     "bearing": 0.0,
     "dist": 0,
     "curvature": null,
     "heading": null,
     "slope": -0.076,
     "slopeDegree": null,
     "slopePercent": null,
     "radius": null,
     "possibleSpeedWithSlope": null,
     "possibleSpeedWithCurvature": null,
     "trafficFrom": "1096402,1248202,1164902,346802,1499802,945002,496902",
     "trafficTo": "994102,1107502,587402,259402,1341602,1106702,1107502",
     "trafficDirection": "F",
     "traficInKmh": 35,
     "signs": [],
     "isTunnel": "N",
     "isBridge": "N",
     "roadName": "Franz-Josef-Kai",
     "isLongHaul": "Y",
     "iri": 2.6,
     "tmc": {},
     "pois": [
        {
            "POI_ID": "2_AUT_11187",
            "CAT_ID": "5540",
            "NATIONAL_IMPORTANCE": null,
            "NAME": "electrodrive Salzburg",
            "CHAIN_ID": null,
            "LINK_ID": "726161491",
            "SIDE": "L",
            "lat": 47.80107,
            "lon": 13.04169,
            "CATEGORY": "Petrol/Gasoline Station",
            "data": {
                "open24Hours": false,
                "privateAccess": true,
                "connectorTypes": [
                    {
                        "typeValue": "Domestic plug/socket type F (CEE 7/4 (Schuko))",
                        "powerFeedType": null,
                        "numberOfConnectors": 2,
                        "chargeMode": "1",
                        "chargeCapacity": "200-240VAC, 1-phase at max. 16 A",
                        "fixedCable": false,
                        "customerChargeLevel": "1",
                        "maxPowerLevel": "3.68",
                        "customerConnectorName": "country specific domestic plug/socket",
                        "chargerManufacturer": null
                    }
                ],
                "gasoline": null,
                "diesel": null,
                "percentFromRefnode": "40",
                "hydrogen": null,
                "E85": null,
                "CNG": null,
                "LPG": null,
                "E10": null,
                "bioDiesel": null
            }
        }
     ],
     "capitalsOnLink": [],
     "federalStatesOnLink": [
        20134400
     ],
     "citiesOnLink": [
       "Salzburg"
     ],
     "adminPlacesAll": {
        "stateId": 20134400,
        "isoCountry": "AUT",
        "country": "Österreich",
        "district": "Salzburg",
        "county": "Salzburg",
        "city": "Salzburg",
        "street": "Franz-Josef-Kai"
     }
  },
  ...
  ]
}

Error response

Code
Http Status Code Possible causes
400 Bad Request Multiple possible reasons: empty location list, bad json syntax, missing mandatory properties in the post body, etc.
401 Unauthorized Missing or invalid authorization.
413 Request Entity Too Large Maximum location count allowed exceeded.
422 Unprocessible Entity Not enough valid locations for a route match available.
 500 Internal Server Error Multiple possible reasons: No configuration file available, errors in the communication with the Here.com servers.
Error response details
Key Description Data type Unit/Format
timestamp Timestamp of the error long milliseconds
status Http Status Code integer NA
error Http Status Code description string NA
message Error message string NA
path Server path of the requested ressource string NA