Route API

Overview

Use the Route API to get information about a route of a moving object between two or more waypoints. The route can contain several different directions of a trip that is represented by geographic elements of the map, which is exploitable for intelligent route planning. When you configure IBM IoT Connected Vehicle Insights to get data from external context origins, including traffic and other systems, the Route API can consider such dynamic context information for a route calculation and an arrival time estimation. Then, the API returns this context information with the route.

The Route API has two modes for routing, Search and Predict. In the Search mode, the Route API calculates the best route by optimizing the direction by considering the static and dynamic information. In the Predict mode, the Route API calculates the routes by using the prediction method, for example, based on the behavior analysis of a moving object or a driver.

Capability and Specification

The Route API provides the following capabilities.

• Calculate a best route between two or more waypoints.

  • Shortest time or shortest distance

  • Considering a traffic flow

• Predict a route between two or more waypoints.

  • Prediction based on trajectory histories of a moving object or a driver

• Estimate a travel time and distance.

• Retrieve the information of affected contexts.

Route Request

The input of the Route API is comprised in the RouteRequest.

When search is specified for the route_mode, the route is calculated in the Search mode. When predict is specified for the route_mode, the route is calculated in the Prediction mode. The default route mode is the Search mode.

Route Response

The output of the Route API is comprised in the RouteResponse.

Route API Elements

The following table shows the elements that form the route.

Requesting Route Search

1. Multiple Waypoints. In the Search mode, the Route API calculates the best Path between the Waypoints in the given order. The raw coordinate of the Waypoint can be specified as either of the following values:

   • Longitude and Latitude

   • POI ID The Longitude and Latitude value is used as the raw coordinate of the Waypoint. When the POI ID is specified for the key poi_id in the props attribute of the Waypoint and true is specified for the key get_poi in the props attribute of RouteRequest, the Route API retrieves the POI information from the Context Map. In this case, the raw coordinate of the Waypoint is replaced with the coordinate of the POI. If the navigation_point is defined in the POI, the coordinate of the navigation point is used instead of the coordinate of the POI. The Route API does map matching with the raw coordinate to determine the point on the road link. The Path between the origin and destination point is calculated based on the map matched point on the road link.

2. Route calculation. The Route API supports two kinds of search mode. When time is specified for the key search_mode in the props attribute of RouteRequest, the route search is executed in the Shortest Time mode. The default search mode is Shortest Time. When distance is specified for the key search_mode in the props attribute of RouteRequest, the route search is executed in the Shortest Distance mode. When the search mode is Shortest Time, the route is calculated so that the travel time between the Waypoints is shortest. When the search mode is Shortest Distance, the route is calculated so that the distance along the roads between the Waypoints is shortest. The travel time is calculated based on the speed-related attribute of road link or the context information that is retrieved dynamically from the external context origins.

Requesting Route Prediction

1. Multiple Waypoints. In the Prediction mode, the Route API calculates the predicted Path between the Waypoints in the given order. If no predicted Path is found, no Path information is returned. The raw coordinate of the Waypoint can be specified as either of the following values.

   • Longitude and Latitude

   • POI ID The POI information can be retrieved from the Context Map in the same way as the Search mode. No map matching is executed in the Prediction mode. The raw coordinate is passed to the prediction method.

2. Route prediction method. The following prediction method can be specified for the key prediction_method in the props attribute of RouteRequest.

   • Driver Behavior Trajectory History Patterns. The default prediction method is pattern. When the prediction method uses the Driver Behavior component, the REST API of the Driver Behavior component needs to be available. The prediction that uses the Driver Behavior component is based on the behavior of a moving object or a driver, mo_id and/or driver_id, specify the ID in the RouteRequest.

3. Predicted Route information. The extra information from the prediction method is stored in the props attribute of Path.

External Context Information

Use the external context information to evaluate how long it takes to pass through the roads. To use the context information for the Route API, the context information needs to be stored, and ready for use in the Context Map. For context information, refer to the documentation for the Context Mapping REST API.

If necessary, specify the context origin as the value for the key context_origins in the props attribute of RouteRequest. The context origin is the context type and source that is connected by "__", for example, <Context Type>__<Context Source>. The possible context type and source depend on the configuration of the Context Map.

If true is specified for the key consider_contexts in the props attribute of RouteRequest, the Route API uses the context information while calculating the route in the Shortest Time in the Search mode.

If true is specified for the key get_contexts in the props attribute of RouteRequest, the Route API returns the list of affected *Contexts that are stored in the Route.

Travel Time Estimation

The travel time of the Path is stored for the key travel_time in the props attribute of Path. The travel distance of the Path is stored for the key travel_distance in the props attribute of Path. If the context information is available and true is specified for get_contexts or consider_contexts, the travel time is calculated by using the latest affected context information. Otherwise, the travel time is calculated based on the speed-related attribute of road link.

Routing Options

The following options can be specified in the props attribute of RouteRequest.

API Specification

For information about the Context Mapping REST API and other REST APIs, see REST APIs for application development

API Example

• The example of RouteRequest

{
	"route_mode": "search",
	"points": [{
		"longitude": -118.24327978549462,
		"latitude": 34.05421078278744
	},
	{
		"longitude": -118.24343013111499,
		"latitude": 34.05401329542899
	}],
	"props": {
		"get_linkshape": "true"
	}
}

• The example of RouteResponse

{
	"mo_id": null,
	"driver_id": null,
	"trip_id": null,
	"routes": [{
		"trips": [{
			"origin_point": {
				"longitude": -118.24327978549462,
				"latitude": 34.05421078278744,
				"altitude": -1000,
				"heading": -1000,
				"props": {
					"distance": "9.978745251158877",
					"map_id": "1",
					"link_id": "68400002925057"
				}
			},
			"destination_point": {
				"longitude": -118.24345030320616,
				"latitude": 34.05402620729102,
				"altitude": -1000,
				"heading": -1000,
				"props": {
					"distance": "35.805545068305015",
					"map_id": "1",
					"link_id": "68400002925057"
				}
			},
			"paths": [{
				"map_id": 1,
				"links": [{
					"link_id": "68400002925057",
					"from_point": null,
					"to_point": null,
					"shape": [{
						"lon": -118.24327978549462,
						"lat": 34.05421078278744
					},
					{
						"lon": -118.24345030320616,
						"lat": 34.05402620729102
					}],
					"props": null
				}],
				"props": {
					"travel_distance": "25.82679981714614",
					"travel_time": "1.9370099862859602"
				}
			}],
			"props": null
		}],
		"contexts": null,
		"props": null
	}],
	"props": null
}