+27 87 310 6400 | products@afrigis.co.za
bclose

AfriGIS Routing

Plan optimal routes and driving directions while considering real-time traffic.

Routing_2
The AfriGIS Routing & Traffic web service allows users to plan routes based on the AfriGIS Streets dataset. Routing options include:

  • Shortest distance or quickest time route
  • Avoid Toll roads, Highways or Main roads
  • Route by Walking
  • Multiple stop points (via points).

The premium Traffic service will calculate the best possible route between the stop points taking live traffic conditions into account. Traffic is supplied in partnership with Altech Netstar and updated at five minute intervals.

If you have multiple stop points (for example, a courier service), the web service can provide an optimal route to visit all of them in the least time.

The API returns the planned route information in either XML or JSON format, which is easily consumed and transformed into printed directions reports or displayed on a map.

 

See also:

API documentation

1. Introduction

2. GetNavigationRouteAG

3. GetRouteAG

4. Additional GetNavigationRouteAG Response Details

4.1 RoutePoints Details

4.2 FeatureLists Details

4.3 CommandLists Details

 

1.Introduction

AfriGIS Routing has two similar requests which support routing:

  • GetNavigationRouteAG – this returns the necessary information to support an interactive navigation solution, including coordinates for drawing the route on a map or navigation screen, street level details such as name, travel time and traffic status, voice guided or visual navigation commands, and the optimal order of via points.
  • GetRouteAG – this returns alternative routing information, ideal for rendering a tabular turn-by-turn set of driving direction instructions.
GetNavigationRouteAG

GetNavigationRouteAG

GetRouteAG

GetRouteAG

 

2. GetNavigationRouteAG

Returns the necessary information to support an interactive navigation solution, including coordinates for drawing the route on a map or navigation screen, street level details such as name, travel time and traffic status, voice guided or visual navigation commands, and the optimal order of via points.

Parameters

Required Parameters

  • version – use the latest version = 1.1.7
  • routing – contains the routing request, such as start and end points, optional via points, the routing layer and the optimisation parameter. The parameter structure is in three parts, each separated by a dollar sign (“$”): ROUTING_LAYER_NAME$OPTIMISATION_PARAM$LIST_OF_POINTS, where:
    • ROUTING_LAYER_NAME – the name of the routing layer. Most commonly this will be AG_STREETS.
    • OPTIMISATION_PARAM – one of TRAVELTIME, LENGTH, TRAFFIC, or WALKING. The routing will be optimised according to this parameter.
    • LIST_OF_POINTS – the list of route points, separated by a caret symbol (“^”). In this list, the first point is the SOURCE and the last point is the DESTINATION of the route. All other points in between the source and the destination are VIA points. Each point has the following format:
      • LATLONG,<LONGITUDE>,<LATITUDE> (Yes, despite the prefix being LATLONG, please note that the order is longitude followed by latitude.)

Example: ROUTING=AG_STREETS$TRAVELTIME$LATLONG,28.229623,-25.744242^LATLONG,28.231233,-25.744928^LATLONG,28.232295,-25.745711^LATLONG,28.228668,-25.746644

Optional Parameters

  • dirAngle– the initial direction that the user is travelling in, 0 – 360, clockwise from North = 0. You can use this parameter to constraint the starting directions, if the user is already moving in a known direction.
  • avoidType – one of TOLLROAD, HIGHWAY, MAIN_ROADS, STREET. If possible, AfriGIS Routing will avoid making use of this type of road, when finding a routing solution.
  • threshold– the maximum distance (in metres), from the SOURCE point to the closest road. If the point is further than this, an error message will be found in the Status object.
  • TSPenabled – a boolean to enable route optimisation (TSP) on the list of points. Default = false. If true, the SOURCE and DESTINATION points are fixed and all VIA points are then ordered to produce an optimal route.
  • outputformat – JSON, JSON-GZIP, XML or GML2-GZIP. Default = XML.

Sample Request:

https://saas.afrigis.co.za/rest/2/ms.getNavigationRouteAG/[AUTH_PARMS]/?VERSION=1.1.7&ROUTING=AG_STREETS$LENGTH$LATLONG,28.229623,-25.744242^LATLONG,28.231233,-25.744928^LATLONG,28.232295,-25.745711^LATLONG,28.228668,-25.746644&OUTPUTFORMAT=JSON

Click to expand Sample Response

 

Response Description

The first thing you should check is Status = Success. If so, the response contains:

  • Status – a string contain Success or Error.
  • Version – the version of the response object should be 1.1.7, as you requested.
  • RoutingLayer – the name of the layer used in the route calculation.
  • RoutePoints – 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 following FeatureLists or CommandLists objects refer to this list of points. See RoutePoints Details for more information.
  • FeatureLists – for each different street segment on the route, a comma-separated list containing the street ID, the starting index (refer to RoutePoints), the travel time and the traffic category (or status). The number of features (street segments) is given by TotalFeature. Format: ID1,Index1,Traveltime1,TrafficCategory1,ID2,Index2,Traveltime2,TrafficCategory2,… See FeatureLists Details for more information.
  • CommandLists – the voice 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. See CommandLists Details for more information.
  • ViaPoints – the index (refer to RoutePoints) of any optional via points in the routing request. For a TSP request, the order relates to the navigational order, not the original order – see ViaPointOrder below. In other words, ViaPoints will always be numerically increasing.
  • ViaPointOrder – only present for a TSP request, this list represents the optimal order of via points with respect to their original order in the request. E.g. if the original LIST_OF_POINTS = Start,Via1,Via2,Via3,Via4,End and if ViaPointOrder = 2,4,3,1, then the optimal navigation order will be Start,Via2,Via4,Via3,Via1,End.
  • TotalLength – the total length of the route, in kilometres
  • TotalTravelTime – the total time, in minutes, it would take to travel the route
  • TotalTrafficTime – the total time considering live traffic, in minutes, it would take to travel the route. Note: If the OPTIMISATION_PARAM is not TRAFFIC, the value would be the same as TotalTravelTime.
  • LastUpdatedTime – the timestamp of the last traffic update, if traffic is enabled.

 

3. GetRouteAG

Returns alternative routing information, ideal for rendering a tabular turn-by-turn set of driving direction instructions.

Parameters

These parameters are identical to GetNavigationRouteAG.

Required Parameters

  • version – use the latest version = 1.1.7
  • routing – contains the routing request, such as start and end points, optional via points, the routing layer and the optimisation parameter. The parameter structure is in three parts, each separated by a dollar sign (“$”): ROUTING_LAYER_NAME$OPTIMISATION_PARAM$LIST_OF_POINTS, where:
    • ROUTING_LAYER_NAME – the name of the routing layer. Most commonly this will be AG_STREETS.
    • OPTIMISATION_PARAM – one of TRAVELTIME, LENGTH, TRAFFIC, or WALKING. The routing will be optimised according to this parameter.
    • LIST_OF_POINTS – the list of route points, separated by a caret symbol (“^”). In this list, the first point is the SOURCE and the last point is the DESTINATION of the route. All other points in between the source and the destination are VIA points. Each point has the following format:
      • LATLONG,<LONGITUDE>,<LATITUDE> (Yes, despite the prefix being LATLONG, please note that the order is longitude followed by latitude.)

Example: ROUTING=AG_STREETS$TRAVELTIME$LATLONG,28.229623,-25.744242^LATLONG,28.231233,-25.744928^LATLONG,28.232295,-25.745711^LATLONG,28.228668,-25.746644

Optional Parameters

  • dirAngle– the initial direction that the user is travelling in, 0 – 360, clockwise from North = 0. You can use this parameter to constraint the starting directions, if the user is already moving in a known direction.
  • avoidType – one of TOLLROAD, HIGHWAY, MAIN_ROADS, STREET. If possible, AfriGIS Routing will avoid making use of this type of road, when finding a routing solution.
  • threshold– the maximum distance (in metres), from the SOURCE point to the closest road. If the point is further than this, an error message will be found in the Status object.
  • TSPenabled – a boolean to enable route optimisation (TSP) on the list of points. Default = false. If true, the SOURCE and DESTINATION points are fixed and all VIA points are then ordered to produce an optimal route.
  • outputformat – JSON, JSON-GZIP, XML or GML2-GZIP. Default = XML.

Sample Request:

https://saas.afrigis.co.za/rest/2/ms.getRouteAG/[AUTH_PARMS]/?VERSION=1.1.7&ROUTING=AG_STREETS$LENGTH$LATLONG,28.22974,-25.74422^LATLONG,28.227223,-25.745238&OUTPUTFORMAT=JSON

Click to expand Sample Response

 

Response Description

The first thing you should check is Status = Success. If so, the response contains:

  • Status – a string contain Success or Error.
  • RoutingLayer – the name of the layer used in the route calculation.
  • RoutingParameter – the OPTIMISATION_PARAM that was requested.
  • RoutingPath – an array, for each row in the table of driving instructions, of objects that include, amongst others:
    • name – street name.
    • length and cum_length– the total (cumulative) length, in kilometres, from the start of the route, to the end of this section.
    • estimated_travel_time andcum_estimated_travel_time– the total (cumulative) travel time, in minutes, from the start of the route, to the end of this section.
    • abs_dir – North|South|East|West
    • abs_dir_angle – counter-clockwise angle, where East = 0, in the range [0, 360).
    • rel_dir – Start|Stop|Turn Left|Turn Right, etc.
    • rel_dir_angle – counter-clockwise angle, with respect to the previous segment, in the range (-180, 180). For the very first segment, this value is 540.
    • starting_point and ending_point coordinates.
  • TotalLength – the total length of the route, in kilometres
  • TotalTravelTime – the total time, in minutes, it would take to travel the route
  • TotalTrafficTime – the total time considering live traffic, in minutes, it would take to travel the route. Note: If the OPTIMISATION_PARAM is not TRAFFIC, the value would be the same as TotalTravelTime.

 

4. Additional GetNavigationRouteAG Response Details

4.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

Index
(Zero based)
BCDELongitudeLatitude
=B[n]+D[n-1]=C[n]+E[n-1]D[n]/100000E[n]/100000
02822974-25744222822974-257442228.22974-25.74422
15-822822979-257450428.22979-25.74504
2-237-182822742-257452228.22742-25.74522
3-20-12822722-257452328.22722-25.74523
412-1502822734-257467328.22734-25.74673
52322822757-257467128.22757-25.74671
61512822772-257467028.22772-25.7467
7235172823007-257465328.23007-25.74653
814282823149-257464528.23149-25.74645
94342823192-257464128.23192-25.74641
104532823237-257463828.23237-25.74638
11-141502823223-257448828.23223-25.74488
12-32-22823191-257449028.23191-25.7449
13-23-22823168-257449228.23168-25.74492
14-189-122822979-257450428.22979-25.74504
15-5822822974-257442228.22974-25.74422

 

4.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), the travel time and the traffic category (or status) 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.
  • TrafficCategory – for TRAFFIC optimisation, the category of traffic speeds on major roads for drawing purposes (one of 1_freeflowing, 2_delay, 3_congested, 4_crawling, undefined).

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

FeatureIDIndexTravelTimeTrafficCategory
16488500.220341
undefined
16446910.477737
3_congested
16465130.432173
undefined
16449640.078686
1_freeflowing
16449660.507153
1_freeflowing
16449690.0551543
1_freeflowing
164883100.432293
undefined
164882110.0724996
1_freeflowing
164882120.255014
1_freeflowing
164885130.387007
undefined

 

4.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.

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

Voice CommandsCommand ID
Start10
Turn Right1
Turn Left2
Keep Left3
Keep Right4
Sharply Left5
Sharply Right6
U Turn Left7
U Turn Right8
Keep Left and Take Highway11
Keep Right and Take Highway12
Keep Left and Take Exit13
Keep Right and Take Exit14
Take Roundabout19
Take Nth Exit from Roundabout20+N
Destination CommandsCommand ID
Destination is on the road30
Destination is on the right31
Destination is on the left32
Visual Commands
(Angle of deviation)
Command ID
0-5° on both left and right sides50
5-15° on left side51
15-25° on left side52
25-35° on left side53
... for every further 10°...... increase by 1...
165-175° on left side67
more than 175° on left side68
5-15° on right side71
15-25° on right side72
25-35° on right side73
... for every further 10°...... increase by 1...
165-175° on right side87
more than 175° on right side88

 

Project Details