Augmenting Locations In Real-Time

ℹ️Covered in this guide
What is it all about?
Map-match a set of locations to obtain contextual data
Layers of information
Step-by-step guide to augment locations

What is it all about?

To get meaningful insights about mobility data, we are putting data into its particular spatial-temporal context. First, getting the precise map-based route of a raw trip sent to the platform; second, extracting all possible information layers for each segment of the trip route; and third, consolidating the results in a per-trip based, conforming the augmented trip. During data augmentation, more than 100 different information elements are added to each location and road segment of the trip.

Layers of information

The collected trip data is augmented, meaning each and every individual location during the trip is geo-data contextualized. Such information can be, but is not limited to:

  • Environment information (e.g., urban, motorway or rural area, street name, points of interest)
  • Road topology (e.g., speed limit, lane category, curvature, roundabout presence, road roughness)
  • Traffic information (e.g., traffic speed)
  • Traffic signals (e.g., presence of stop, yield or pedestrian crossing signs, animal crossing areas)
  • Driving warnings (e.g., Illegal U-turn, forbidden driving direction)
  • Weather conditions

Detailed list of properties

The location augmentation endpoints contain the following contextual information:

Property nameDescription
record_dateDatetime originally sent as datetime or recordDateUTCTimestamp. In the location’s timezone, if available.
id_from_inputUnique identifier originally sent as id or id_loc
distance_from_startDistance measured from start of the trip until the current location in km
distance_to_prev_matched_locationDistance to the previous matched location in km
distance_to_matched_locationDistance to the matched location in km
elapsed_time_from_startTime measured from start of the trip until the current location in seconds
link_idUnique identifier of the segment of the road to which the location belongs
route_link_seq_numberSequence number of the link in the route
latLatitude originally sent
lonLongitude originally sent
lat_matchedClosest latitude matching the road network
lon_matchedClosest longitude matching the road network
bearingbearing provided by the original input location
speed_from_inputSpeed provided as input to the contextualizer
is_illegal_turnIndicates an illegal turn on the link (warnings code 8)
is_illegal_uturnIndicates an illegal u-turn on the link (warnings code 6)
is_illegal_directionIndicates an illegal driving direction on the link (warnings code 3)
is_last_location_on_linkTrue, if the location is the last one in the corresponding link
is_intersectionIndicates an intersection at the location
distance_to_intersectionDistance to the intersection in m. null if there is no intersection present on the link.
speed_limitLegal speed limit at the location
speed_limit_trucksLegal speed limit applicable to trucks at the location
possible_speedRecommended speed limit at the location computed using slope and curvature on that location
possible_speed_with_slopeRecommended speed limit at the location computed using slope and curvature on that location (not capped to the legal speed limit)
possible_speed_with_curvatureRecommended speed limit at the location computed using curvature only on that location (not capped to the legal speed limit)
fcFunctional class, used to classify roads depending on the speed, importance and connectivity of the road. The higher the number, the smaller the road
urbanBoolean indicating if location belongs to urban area
is_urbanBoolean indicating if location belongs to urban area
countryISO code of the country
speed_categoryClassifies the general speed trend of a navigable link based on posted or legal speed.
route_typesRoute types per country
road_typeRoad type classification including Urban Area, Motorway, ExpressHighway, Inter, Highway, Unclassified
lane_categoryClassifies a navigable link based on the number of lanes in each travel direction
intersection_categoryIdentifies the type of intersection
low_mobility_categoryIndication if the navigable link is a Low Mobility link
is_roundaboutBoolean indicating if the location is inside a roundabout
controlled_accessBoolean indicating if the link has controlled access
limited_access_roadIdentifies roads that feel and function as a Controlled Access road
is_limited_access_roadIdentifies roads that feel and function as a Controlled Access road
travel_directionstring
rampIndicates if the navigable link represents a ramp
is_rampIndicates if the navigable link represents a ramp
overpass_underpassIndicates if the navigable link represents an overpass or underpass
dividerDescription of the divider on the road
divider_legalBoolean indicating if the divider is a legal or physical divider
is_divider_legalBoolean indicating if the divider is a legal or physical divider
center_divider_markerType of the divider marker in the center of the road
lane_widthThe width of the lane for the current location
min_link_idThe link id where the road segment started
curvatureRadius of curvature at the location. Value indicated is equal to (1 / radius) [10^-6 1/meter]
headingHeading at the location
bearingBearing provided in the input location
slopeVertical road direction RAW at location points along the link in the direction of driving
slope_percentVertical road direction at location points along the link in the direction of driving
radiusRadius of curvature at the location in meters
traffic_speed_from_ref_node_all_dayTraffic speed values in driving direction for all the day
traffic_speed_to_ref_node_all_dayTraffic speed values against driving direction for all the day
traffic_directionIndicator, which values belong to the current location
traffic_speedHistorical speed of the traffic flow at the location and time
traffic_speed_recordLive speed information of the traffic flow at the location and time
signsList of traffic signs associated with the location
has_stop_signTrue, if there is a stop sign at the link of the location
has_yield_signTrue, if there is a yield sign at the link of the location
has_pedestrian_crossing_signTrue, if there is a pedestrian crossing sign at the link of the location
has_no_overtaking_signTrue, if there is a no-overtaking sign at the link of the location
has_end_of_no_overtaking_signTrue, if there is a sign indicating the end of a no-overtaking area at the link of the location
has_traffic_signalTrue, if there is a traffic signal at the link of the location
is_tunnelBoolean indicating if the location belongs to a tunnel
is_bridgeBoolean indicating if the location belongs to a bridge
road_nameLiteral road name at the location
is_long_haulBoolean indicating if the location is a long haul
from_avg_roughness_categoryRoad roughness category of the link to which the location belongs to in the driving direction
from_avg_iriInternational roughness index of the link to which the location belongs to in the driving direction
from_available_roughness_typeRoad roughness type of the link to which the location belongs to in the driving direction
to_avg_roughness_categoryRoad roughness category of the link to which the location belongs to against the driving direction
to_available_roughness_typeRoad roughness type of the link to which the location belongs to against the driving direction
to_avg_iriInternational roughness index of the link to which the location belongs to against the driving direction
iriInternational roughness index of the link to which the location belongs to
has_ev_chargerBoolean indicating if there is a ev charger
cities_on_linkArray containing the ID or name of the city associated with the location
admin_places_countryCountry associated to the location
admin_places_districtDistrict associated to the location
admin_places_cityCity associated to the location
admin_places_postal_codePostal code associated to the location
admin_places_languageLanguage associated to the location
weather_sky_infoWeather condition description for the first location of every chunk (extracted from the weather information entry of the contextualizer result)
weather_visibilityVisibility weather condition for the first location of every chunk
weather_icon_nameIcon name for the weather condition for the first location of every chunk
weather_temperatureWeather temperature for the first location of every chunk
weather_humidityWeather humidity for the first location of every chunk
weather_wind_speedWeather wind speed for the first location of every chunk
weather_total_snowTotal snow accumulated for the first location of every chunk
poi_idsIdentifiers of the points of interest associated with the location
Example Response
{
    "distance_in_km": 0.052,
    "location_count": 10,
    "valid_location_count": 10,
    "start_timestamp": 1643269027004,
    "end_timestamp": 1643269036001,
    "duration_in_ms": 8997,
    "tunnel_segments": 0,
    "warnings": [],
    "weather": [
        {
            "sky_info": "Sunny",
            "visibility": "10000",
            "icon_name": "clear",
            "temperature": "-1",
            "humidity": "94",
            "wind_speed": "12",
            "total_snow": 0.0,
            "sunrise": "08:13 AM",
            "sunset": "05:22 PM",
            "wind_degree": 250,
            "wind_direction": "WSW",
            "pressure": 1030,
            "precipitation": 0.0,
            "cloud": 32,
            "feels_like_temperature": -4,
            "wind_chill_temperature": -4,
            "heat_index": -1,
            "dew_point": -2,
            "gust_speed": 21,
            "timestamp": 1643266800000
        }
    ],
    "link_info": [],
    "units": {
        "distance_from_start": "m",
        "distance_to_prev_matched_location": "m",
        "elapsed_time_from_start": "sec",
        "lat": "degree",
        "lon": "degree",
        "lat_matched": "degree",
        "lon_matched": "degree",
        "distance_to_matched_location": "m",
        "speed_from_input": "km/h",
        "distance_to_intersection": "m",
        "speed_limit": "km/h",
        "possible_speed": "km/h",
        "bearing": "degree",
        "curvature": "0.000001/m",
        "heading": "degree",
        "slope": "degree",
        "slope_percent": "percent",
        "radius": "m",
        "possible_speed_with_slope": "km/h",
        "possible_speed_with_curvature": "km/h",
        "traffic_speed": "km/h",
        "weather_visibility": "m",
        "weather_temperature": "C",
        "weather_humidity": "percent",
        "weather_wind_speed": "km/h",
        "weather_total_snow": "cm"
    },
    "traffic_signs": [],
    "pois": [
      {
        "category": "Nightlife",
        "poi_id": "1023842294",
        "cat_id": "5813",
        "national_importance": "N",
        "name": "Dolce Vita",
        "link_id": "54098887",
        "lat": 49.50396,
        "lon": 6.28009,
        "side": "R"
     },
     ...
    ],
    "locations": {
        "1": {
            "record_date": "2022-01-27T08:37:16.001000+01:00",
            "id_from_input": 1487,
            "distance_from_start": 52,
            "distance_to_prev_matched_location": 6,
            "distance_to_matched_location": 14.97,
            "elapsed_time_from_start": 8,
            "link_id": 54098887,
            "route_link_seq_num": 1,
            "lat": 49.5039383,
            "lon": 6.279823,
            "lat_matched": 49.50387,
            "lon_matched": 6.27994,
            "bearing": 42.0,
            "speed_from_input": null,
            "is_illegal_turn": false,
            "is_illegal_u_turn": false,
            "is_illegal_direction": false,
            "is_last_location_on_link": true,
            "is_intersection": false,
            "distance_to_intersection": 137,
            "speed_limit": 50,
            "speed_limit_trucks": null,
            "fc": 5,
            "urban": "Y",
            "is_urban": true,
            "country": "LUX",
            "speed_category": "31-50 kmh (21-30 mph)",
            "route_types": {
                "ANY": "none attached"
            },
            "road_type": "urban",
            "lane_category": "one lane",
            "intersection_category": "not applicable",
            "low_mobility_category": "unknown",
            "is_roundabout": false,
            "controlled_access": "N",
            "is_controlled_access": false,
            "limited_access_road": "N",
            "is_limited_access_road": false,
            "travel_direction": "F",
            "ramp": "N",
            "is_ramp": false,
            "overpass_underpass": null,
            "divider": "NO DIVIDER",
            "divider_legal": "N",
            "is_divider_legal": false,
            "center_divider_marker": null,
            "lane_width": null,
            "min_link_id": null,
            "curvature": null,
            "heading": null,
            "slope": 0.035,
            "radius": null,
            "traffic_speed_from_ref_node_all_day": "37,37,37,37,37,37,37,37,37,37,37,37,37,37,37,37,37,37,37,37,37,37,37,37,37,37,37,37,37,36,33,29,25,24,23,23,23,23,23,23,23,23,23,23,23,23,23,23,23,23,23,23,23,23,23,23,23,23,23,23,23,23,23,23,23,23,24,24,24,24,24,24,24,24,24,24,24,24,24,24,24,25,26,30,34,36,37,37,37,37,37,37,37,37,37,37",
            "traffic_speed_to_ref_node_all_day": null,
            "traffic_direction": "F",
            "traffic_speed": 33,
            "traffic_speed_record": null,
            "signs": null,
            "has_stop_sign": null,
            "has_yield_sign": null,
            "has_pedestrian_crossing_sign": null,
            "has_no_overtaking_sign": null,
            "has_traffic_signal": null,
            "has_end_of_no_overtaking_sign": null,
            "is_tunnel": false,
            "is_bridge": false,
            "road_name": "Avenue Dr Klein",
            "is_long_haul": false,
            "from_avg_roughness_category": null,
            "to_avg_roughness_category": null,
            "from_available_roughness_type": null,
            "to_available_roughness_type": null,
            "from_avg_iri": null,
            "to_avg_iri": null,
            "iri": null,
            "has_ev_charger": false,
            "cities_on_link": [
                "20199978",
                "Mondorf-les-Bains"
            ],
            "admin_places_country": "Luxembourg",
            "admin_places_district": "Remich",
            "admin_places_county": "Remich",
            "admin_places_city": "Mondorf-les-Bains",
            "admin_places_postal_code": "5630",
            "admin_places_language": "FRE",
            "weather_sky_info": "Sunny",
            "weather_visibility": "10000",
            "weather_icon_name": "clear",
            "weather_temperature": "-1",
            "weather_humidity": "94",
            "weather_wind_speed": "12",
            "weather_total_snow": 0.0,
            "poi_ids": [
                "1023842294",
                "1110245208",
                "1148610211",
                "50791374",
                "1192452895"
            ]
        },
        ...
    }
}

Augmenting Locations In Real-time API

Check our reference to see our endpoints: Location Augmentation.


Did this page help you?