These 3 sections explain the details of each part of the GetNavigationRouteAG response, in more depth than can be covered in the API specification.

GetNavigationRouteAG Response Details

1. RoutePoints Details

RoutePoints is a list of compressed coordinates for drawing the route on a map or navigation screen. The number of points is given by TotalPoint. Indices in the related FeatureLists or CommandLists objects refer to this list of points – take note that the index is zero-based.

The Points are listed in a compressed format to reduce the size of the response. All coordinates are multiplied by 100 000 and truncated to an integer (this is approximately 10 cm accuracy). The starting longitude and latitude is given, followed by the difference (or delta) from the previous coordinate, repeated to the end of the list.

Conversion example:

2822974, -2574422, 5, -82, -237, -18, -20, -1, 12, -150, 23, 2, 15, 1, 235, 17, 142, 8, 43, 4, 45, 3, -14, 150, -32, -2, -23, -2, -189, -12, -5, 82

2. FeatureLists Details

While RoutePoints shows every twist and turn on a route (and there can be many on a single street segment), FeatureLists works at the level higher – for each different street segment. It is a comma-separated list containing the street ID, the starting index (refer to RoutePoints) and the travel time for that street segment. The total number of features (street segments) is given by TotalFeature. Format: ID1,Index1,TravelTime1,TrafficCategory1, ID2,Index2,TravelTime2,TrafficCategory2, … where:

• ID – the unique AfriGIS FeatureID, mostly commonly AG_STR_ID.
• Index – the index position of this feature’s starting coordinate, in the list of RoutePoints.
• TravelTime – the time (in minutes) to traverse the entire feature.

Example:

164885,0,0.220341,undefined, 164469,1,0.477737,3_congested, 164651,3,0.432173,undefined, 164496,4,0.078686,1_freeflowing, 164496,6,0.507153,1_freeflowing, 164496,9,0.0551543,1_freeflowing, 164883,10,0.432293,undefined, 164882,11,0.0724996,1_freeflowing, 164882,12,0.255014,1_freeflowing, 164885,13,0.387007,undefined

3. CommandLists Details

Not every street segment requires an audible or visual navigation command (for example, to continue straight.) The CommandLists object lists all the voice (audible) or visual navigation commands to present to a user while he is navigating. Most commands have an index (referring to the RoutePoints list) where the command should be presented, and voice commands also include the name and length of the street segment.

There are three types of navigation commands:

• Voice Commands – indicates what voice command to play at this location, as well as the street name and the length of the street segment.
• Destination Command – indicates that this is the last command on a route.
• Visual Commands – additional visual cues to guide the user visually at this location, such as a 20° turn to the left.

Voice command format

A comma-separated list of commandID,Index,Name,Length where:

• commandID – an instruction in the CommandID lookup table. (See below)
• Index – the index position of this command’s starting coordinate, in the list of RoutePoints.
• Name – name of the street segment.
• Length – length of the street segment (in km).

Destination command format

The destination command only contains the destination commandID.

Visual command format

The visual command only contains the commandID and Index.

Example

The example below contains a list of commands. Voice command in green, Destination command in blue, and Visual commands in red.

10, 0, Athlone Street, 0.0910037, 1, 1, Pretorius Street, 0.259222, 2, 3, Hill Street, 0.166184, 2, 4, Schoeman Street, 0.121007, 50, 6, 50, 9, 2, 10, Festival Street, 0.166234, 2, 11, Pretorius Street, 0.253813, 50, 12, 50, 13, 1, 14, Athlone Street, 0.0910037, 32