Follow

Json itineraries

1. About Json itineraries

This section explains how to work with itineraries using json file format.
First, one can send a json itinerary to the navigation, and then a json status of itinerary execution can be monitored in real time.
Itineraries are defined as a list of waypoints, each represented mainly with gps coordinates and optionally with the time window, which defines a desired visiting time.
There are the two SDK function AddItinerary and GetRouteStatus, through which the json structures can be exchanged with navigation engine.
Please note that the json file itineraries are only available with 3D versions of navigation.

2. Itinerary push format

The json specification of the supported structure is shown in the diagram bellow.
The fields denoted with * are mandatory.

 

The description of the json fields:

Field Type Default value Description
name string   name of the itinerary
description string   short description
version string   file format version, supported are: 2.1, 2.2
allowItineraryEdit bool true allows or disallows manual edit of itinerary once loaded into navigation
routeComputeType string: car|truck|taxi|emergency car defines the vehicle routing preference applied between waypoints
routeComputeMethod string: fastest|shortes|economical fastest defines the routing method preference applied between waypoints
avoidTollRoads bool false defines the routing attribute for toll roads
avoidSpecialArea bool false defines the routing attribute for special city zones
avoidMotorways bool false defines the routing attribute for motorways/highways
avoidUnpavedRoads bool false defines the routing attribute for unpaved roads
ignoreProhibited bool false defines the routing attribute for ignoring prohibited maneuvers
ignoreOneWays bool false defines the routing attribute for ignoring oneway driving rule
lat int 0 latitude position defined as WGS84 multiplied by 100,000
lon int 0 longitude position defined as WGS84 multiplied by 100,000
lonNavi int =lat navigable longitude position defined as WGS84 multiplied by 100,000
latNavi int =lon navigable latitude position defined as WGS84 multiplied by 100,000
hitRadius int 50 distance in meters from the waypoint considered as visiting criteria
type string: start|via|invisible|finish via the type of waypoint
waypointId int -1 user defined identification of the waypoint
startTime string   defines the starting time of a time window in the UTC format, example 2015-03-06T14:15:00Z
endTime string   defines the ending time of a time window in the UTC format, example 2015-03-06T14:30Z
stopDelay int 0 defines the service time in seconds expected to spent on the waypoint

 

Version history:

Version Release date Change log
2.2 21.8.2015 rename sdkId into waypointId
rename earliestPossibleStart into startTime
rename latestPossibleEnd into endTime
2.1 30.6.2015 1st official release
1.0 20.5.2015 beta release

 

Example of the itinerary with 3 waypoints:

{
"name":		"Itinerary-627",
"version":	"2.2",
"routeParts":
   [{
		"directives":
		{
			"routeComputeType":	"car",
			"routeComputeMethod":	"fastest",
			"avoidTollRoads":		true,
			"avoidSpecialArea":	false,
			"avoidMotorways":	false,
			"avoidFerries":	        	false,
			"avoidUnpavedRoads":	true,
			"ignoreProhibited":	false,
			"ignoreOneWays":		false
		},
		"waypointFrom":
		{
			"timeWindow":
			{
				"startTime": "2015-06-16T14:00:00Z",
				"endTime": "2015-06-16T14:30:30Z",
				"stopDelay": 120
			 },
			"lon":	        	1711001,
			"lat":	        	4814955,
			"type":	       	 "via",
			"waypointId":	1,
			"hitRadius":	100
		},
		"waypointTo":
		{
			"lon":	       	 1710758,
			"lat":	       	 4814795,
			"type":	       	 "via",
			"waypointId":	2,
			"hitRadius":	100
		}
   },{
		"directives":
		{
			"routeComputeType":	"car",
			"routeComputeMethod":	"shortest"
		},
		"waypointTo":
		{
			"timeWindow":
			{
				"startTime": "2015-06-16T15:00:00Z",
				"endTime": "2015-06-16T15:30:30Z",
			    "stopDelay": 120
			},
			"lon":	        	1710375,
			"lat":	        	4814391,
			"type":	        	"finish",
			"waypointId":	3,
			"hitRadius":	100
		}
	}]
}

 

3. Itinerary real time status format

The json specification of supported json fields is shown in the diagram bellow.
Some fields denoted by * can be omitted, which is in case the value is not valid. E.g. the field timeArrival when the waypoint is not yet visited.

 

The description of the json fields:

Field Type Default value Description
timeStamp string - the timestamp of the current status
numVisited int - number of waypoints already visited. The start waypoint is counted too.
numUnvisited int - number of waypoints not yet visited
numPredictedLateArrivals int - number of waypoints predicted to have late arrivals
numPredictedEarlyArrivals int - number of waypoints predicted to have early arrivals
timeRemaining int - time in seconds estimated to reach the finish
distanceRemaining int - distance in meters estimated to reach the finish
distancePassed int - distance in meters passed from start
lat int - latitude position defined as WGS84 multiplied by 100,000
lon int - longitude position defined as WGS84 multiplied by 100,000
lonNavi int - navigable longitude position defined as WGS84 multiplied by 100,000
latNavi int - navigable latitude position defined as WGS84 multiplied by 100,000
hitRadius int - distance in meters from the waypoint considered as visiting criteria
type string: start|via|invisible|finish - the type of waypoint
status string: visited|unvisited|none - the status of the waypoint
edited bool - indicates whether the waypoint was manually edited since itinerary loading into navigation
timeArrival string - defines the actual arrival time at the waypoint in the UTC format if already visited, example 2015-03-06T14:15:00Z
estimatedTimeArrival string - defines the estimated arrival time at the waypoint in the UTC format if not yet visited, example 2015-03-06T14:30Z
realtimeStatus:
timeRemaining
int - time in seconds estimated to reach the waypoint
realtimeStatus:
distanceRemaining
int - distance in meters estimated to reach the waypoint

 

Example of the itinerary status with 3 waypoints:

{
	"timeStamp": "2015-06-28T16:10:37Z",
	"numVisited": 1,
	"numUnvisited": 2,
	"numPredictedLateArrivals": 0,
	"numPredictedEarlyArrivals": 1,
	"timeRemaining": 1312,
	"distancePassed": 0,
	"distanceRemaining": 8610,
	"waypoints":
	[{
			"lon":	1711468,
			"lat":	4813110,
			"type":	"start",
			"waypointId":	1,
			"hitRadius":	200,
			"timeWindow":
			{
				"startTime":  "2015-06-28T16:00Z",
				"endTime":  "2015-06-28T16:30Z",
				"stopDelay":  180
			},
			"realtimeStatus":
			{
				"status":  "visited",
				"edited":  false
			}
	}, {
			"lon":  1713067,
			"lat":  4816062,
			"type":  "via",
			"waypointId":  2,
			"hitRadius":  200,
			"timeWindow":
			{
				"startTime":  "2015-06-28T16:15Z",
				"endTime":  "2015-06-28T16:30Z",
				"stopDelay":  180
			},
			"realtimeStatus":
			{
				"status":  "unvisited",
				"estimatedTimeArrival":	"2015-06-28T16:19:25Z",
				"timeRemaining":  528,
				"distanceRemaining":  5018,
				"edited":  false
			}
	}, {
			"lon":	1710000,
			"lat":	4814722,
			"type":	"finish",
			"waypointId":	3,
			"hitRadius":	200,
			"timeWindow":
			{
				"startTime":  "2015-06-28T17:00Z",
				"endTime":  "2015-06-28T17:30Z",
				"stopDelay":  180
			},
			"realtimeStatus":
			{
				"status":  "unvisited",
				"estimatedTimeArrival":  "2015-06-28T16:29:29Z",
				"timeRemaining":  1132,
				"distanceRemaining":  8610,
				"edited":  false
			}
		}]
}
Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments