Making dynamic context changes to road data

Edit online

You can use the IBM® IoT Connected Vehicle Insights Context Map service in the Route API to make dynamic context changes to road link data. Maps include road, or link, data that can have dynamic attributes, such as speed. You can use the REST API to create, update, and delete dynamic road attributes, and you can retrieve aggregated road attributes that include both static map data and dynamic context data.

Dynamic link data in the REST API

The following table shows the elements of dynamic link data that is supported in the Route REST API:

Type Category Create Update Delete Get Description
Dynamic Context Map for Link X (New) X (New) X (New) X (New) Dynamic data per map ID
Dynamic Context Map for Time-series - (Crawler only) - - X (New) The Weather Company traffic flow, The Weather Company weather
Static Dynamic Map Manager - - - X Attributes depend on map vendor and map tool

Dynamic link data in databus access

The following table shows the elements of dynamic link data that is supported in databus access by using get_link_information from the Vehicle Data Hub (VDH) to the Dynamic Map Manager (DMM):

Type Category Get Description
Dynamic Context Map for Link X Dynamic data per map ID
Dynamic Context Map for Time-series X (New) The Weather Company traffic flow, The Weather Company weather
Static DMM X Attributes depend on map vendor and map tool
Note: Databus access involves IBM IoT Connected Vehicle Insights internal communication. The Vehicle Data Hub uses databus to get link information from the Dynamic Map Manager after it gets map-matched longitude and latitude.

Access is supported by link-id as an aggregated way to include static attributes from map data, dynamic attributes, and dynamic context data such as traffic flow and weather.

Cache function is supported to reduce the number of access instances from DMM to HBase. High-volume access to HBase might cause a latency problem in DMM. Reducing the number of access instances from DMM to HBase can keep the HBase status working correctly. The following features help to reduce the number of access instances:

  • Maximum cache size management

  • Cache TTL (Time-To-Live) management

Dynamic link Create, Update, and Delete

The following diagram shows the Create Update, and Delete functions.

DynamicLinkCreateUpdateDelete

Dynamic link Get

The following diagram shows the Get function.

DynamicLinkGet

Configuring dynamic link context

The following table shows the parameters that are used to configure the dynamic link context feature:

Field Data type (unit) Default Description Customizable
Link.enabled true/false False Indicates whether cache link context is enabled Yes
Link.max_cache_number Number 100000 Max number of cache Yes
Link.ttl Number (milliseconds) 300000 TTL (5(minutes)*60(s)*1000(ms)) Yes
TrafficFlow__TWC.enabled true/false False Indicates whether The Weather Company cache traffic flow is enabled Yes
TrafficFlow__TWC.max_cache_number Number 1000000 Max number of cache Yes
TrafficFlow__TWC.ttl_observation_ratio Number (float) 1.1 Cache interval ratio of observed data compared with interval Yes
TrafficFlow__TWC.ttl_prediction_ratio Number (float) 0.1 Cache interval ratio of prediction data compared with interval Yes
TrafficFlow__TWC.max_steps Number 2 Max steps of latest historical traffic data Yes
TrafficFlow__TWC.target_measures String (comma-separated) flow_summary,flow_detail,prediction Target measures Yes
TrafficFlow__TWC.hbase_cache_blocks_enabled true/false True Indicates whether cache is enabled on HBase block cache No
HourlyWeather__TWC.enabled true/false False Indicates whether The Weather Company weather data is enabled Yes
HourlyWeather__TWC.max_cache_number Number 1000000 Max number of cache Yes
HourlyWeather__TWC.ttl_observation_ratio Number (float) 1.1 Cache interval ratio of observed data compared with interval Yes
HourlyWeather__TWC.ttl_prediction_ratio Number (float) 0.1 Cache interval ratio of prediction data compared with interval Yes
HourlyWeather__TWC.max_steps Number 2 Max steps of latest historical weather data Yes
HourlyWeather__TWC.target_measures String (comma-separated) icon_code, phrase,day_indicator,temperature,wind_speed,wind_direction,pressure,precip_1hr, snow_1hr, forecast Target measures Yes
HourlyWeather__TWC.hbase_cache_blocks_enabled true/false True If cache on HBase block cache No
RouteSearch.cache.enabled true/false True If cache on HBase block cache Yes

Enabling dynamic link context

DMM configuration

Enable Context Mapping access in the DMM Liberty node with support from the IBM IoT Connected Vehicle Insights operations team.

  1. Context map for time-series configuration The crawler for Weather Company Data traffic flow is unavailable by default. To set up access to traffic flow, you must work with the IBM IoT Connected Vehicle Insights operations team.

  2. Context map for link configuration Use the REST API to set up the Context Map for Link.

Configuring time-to-live (TTL) of cached dynamic data

Context map for time-series configuration

Prediction and forecast data is overwritten by observed data later. As a result, a much shorter TTL is set to predict data than the observed TTL.

  • Weather Company Data traffic flow

  • Default interval of crawling is 15 (minutes)

  • Observed data

    • TTL: 15 (minutes) * 1.1 = 16.5 (minutes)

    • Related parameter: TrafficFlow__TWC.ttl_observation_ratio in ctxmap.properties

  • Prediction data

    • TTL: 15 (minutes) * 0.1 = 1.5 (minutes)

    • Related parameter: TrafficFlow__TWC.ttl_prediction_ratio in ctxmap.properties

  • {{site.data.keyword.weather_company_short}} weather

    • Default interval of crawling is 60 (minutes)

    • Observed data

      TTL: 60 (minutes) * 1.1 = 66 (minutes)

      Related parameter: HourlyWeather__TWC.ttl_observation_ratio in ctxmap.properties

    • Forecast data

      TTL: 60 (minutes) * 0.1 = 6 (minutes)

      Related parameter: HourlyWeather__TWC.ttl_prediction_ratio in ctxmap.properties

Context map for link configuration**

  • If the Context Map for Link data is cached on DMM. The cache data might not reflect the actual data on the Context Map (HBase) when the data is updated. Therefore, if the update frequency is high and you need to query the updated data in your application, consider shortening the TTL.

  • TTL: 5 (minutes) in default

    • Related parameter: Link.ttl in ctxmap.properties

Configuring max steps

The crawled data's timestamp is rounded to fix a 1-hour interval, but for Weather Company Data weather crawler, the timestamp is rounded to fit a 15-minute interval. It is possible that crawled weather data might be missing, depending on the invocation timing of data crawler. The following parameters enable the latest crawled data to be queried in DMM:

  • HourlyWeather__TWC.max_steps in ctxmap.properties

  • TrafficFlow__TWC.max_steps in ctxmap.properties

As a result, DMM can get 14:00-15:00 data, for example, even if the 15:00-16:00 interval is not yet crawled, which is shown in the following image of the specification of Weather Company Data weather crawler:

CrawlerSpecAndSteps

Data format

For detailed REST API information, see Context Mapping REST API.

The following image shows the details of links.properties in the GET /mapservice/link response: QueryLinkDataFormat

The following example shows contextmap.link.attributes:

	"contextmap.link.attributes": [
	    {
	        "values": {
	            "value": "68400003417146_value_bbb"
	        },
	        "type": "bbb"
	    },
	    {
	        "values": {
	            "value": "68400003417146_value_aaa"
	        },
	        "type": "aaa"
	    },
	    {
	        "values": {
	            "value": "68400003417146_value_ccc"
	        },
	        "type": "ccc"
	    }
	],

The following example shows HourlyWeather__TWC in contextmap.timeseries.attributes:

    {
        "values": {
            "phrase": "Sunny",
            "snow_1hr": "0.0",
            "temperature": "25",
            "forecast": "true",
            "wind_direction": "236",
            "wind_speed": "10",
            "day_indicator": "D",
            "icon_code": "32",
            "pressure": "1013.35",
            "precip_1hr": "0.0"
        },
        "conditions": {
            "timestamp": "1588035600000"
        },
        "type": "HourlyWeather__TWC"
    },

The following example shows the use of flow_summary of TrafficFlow__TWC in contextmap.timeseries.attributes:

        {
            "values": {
                "measure": "flow_summary",
                "freeFlowSpeed": 94,
                "averageSpeed": 45,
                "currentSpeed": 101,
                "trafficStatus": 3
            },
            "conditions": {
                "direction": 2,
                "timestamp": 1588035600000
            },
            "type": "TrafficFlow__TWC"
        },

The following example shows the prediction of TrafficFlow__TWC in contextmap.timeseries.attributes:

        {
            "values": {
                "measure": "prediction",
                "freeFlowSpeed": 0,
                "averageSpeed": 0,
                "currentSpeed": 75,
                "trafficStatus": 0
            },
            "conditions": {
                "direction": 2,
                "timestamp": 1588035600000
            },
            "type": "TrafficFlow__TWC"
        },

The following example shows the flow_detail of TrafficFlow__TWC in contextmap.timeseries.attributes:

        {
            "values": {
                "measure": "flow_detail",
                "freeFlowSpeed": 94.95106,
                "averageSpeed": 45.06152,
                "currentSpeed": 101.38842
            },
            "conditions": {
                "start_distance": 0,
                "end_distance": 69.569,
                "direction": 2,
                "timestamp": 1588035600000
            },
            "type": "TrafficFlow__TWC"
        },