Location Data Augmentation API

Description

Data Augmentation

Basic GPS data is enriched with contextual data, such as road topology, road signs and POIs, weather and traffic conditions.

The API methods aim at giving developers the tool to easily integrate the telematics data, either generated by our SDK or by self-managed devices, into our profiling and analytics platforms. API access and the data processed is secured and privacy compliant, since the API is completely agnostic about user personal information.

Sign up at https://motion-s.com and use our easy-to-work and powerful API. Look at our monthly subscriptions for more options.

API documentation

This documentation is valid for release > release-01-04-19.1. See version property of response for verification.

  • URL

    URL

  • Method:

    POST

  • HEADERS

    HEADERS

  • Data Params

    Required:

    • locations=[array<json>] OR coordinates=[array<json>]: an array of coordinates of the trip with elements containing required properties:
      • lat=[number]: in decimal format
      • lon=[number]: in decimal format
      • recordDateUTCTimestamp=[number]: location record timestamp in EPOCH milliseconds OR datetime=[text]: date and time of the location sample in the following format "yyyy-MM-dd hh:mm:ss"
      • optionally:
      • id=[number]: id or index of the location within the trip to match back after processing

    Optional:

    • properties=[array<text>]: the names of the properties which are to be returned (see "Result Properties"), additionally weather
    • device=[text]: a device identifier (id or uid) in external system
    • foreignKey=[text]: the (id or uid) of the trip in external system
    • origin=[text]: format 'X+-X+' where you can use any string out of [a-z0-9] and minus sign (ASCII CODE 45) in the X part up to a total length of 200 characters. Eg 'vue-fleet-001'
  • Success Response:

    • Code: 200
      Content: { json }
  • Error Response:

    • Code: 401 UNAUTHORIZED
      Content: Denied access!

    OR

    • Code: 200
      Content: { "ERROR" : "..." }
  • Response Properties:

    Default:

    • status=[text]: Status result of the contextualizer success OR error
    • warnings=[array<json>]: Array containing list warnings encountered during trace matching, including Suspicious u-turn (2), Forbidden driving direction (3), Forbidden access (4), Leaving no-through-traffic zone (5), Illegal u-turn (6), Gate traversal (7), Illegal turn (8), Illegally traversed a road which is temporarily closed for construciton work (19)
    • version=[text]: Version of the contextualizer used for this trip

    Optional:

    • weather=[json]: (if selected in the "properties" array parameter) Weather condition at the time of the trip.
      • sunrise=[text]: Sunrise time
      • sunset=[text]: Sunset time
      • temperature=[number]: Temperature in Celsius
      • isDay=[boolean]: True, if the corresponding time is at daylight
      • conditionText=[text]: Weather condition description
      • iconName=[text]: Icon name. Possible values are for example: scattered_tstorms_late, a_few_showers, hail, sprinkles_late
      • windSpeed=[number]: Wind speed in km/h
      • windDegree=[number]: Wind direction in degrees
      • windDirection=[text]: Wind direction as 16 point compass, for example: "NSW"
      • pressure=[number]: Pressure in millibars
      • precipitation=[number]: Precipitation amount in millimeters
      • humidity=[number]: Humidity as percentage (%)
      • cloud=[number]: Cloud cover as percentage (%)
      • feelsLikeTemperature=[number]: Feels like temperature in Celcius
      • windChillTemperature=[number]: Windchill temperature in Celcius
      • heatIndex=[number]: Heat index in Celsius
      • dewPoint=[number]: Dew point in Celsius
      • chanceOfRain=[number]: Chance of rain as percentage (%)
      • chanceOfSnow=[number]: Chance of snow as percentage (%)
      • visibility=[number]: Visibility in km/h
      • gustSpeed=[number]: Gust speed in km/h
      • timestamp=[number]: Timestamp of this weather information
    • locationCount=[number]: Number of locations successfully contextualized
    • distanceInKm=[number]: Total distance of the Contextualized trip in km
    • results=[array<json>]: Array containing contextual information per location (properties see below "Result properties")

    Result properties:

    • the key names are possible entries for the input "properties" array parameter
      • linkId=[number]: Unique identifier of the segment of the road to which the location belongs

      • index=[number]: position of the location inside the location set sent to contextualizer

      • locId=[number]: unique identifier of the location in the trip

      • routeLinkSeqNum=[number]: Here.com sequence number of the link in the route

      • lat=[number]: latitude originally sent

      • lon=[number]: longitude originally sent

      • latMatched=[number]: closest latitude matching the road network

      • lonMatched=[number]: closest longitude matching the road network

      • distanceFromStartKm=[number]: distance measured from start of the trip until the current location in km

      • fc=[number]: Here.com functional class. Functional class 1 roads are roughly motorways, while functional class 5 roads are small roads that are used only to reach a destination.

      • clazz=[number]: Internal mapping to OpenStreetMap road class (clazz)

      • urban=[text]: Boolean indicating if location belongs to urban area

      • country=[text]: ISO code of the country

      • speedCategory=[text]: Classifies the general speed trend of a navigable link based on posted or legal speed. > 130 KPH / > 80 MPH (1), 101-130 KPH / 65-80 MPH (2), 91-100 KPH / 55-64 MPH (3), 71-90 KPH / 41-54 MPH (4), 51-70 KPH / 31-40 MPH (5), 31-50 KPH / 21-30 MPH (6), 11-30 KPH / 6-20 MPH (7), < 11 KPH / < 6 MPH (8)

      • routeTypesMask=[text]: Mapped to functional_class. The functional class is used to classify roads depending on the speed, importance and connectivity of the road. It is an xs:byte type with the following restrictions:

        1: allowing for high volume, maximum speed traffic movement
        2: allowing for high volume, high speed traffic movement
        3: providing a high volume of traffic movement
        4: providing for a high volume of traffic movement at moderate speeds between neighbourhoods
        5: roads whose volume and traffic movement are below the level of any functional class
        77: Roundabout
        
      • typeName=[text]: Road type classification including Urban Area, Motorway, ExpressHighway, Inter, Highway, Unclassified

      • laneCategory=[text]: Classifies a navigable link based on the number of lanes in each travel direction. (1) : ONE LANE, (2) : TWO OR THREE LANES, (3) : FOUR OR MORE LANES

      • intersectionCategory=[text]: Identifies the type of intersection. NOTAPPLICABLE (0), INTERNAL (1), MANOEUVRE (2), INDESCRIBABLE (3), ROUNDABOUT (4), UNDEFINED (5), SPECTRFIG (6) (A roundabout where the number of lanes changes)

      • lowMobility=[text]: Indication if the navigable link is a Low Mobility link. DRIVING CONDITION IS LOW MOBILITY (1), DRIVING CONDITION IS NOT LOW MOBILITY (2), DRIVING CONDITION IS NOT KNOWN (3)

      • isRoundabout=[text]: Boolean indicating if the location is inside a roundabout

      • minLinkId=[number]: The link id where the road segment started

      • speedLimit=[number]: legal speed limit at the location

      • possibleSpeed=[number]: recommended speed limit at the location computed using slope and curvature on that location

      • speedLimitTrucks=[json]: legal speed limit applicable to trucks at the location

        • speedLimit=[text]: the speed limit at the location in km/h
        • minWeight=[text]: Minimum weight of vehicle type in tons
        • vehicleTypes=[text]: Access Characteristics identify the vehicle types that are allowed on a link, allowed on a lane or to which a condition applies. 16 bit bitmask of affected vehicle types or functions. Sum of: Automobiles (1), buses (2), taxis (4), car pools (8), pedestrians (16), trucks (32), deliveries (64), emergency vehicles (128), through traffic (256), motorcycles (512) and road trains (1024).
        • minLength=[text]: Minimum length restriction of vehicle in meter. So if the vehicle lengths is over this length, the speed limit may apply.
        • carriesDangMaterial=[text]: Vehicle carries explosive or dangerous material.
        • trailer=[text]: Specifies if the speed limit applies to vehicles with trailers. NULL: This speed limit applies to all vehicles, with or without trailer(s), Y: This speed limit applies to all vehicles, with trailer(s), 1-x: This speed limit applies to all vehicles with this count of trailer(s)
      • curvature=[number]: radius of curvature at the location. Value indicated is equal to (1 / radius) [10^-6 1/meter]

      • slope=[number]: Vertical road direction RAW at location points along the link in the direction of driving

      • slopeDegree=[number]: Vertical road direction measured in [10^-3 degree] at location points along the link in the direction of driving

      • slopePercent=[number]: Vertical road direction measured in % at location points along the link in the direction of driving

      • radius=[number]: radius of curvature at the location in meters.

      • possibleSpeedWithSlope=[number]: recommended speed limit at the location computed using slope and curvature on that location (not capped to legal speed limit)

      • possibleSpeedWithCurvature=[number]: recommended speed limit at the location computed using curvature only on that location (not capped to legal speed limit)

      • trafficFrom=[text]: HERE.com traffic vector FROM the reference node

      • trafficTo=[text]: : HERE.com traffic vector TO the reference node

      • trafficDirection=[text]: Indicator, which values belong to the current location. F: trafficFrom, T: trafficTo

      • traficInKmh=[text]: Historical speed of the traffic flow at the location and time

      • isTunnel=[text]: Boolean indicating if the location belongs to a tunnel

      • isBridge=[text]: Boolean indicating if the location belongs to a bridge

      • roadName=[text]: Literal road name at the location

      • isLongHaul=[text]: Boolean indicating if the location is a long haul

      • iri=[number]: International roughness index of the link to which the location belongs to

      • signs=[array<json>]: Array containing the traffic signs associated to the location

        • conditionType=[text]: Type of the condition entity. One of VARIABLE SPEED SIGN, TRAFFIC SIGNAL, TRAFFIC SIGN, RAILWAY CROSSING, NO OVERTAKING, PROTECTED OVERTAKING, BLACKSPOT
        • trafficSignType=[text]: Identifies the type of warning sign.
        • trafficSignCategory=[text]: Identifies the main sign category to which the sign belongs. One of REGULATORY TRAFFIC SIGN CATEGORY (1), SAFETY INFORMATION TRAFFIC SIGN CATEGORY (2), WARNING TRAFFIC SIGN CATEGORY (3)
      • pois=[array<json>]: contains the details on Points of Interests associated to the location

        • name=[text]: Name of the Point of Interest
        • side=[text]: Side of the road of the Point of Interest in driving direction
        • lat=[text]: Latitude matching the Point of Interest without decimal point
        • lon=[text]: Longitude matching the Point of Interest without decimal point
        • category=[text]: What category the Point of Interest belongs to
      • capitalsOnLink=[array<text>] : Array containing the name of the capital city associated to the location if applicable

      • citiesOnLink=[array<number/text>]: Array containing the ID or name of the city associated to the location

      • federalStatesOnLink=[array<number>]: Array containing the ID of the region or federal state associated to the location

      • adminPlacesAll=[json]: Provides the IDs or names of the different administratives levels associated to the location

        • stateId=[number]: State
        • isoCountry=[text]: 3-digit ISO country code
        • country=[number/text]: Country
        • district=[number/text]: District
        • county=[number/text]: County
        • city=[number/text]: City
  • Sample Post Data:

{
  "device": "a53bceb868280de",
  "origin": "motion-s",
  "properties": [],
  "locations": [
    {
      "id_loc": 1,
      "latitude": 38.76929389,
      "longitude": -9.11084338,
      "recordDateUTCTimestamp": 1538419138000
    },
    {
      "id_loc": 2,
      "latitude": 38.7692965,
      "longitude": -9.11090907,
      "recordDateUTCTimestamp": 1538419139000
    },
    {
      "id_loc": 3,
      "latitude": 38.76931321,
      "longitude": -9.11104234,
      "recordDateUTCTimestamp": 1538419141000
    }
  ]
}
  • Sample Reponse Data:
{
  "status": "success",
  "version": "v1",
  "distanceInKm": 0.002,
  "locationCount": 3,
  "warnings": [],
  "weather": {
    "sunrise": "07:32 AM",
    "sunset": "07:20 PM",
    "temperature": 20.9,
    "isDay": false,
    "conditionText": "Clear",
    "iconName": "clear",
    "windSpeed": 13.2,
    "windDegree": 342,
    "windDirection": "NNW",
    "pressure": 1018,
    "precipitation": 0,
    "humidity": 52,
    "cloud": 0,
    "feelsLikeTemperature": 20.9,
    "windChillTemperature": 20.9,
    "heatIndex": 21.3,
    "dewPoint": 10.5,
    "chanceOfRain": "0",
    "chanceOfSnow": "0",
    "visibility": 10,
    "gustSpeed": 26.5,
    "timestamp": 1538419138000
  },
  "results": [
    {
      "index": 0,
      "distanceFromStartKm": 0,
      "linkId": 537286630,
      "routeLinkSeqNum": 0,
      "lat": 38.76929389,
      "lon": -9.11084338,
      "latMatched": 38.76926,
      "lonMatched": -9.1111,
      "locId": 1,
      "speedLimit": 0,
      "possibleSpeed": 0,
      "speedLimitTrucks": null,
      "fc": 5,
      "clazz": 41,
      "urban": "Y",
      "country": "PRT",
      "speedCategory": "6",
      "routeTypesMask": "0",
      "typeName": "Urban Area",
      "laneCategory": "1",
      "intersectionCategory": null,
      "lowMobility": "3",
      "isRoundabout": "N",
      "controlledAccess": "N",
      "limitedAccessRoad": "N",
      "ramp": "N",
      "overpassUnderpass": null,
      "divider": "NO DIVIDER",
      "dividerLegal": "N",
      "minLinkId": 0,
      "bearing": 0,
      "dist": 0,
      "curvature": null,
      "heading": null,
      "slope": null,
      "slopeDegree": null,
      "slopePercent": null,
      "radius": null,
      "possibleSpeedWithSlope": null,
      "possibleSpeedWithCurvature": null,
      "trafficFrom": null,
      "trafficTo": null,
      "trafficDirection": null,
      "traficInKmh": 0,
      "signs": [],
      "isTunnel": null,
      "isBridge": null,
      "roadName": null,
      "isLongHaul": null,
      "iri": 0,
      "tmc": {},
      "pois": [],
      "capitalsOnLink": "Lisbon",
      "federalStatesOnLink": 20319435,
      "citiesOnLink": "Lisbon",
      "adminPlacesAll": {
        "stateId": 20319435,
        "isoCountry": "PRT",
        "country": "Portugal",
        "district": null,
        "county": null,
        "city": "Lisboa",
        "street": null
      }
    },
    ...
  ]
}

Usage examples

POST /your URL path HTTP/1.1
Host: your Host
Content-Type: application/json
token: your Key
{
    "properties": ["adminPlacesAll", "speedLimit"],
    "coordinates":[
        {
             "id": 1,
             "lat": 49.624604281877,
             "lon": 6.1145851262855
        },
        {
            "id": 2,
            "lat": 49.6245810497238,
            "lon": 6.11460608746644
        },
        {
            "id": 3,
            "lat": 49.6245810497238,
            "lon": 6.11460608746644
        }
    ]
}
wget --quiet \
--method POST \
--header 'Content-Type: application/json' \
--header 'token: your Key' \
--body-data '{"properties": ["adminPlacesAll", "speedLimit"],"coordinates":[ { "id": 1, "lat": 49.624604281877, "lon": 6.1145851262855 },{ "id": 2, "lat": 49.6245810497238, "lon": 6.11460608746644 },{ "id": 3, "lat": 49.6245810497238, "lon": 6.11460608746644 }]}' \
--output-document \
- your Host + URL path
import http.client

conn = http.client.HTTPConnection("your Host")
payload = "{'properties': ['adminPlacesAll', 'speedLimit'],'coordinates':[{'id': 1,'lat': 49.624604281877,'lon': 6.1145851262855},{'id': 2,'lat': 49.6245810497238,'lon': 6.11460608746644},{'id': 3,'lat': 49.6245810497238,'lon': 6.11460608746644}]}"
headers = {'Content-Type': "application/json", 'token': "your Key"}

conn.request("POST", "/your URL path", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))