ℹ️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 name	Description
record_date	Datetime originally sent as datetime or recordDateUTCTimestamp. In the location’s timezone, if available.
id_from_input	Unique identifier originally sent as id or id_loc
distance_from_start	Distance measured from start of the trip until the current location in km
distance_to_prev_matched_location	Distance to the previous matched location in km
distance_to_matched_location	Distance to the matched location in km
elapsed_time_from_start	Time measured from start of the trip until the current location in seconds
link_id	Unique identifier of the segment of the road to which the location belongs
route_link_seq_number	Sequence number of the link in the route
lat	Latitude originally sent
lon	Longitude originally sent
lat_matched	Closest latitude matching the road network
lon_matched	Closest longitude matching the road network
bearing	bearing provided by the original input location
speed_from_input	Speed provided as input to the contextualizer
is_illegal_turn	Indicates an illegal turn on the link (warnings code 8)
is_illegal_uturn	Indicates an illegal u-turn on the link (warnings code 6)
is_illegal_direction	Indicates an illegal driving direction on the link (warnings code 3)
is_last_location_on_link	True, if the location is the last one in the corresponding link
is_intersection	Indicates an intersection at the location
distance_to_intersection	Distance to the intersection in `m`. `null` if there is no intersection present on the link.
speed_limit	Legal speed limit at the location
speed_limit_trucks	Legal speed limit applicable to trucks at the location
possible_speed	Recommended speed limit at the location computed using slope and curvature on that location
possible_speed_with_slope	Recommended speed limit at the location computed using slope and curvature on that location (not capped to the legal speed limit)
possible_speed_with_curvature	Recommended speed limit at the location computed using curvature only on that location (not capped to the legal speed limit)
fc	Functional class, used to classify roads depending on the speed, importance and connectivity of the road. The higher the number, the smaller the road
urban	Boolean indicating if location belongs to urban area
is_urban	Boolean indicating if location belongs to urban area
country	ISO code of the country
speed_category	Classifies the general speed trend of a navigable link based on posted or legal speed.
route_types	Route types per country
road_type	Road type classification including `Urban Area`, `Motorway`, `ExpressHighway`, `Inter`, `Highway`, `Unclassified`
lane_category	Classifies a navigable link based on the number of lanes in each travel direction
intersection_category	Identifies the type of intersection
low_mobility_category	Indication if the navigable link is a Low Mobility link
is_roundabout	Boolean indicating if the location is inside a roundabout
controlled_access	Boolean indicating if the link has controlled access
limited_access_road	Identifies roads that feel and function as a Controlled Access road
is_limited_access_road	Identifies roads that feel and function as a Controlled Access road
travel_direction	string
ramp	Indicates if the navigable link represents a ramp
is_ramp	Indicates if the navigable link represents a ramp
overpass_underpass	Indicates if the navigable link represents an overpass or underpass
divider	Description of the divider on the road
divider_legal	Boolean indicating if the divider is a legal or physical divider
is_divider_legal	Boolean indicating if the divider is a legal or physical divider
center_divider_marker	Type of the divider marker in the center of the road
lane_width	The width of the lane for the current location
min_link_id	The link id where the road segment started
curvature	Radius of curvature at the location. Value indicated is equal to `(1 / radius) [10^-6 1/meter]`
heading	Heading at the location
bearing	Bearing provided in the input location
slope	Vertical road direction RAW at location points along the link in the direction of driving
slope_percent	Vertical road direction at location points along the link in the direction of driving
radius	Radius of curvature at the location in meters
traffic_speed_from_ref_node_all_day	Traffic speed values in driving direction for all the day
traffic_speed_to_ref_node_all_day	Traffic speed values against driving direction for all the day
traffic_direction	Indicator, which values belong to the current location
traffic_speed	Historical speed of the traffic flow at the location and time
traffic_speed_record	Live speed information of the traffic flow at the location and time
signs	List of traffic signs associated with the location
has_stop_sign	True, if there is a stop sign at the link of the location
has_yield_sign	True, if there is a yield sign at the link of the location
has_pedestrian_crossing_sign	True, if there is a pedestrian crossing sign at the link of the location
has_no_overtaking_sign	True, if there is a no-overtaking sign at the link of the location
has_end_of_no_overtaking_sign	True, if there is a sign indicating the end of a no-overtaking area at the link of the location
has_traffic_signal	True, if there is a traffic signal at the link of the location
is_tunnel	Boolean indicating if the location belongs to a tunnel
is_bridge	Boolean indicating if the location belongs to a bridge
road_name	Literal road name at the location
is_long_haul	Boolean indicating if the location is a long haul
from_avg_roughness_category	Road roughness category of the link to which the location belongs to in the driving direction
from_avg_iri	International roughness index of the link to which the location belongs to in the driving direction
from_available_roughness_type	Road roughness type of the link to which the location belongs to in the driving direction
to_avg_roughness_category	Road roughness category of the link to which the location belongs to against the driving direction
to_available_roughness_type	Road roughness type of the link to which the location belongs to against the driving direction
to_avg_iri	International roughness index of the link to which the location belongs to against the driving direction
iri	International roughness index of the link to which the location belongs to
has_ev_charger	Boolean indicating if there is a ev charger
cities_on_link	Array containing the ID or name of the city associated with the location
admin_places_country	Country associated to the location
admin_places_district	District associated to the location
admin_places_city	City associated to the location
admin_places_postal_code	Postal code associated to the location
admin_places_language	Language associated to the location
weather_sky_info	Weather condition description for the first location of every chunk (extracted from the weather information entry of the contextualizer result)
weather_visibility	Visibility weather condition for the first location of every chunk
weather_icon_name	Icon name for the weather condition for the first location of every chunk
weather_temperature	Weather temperature for the first location of every chunk
weather_humidity	Weather humidity for the first location of every chunk
weather_wind_speed	Weather wind speed for the first location of every chunk
weather_total_snow	Total snow accumulated for the first location of every chunk
poi_ids	Identifiers 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.