Location data augmentation API

Last updated on October 14th, 2019 at 12:42 pm


This documentation is valid for release > release-23-08-19.3. See version property of response for verification.


  • URL


  • Method:



    {‘Content-Type’: “application/json”, ‘token’: “your_key”}

  • Data Params


    • 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


    • 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!


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


    • 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
    • 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”)


    • 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
      • skyInfo=[text]: Weather condition description
      • iconName=[text]: Icon name. Possible values are for example: scattered_tstorms_latea_few_showershailsprinkles_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
      • visibility=[number]: Visibility in km/h
      • gustSpeed=[number]: Gust speed in km/h
      • timestamp=[number]: Timestamp of this weather information

    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
      • illegalTurn=[boolean]: indicates an illegal turn on the link (warnings code 8)
      • illegalUTurn=[boolean]: indicates an illegal u-turn on the link (warnings code 6)
      • illegalDirection=[boolean]: indicates an illegal driving direction on the link (warnings code 3)
      • isIntersection=[boolean]: indicates an intersection at the location
      • distanceToIntersection=[boolean]: distance to the intersection in mnull if there is no intersection present on the link.
      • 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 AreaMotorwayExpressHighwayInterHighwayUnclassified
      • 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)
      • controlledAccess=[text]: Boolean indicating if the link has controlled access
      • limitedAccessRoad=[text]: Identifies roads that feel and function as a Controlled Access road
      • ramp=[text]: Indicates if the navigable link represents a ramp
      • divider=[text]: Description of the divider on the road
      • dividerLegal=[text]: Boolean indicating if the divider is a legal or physical divider
      • 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]
      • heading=[number]: Heading at the location in [10^-3 degree]
      • 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. FtrafficFromTtrafficTo
      • 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
        • lat=[number]: latitude of the sign
        • lon=[number]: longitude of the sign
        • 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
        • street=[text]: Literal road name at the location
  • 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, "skyInfo": "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, "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": "" } }, ... ] }