infoware mapsuite Javascript API - Company for Mapping, Routing, GPS-Navigation, Tracking and Telematics solutions

« Previous Chapter 3: Mapping and Geocoding Back to Index Next Chapter 5: Controls »

Chapter 4: Routing

With example 4a we will start with a very simple routing example, where start and destination are given as coordinates. In example 4b we will add more options, like interstations in our route, and in example 4c we will combine routing and geocoding.

4.1 Simple routing example

This example shows how to use the routing client. The procedure is very similar to the geocoding example. If you read the geocoding example already, you should have no problems understanding this code.

Routing example 4a

Source code example 4a:

<!DOCTYPE html>

<html>
	<head>
		<title>mapsuite Javascript API - Chapter 4: Routing example 4a</title>		
		<script type="text/javascript" src="http://iw.mapandroute.de/MapAPI-1.1/js/core.js?vnr=0&pnr=0"></script>
		
		<script type="text/javascript">

			var routingClient = null;
			
			function initialize()
			{
				IWEventManager.addListener(IWLoader, 'onmoduleload', function(event)
				{
					if (event.name == 'routing') {
						//(2) initialize routing client
						routingClient = new IWRoutingClient();
						//we don't need any shapes to show a list
						routingClient.getRouteOptions().setShapeEnabled(false);
						IWEventManager.addListener(routingClient, 'onroute', function(event) {
							//call method to handle results 
							return showRoutingResult(event); 
						});
					}
				});
				//(1) load routing module
				IWLoader.loadModules(['routing']);
			}
			
			//function to start routing
			function doRouting(x1, y1, x2, y2)
			{				
				var startAddress = new IWAddress();
				startAddress.setCoordinate(new IWCoordinate(x1, y1, IWCoordinate.WGS84));
				var destinationAddress = new IWAddress();
				destinationAddress.setCoordinate(new IWCoordinate(x2, y2, IWCoordinate.WGS84));
				
				//(3) calling routing service
				routingClient.route(startAddress, destinationAddress);
			}
			
			//Shows the routing result in a table.
			function showRoutingResult(event)
			{
				//(4) receiving the routing answer
				var route = event.route;
			
				//Formats the driving instructions 
				var formatter = new IWRouteFormatter(route);
		
				var p = document.getElementById('headerRoute');
				p.innerHTML = formatter.createSummaryAsHTML();
						
				var table = document.getElementById('resultTable');								
			
				for(var i = 0; i < route.getSegments(); i++) 
				{		
					var entry = route.getEntry(i);
					//handle route entries ...
				}						
				return true;
			}
		</script>	
			
	</head>
	<body onload="initialize()" class="tutorial">
		<form>
			<!-- ... -->
			<input type="button" value="calculate route" onClick="doRouting()">
		</form>
		<span id="headerRoute"></span>		
		
		<table id="resultTable">
			<!-- ... -->			
		</table>
	</body>
</html>

In this very simple example we let the user enter (already geocoded) coordinates. Like in the geocoding example, we define two javascript methods, doRouting() and showRoutingResult(). In doRouting() we just forward the values from our form we defined in our html code. This method will be executed when the user presses the submit button.

The showRoutingResult() method writes the answer in the table resultTable that we defined at the bottom of our code.

4.1.1 load routing module and listen on module load

To use routing functions you need to load the module 'routing' with following code line:

IWLoader.loadModules(['routing']);

If a module is completely loaded the event 'onmoduleload' is fired.

4.1.2 Creating the routing client

At first we need our routing client, so we instantiate the IWRoutingClient class.

Then we add a new listener to the IWEventManager object. In this case, we listen on a event 'onroute' to call our "showRoutingResult()" method when the routing service has sent a response.

routingClient = new IWRoutingClient();			
IWEventManager.addListener(routingClient, 'onroute', function(event) { return showRoutingResult(event); });

4.1.3 Calling the routing service

The function doRouting() just forward our request to the designated method of the API. This method takes two IWCoordinates. You can add more options here, this will be shown in further examples.

The server will now process our request and will send an answer. This answer will then be catched by our listener.

4.1.4 Receiving the routing answer

If our listener (that we created at step two) catches an answer, it calls our function with the event it receives as parameter. This event contains our route object (IWRoute) and we get it with event.route;

While we have our route now, we want to present it to our user. Therefore we can now go through our route segments and print the details of each route entry in a table. See here IWRouteEntry to see which informations are available for each entry.

4.2 Routing options and interstations

You can customize the routing with several options. These options are presented in the next example. As this example is only a modified version from example 4a.

Routing options example 4b

4.2.1 Routing options

To configure the options we have to initialize a new IWRouteOptions object or change the current options by routingClient.getRouteOptions(). To see all available options see here IWRouteOptions.

4.3.1 Routing with interstations

The routing client needs at least two parameters to calculate a route between the start and destination coordinates. A route can although be based on more than two coordinates. These additional coordinates are called interstations. You can pass them through the routing algorithm by specifying them as an optional parameter. In this simple example we used only two interstations. But there is no limit of interstations. After the route has been calculated by the routing service the listener method showRoutingResult() will be called.

//init array of interstations	
var interstations = new Array();

//interstation 1
var interstationAddress1 = new IWAddress();
interstationAddress1.setCoordinate(new IWCoordinate(x1, y1, IWCoordinate.WGS84));
interstations.push(interstationAddress1);

//interstation 2
var interstationAddress2 = new IWAddress();
interstationAddress2.setCoordinate(new IWCoordinate(x2, y2, IWCoordinate.WGS84));
interstations.push(interstationAddress2);

//calculate route
routingClient.route(startAddress, destinationAddress, interstations);

4.3 Routing and Geocoding

This example shows how to combine routing and geocoding. Most of the code is explained in previous examples, head back to them if you have problems in understanding the code. This implementation doesn't pay much attention to the usability, as the main intention is not to show you how to make a nice user interface, but to show how to work with the API.

Routing with geocoding example 4c

Source code example 4c:

<!DOCTYPE html>

<html>
	<head>
		<title>mapsuite Javascript API - Chapter 4: Routing example 4c</title>		
		<script type="text/javascript" src="http://iw.mapandroute.de/MapAPI-1.1/js/core.js?vnr=0&pnr=0"></script>
		<script type="text/javascript">
			var geocoderClient;
			var routingClient;
			
			function initialize()
			{
				IWEventManager.addListener(IWLoader, 'onmoduleload', function(event)
				{
					if (event.name == 'routing') {
						//(2) initialize routing client
						routingClient = new IWRoutingClient();
						//we don't need any shapes to show a list
						routingClient.getRouteOptions().setShapeEnabled(false);
						IWEventManager.addListener(routingClient, 'onroute', function(event) {
							//call method to handle routing results 
							return showRoutingResult(event); 
						});
					} else if (event.name == 'geocoding') {
						//(2) initialize geocoder client
						geocoderClient = new IWGeocoderClient();
						IWEventManager.addListener(geocoderClient, 'ongeocode', function(event)
						{
							//call method to handle geocoding results 
							return showGeocodingResults(event);
						});
					}
				});
				//(1) load modules
				IWLoader.loadModules(['geocoding', 'routing']);
			}
			
			//function to start geocoding	
			function doGeocoding()
			{				
				var startAddress = document.getElementById('form1').start.value;
				geocoderClient.geocodeAddressString(startAddress, 'D', 10, 'startAddress');
				
				var destAddress = document.getElementById('form1').destination.value;
				geocoderClient.geocodeAddressString(destAddress, 'D', 10, 'destAddress');
			}	
			
			//function to start routing			
			function doRouting()
			{
				var selectStartAddress = document.getElementById('form2').selectStartAddress;
				var startAddress = selectStartAddress.options[selectStartAddress.selectedIndex].address;
				
				var selectDestinationAddress = document.getElementById('form2').selectDestinationAddress;
				var destinationAddress = selectDestinationAddress.options[selectDestinationAddress.selectedIndex].address;

				routingClient.route(startAddress, destinationAddress);
			}
			
			//handle geocoding response
			function showGeocodingResults(event, start){
				var results = event.results;
				//...
			}
			 
			//handle routing response 
			function showRoutingResult(event)
			{
				var route = event.route;
				//...	
			}
		</script>				
	</head>
	<body onload="initialize()" class="tutorial">
		<form id="form1">
			<!-- geocoding form -->
			<input id="button" type="button" value="geocode address" onClick="doGeocoding()">
		</form>
		<form id="form2">
			<!-- routing form -->
			<input id="button" type="button" value="calculate route" onClick="doRouting()">
		</form>	
		<span id="headerRoute"></span>
		<table id="resultTable">
			<!-- results -->
		</table>
	</body>
</html>

4.3.1 load modules

To use routing and geocoding functions you need to load both modules 'routing' and 'geocoding' with following code line:

IWLoader.loadModules(['geocoding', 'routing']);

If a module is completely loaded the event 'onmoduleload' is fired with the given module name in the event. Here we define the already known listeners for 'onroute' and 'ongeocode' events, where we can call the methods to handle the response from routing and geocoding service.

4.4 Drawing the route on the map

The following example draws the calculated route on the map.

Drawing the route on the map example 4d

The functions to show a simple map is available in the API-core. But to draw the route on the map, we need the additional module 'graphics'.

IWLoader.loadModules(['geocoding', 'routing', 'graphics']);

Furthermore we need to initialize an IWMapRenderer if the module 'graphics' is loaded

IWEventManager.addListener(IWLoader, 'onmoduleload', function(event)
{
	if (event.name == 'routing') {
		//initialize routing client ...
	} else if (event.name == 'geocoding') {
		//initialize geocoder client ...
	} else if (event.name == 'graphics') {
		//initialize map and maprenderer
		map = new IWMap(document.getElementById('mapContainer'));
		map.setCenter(new IWCoordinate(7.1408879, 50.70150837, IWCoordinate.WGS84));
		renderer = new IWMapRenderer(map);
	}
});

To draw the route on the map we extend the function showRoutingResult() with these lines:

//remove the last rendererd route
renderer.clearContainer();

//render the route on the map
var attributes = {
	stroke: 'rgb(50, 100, 0)', // a CSS color code like #ff0000, white or rgb(50, 100, 0)
	strokeDashStyle: 'solid', // solid, dotted or dashed
	strokeWidth: 4, // width in pixels
	strokeOpacity: 0.9 
};

renderer.drawPolyline(event.route.getCoordinates(), attributes);
renderer.render();

// set the new center and zooming level to show the whole route on the map.
map.setCenter(route.getBounds().getCenter(), map.getBoundsZoomlevel(route.getBounds()));

4.5 Creating driving instructions

The following example uses the formatter class IWRouteFormatter to create readable driving instructions.

driving instructions example 4e

we extend the function showRoutingResult() with these lines:

var formatter = new IWRouteFormatter(route);
tr.insertCell(1).innerHTML = formatter.createImageAsHTML(i);
tr.insertCell(2).innerHTML = formatter.createDescriptionAsHTML(i);
tr.insertCell(3).innerHTML = formatter.createDistanceAsHTML(i);

4.6 Routing images

The following table shows the urls of available routing images.

Name	Direction Code	Image
`img/controls/routing/blue_sharp_left.gif`	`-3`
`img/controls/routing/blue_left.gif`	`-2`
`img/controls/routing/blue_half_left.gif`	`-1`
`img/controls/routing/blue_straight_ahead.gif`	`0`
`img/controls/routing/blue_half_right.gif`	`1`
`img/controls/routing/blue_right.gif`	`2`
`img/controls/routing/blue_sharp_right.gif`	`3`
`img/controls/routing/blue_roundabout.gif`	`11`
`img/controls/routing/blue_highway.gif`
`img/controls/routing/blue_highway_exit.gif`
`img/controls/routing/blue_highway_junction.gif`
`img/controls/routing/blue_destination.gif`

Instead of using different images you can use sprite images in different colors:

img/controls/routing/sprite-routing.gif: blau
img/controls/routing/sprite-routing-black.gif: schwarz
img/controls/routing/sprite-routing-grey.gif: grau

« Previous Chapter 3: Mapping and Geocoding Back to Index Next Chapter 5: Controls »