Multimap Open API V1.2 Example

Routing - Basic Example new

This example demonstrates how to use the Multimap Open API's optional Routing module to calculate routes and present travel directions in a list and on a map.

You can use the Multimap Open API to show and describe a highlighted route between two locations (including intermediate 'via' points, if required) while controlling the restrictions on the routes that are available and the language in which travel directions are presented.

The Routing module of the Multimap Open API can generate routes that link numerous locations: it achieves this by processing a list of locations, treating the list's:

first item as the route's start point;
last item as the route's end point; and
any intermediate items as 'via' points.

This means that you can use the Multimap Open API to control the order of 'via' points of a route or to 'optimize' them by ordering them automatically.

Route Structure:

The Multimap Open API models routes in a structured format as described below:

Term	Description
Route	This term describes the series of one or more route stages, each containing one or more route steps, between two or more locations. Every route has a start point and an end point and may contain one or more intermediate 'via' points.
Stage	This term denotes a series of one or more route steps that link any two points along a route. A separate route stage exists between every pair of points that have been specified along the route, including 'via' points.
Step	This term denotes a portion of a route stage containing one instruction, such as "Depart on Hazlitt Road for 0.1 miles".

For a full description of all attributes and elements of the Multimap Open API route structure, please see the Route Structure page.

If you are familiar with XML, please see Multimap's Open API Routing web service documentation for a example of a typical route structure contained in an XML response.

'Snap to' feature

Where the start or end point of a route does not correspond to a point on a recognized route network, the Multimap Open API attempts to 'snap' that point's coordinates to the nearest road within one kilometer. Since a location that has been 'snapped' any distance greater than this is unlikely to bear much resemblance to the location that was originally requested, the Multimap Open API returns an error if a user specifies a location more than one kilometer away from the nearest road (for example, in an extremely rural area or out at sea).

Functions introduced:

MMRouteRequester: request()

What You Should See

If you view this in your browser you should see a Multimap draggable map centered on Saint James Avenue, Boston, Massachusetts, USA, at zoom factor 15.

To generate a route:

Make a selection for the start and end points for your route. The latitude and longitude that correspond to your selections will be passed in as start and end 'locations' for the route.
Optionally, you can also select one or two additional waypoints through which the route will travel. If selected, the latitude and longitude that correspond to your selections will be passed in as additional intermediate locations (or 'via' points) for the route.
Click on the "Go" button to view your results.
Your route is displayed, highlighted on a draggable map, with a numbered series of travel directions listed below it; each of the list's numbered instructions is shown on the map as a marker with an info box.

A journey with 'via' points is listed beneath the map in separate stages.

Important note: You must display copyright and disclaimer notices when providing travel directions.

The Map

	Get directions: Choose Starting Point: Choose Ending Point: Add Optional Waypoint: Add Optional Waypoint:
Messages and results will be placed here

The Code

There are four parts to the code below. The first is the line that links to the Multimap Open API. The second is an example of the HTML you must have in your page. The third is an example of the JavaScript required to implement the page. Finally, the fourth is the CSS code that you should add to your web page.

Please note that, to ensure that your Multimap API routes appear correctly in browsers such as Internet Explorer, you should include in your web page both the first line of the header code and the example of CSS code shown in the boxes below.

The header code

<html xmlns="http://www.w3.org/1999/xhtml" xmlns:v="urn:schemas-microsoft-com:vml" >

<script type="text/javascript" src="http://developer.multimap.com/API/maps/1.2/OA08061815803962482"></script>

The body code

Sorry, JavaScript required...

Sorry, JavaScript required...

Sorry, JavaScript required...

The JavaScript code

Sorry, JavaScript required...

The CSS code

Sorry, JavaScript required...

Note on printing

Please note that you may not be able to print a highlighted route or a polyline from the Multimap Open API when using a Mozilla Firefox or an Opera browser. If you encounter such a problem, please try a different browser.

For more information on the subject of Multimap Open API JavaScript code (including error codes for the Routing module), please read the Multimap Open API documentation at: http://www.multimap.com/share/documentation/openapi/1.2/classes/.

Back to examples.

Further Help

If you require further help with your Multimap Open API implementation, please visit the Multimap Developer Forums.

For Open API news, announcements and other information, please see our blog.

For general account enquiries or further services, please contact the Multimap Sales team:

London, Great Britain	+44 (0)20 7632 7800
email:	sales@multimap.com