Multimap Open API V1.2 : Documentation - Route Structure and Actions

The Multimap Open API models routes in a structured format:


Route
++Duration
  ++Days, Hours and/or Minutes
++Distance
  ++Miles or KM
++Bounds
  ++NorthEast
    ++Lat and Lon
  ++SouthWest
    ++Lat and Lon
++Stages
  ++Stage 1
    ++StructuredSummary
      ++Road
        ++RoadName
        ++RoadNumber
        ++StartPoint
          ++Lat and Lon
        ++EndPoint
          ++Lat and Lon
    ++StartAddress
      ++(PostalCode and DisplayName or 'Quick Search' text string) and CountryCode
    ++StartPoint
      ++Lat and Lon
    ++EndAddress
      ++(PostalCode and DisplayName or 'Quick Search' text string) and CountryCode
    ++EndPoint
      ++Lat and Lon
    ++Duration
      ++Days, Hours and/or Minutes
    ++Distance
      ++Miles or KM
    ++Bounds
      ++NorthEast
        ++Lat and Lon
      ++SouthWest
        ++Lat and Lon
    ++Steps
      ++Step 1
        ++Instruction
        ++RoadName
        ++RoadNumber
        ++Distance
          ++Miles or KM
        ++Duration
          ++Days, Hours and/or Minutes
        ++Bearing
        ++TurnDirection
        ++Actions
          ++Action
        ++Information
          ++Info
        ++StartPoint
          ++Lat and Lon
        ++EndPoint
          ++Lat and Lon
++Vector
++Copyright 
++Disclaimer

A route can have elements and attributes as shown above and described below:

Term	'Parent' Element	Description	Elements/Attributes
Route	N/A	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.	Duration, Distance, Bounds, Stages, Vector, Copyright, Disclaimer
Stage	Route	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.	Structured Summary (Road), Start Address, Start Point, End Address, End Point, Duration, Distance, Bounds, Steps
Step	Stage	This term denotes a portion of a route stage containing one instruction, such as "Depart on Hazlitt Road for 0.1 miles".	Instruction, Road Name, Road Number, Duration, Distance, Bearing, Turn Direction, Start Point, End Point
Bounds	Route or Stage	This term denotes the rectangular area defined by two points, north-east and south-west; it refers to these two points by their coordinates of latitude and longitude.	North-east (Lat/Lon), South-west (Lat/Lon)
Duration	Route, Stage or Step	This term denotes the time duration of a journey along a route, stage or step.	Minutes, Hours or Days
Distance	Route, Stage or Step	This term denotes the distance along a route, stage or step.	Miles or KM
Start Point	Route, Stage or Step	This term denotes the coordinates at the beginning of a route, stage or step.	Latitude, Longitude
End Point	Route, Stage or Step	This term denotes the coordinates at the end of a route, stage or step.	Latitude, Longitude
Structured Summary (Road)	Stage	This term denotes a summary of the current stage of a route.	Road Name, Road Number, Start Point, End Point
Start Address	Stage	This term denotes the address from where the current route stage initiates.	'Quick Search' text string, Country Code
End Address	Stage	This term denotes the address at which the current route stage terminates.	'Quick Search' text string, Country Code
Road Name, Road Number	Stage (Structured Summary (Road)) or Step	These terms refer to the name and number of the road in the current stage summary or step .	Text
Instruction	Step	This term refers to the action(s) provided for the route step.	Text (for example, "Depart on")
Bearing	Step	This term denotes the direction of the current route step with respect to the points of the compass.	Text (for example, "E")
Turn Direction	Step	This term denotes the direction of the current route step relative to the current position in the route step.	Text (for example, "L")
Actions	Step	This element contains a list of one or more permissible actions.	Action
Action	Step	This is the internal name of a single action.	Any one of a list of permissible actions
Information	Step	This element includes one or more pieces of local information about a route step, such as its country code and road class.	Info
Info	Step	This element includes a single piece of local information about a route step, such as its country code.	String
Vector	Route	This term denotes any polyline that highlights a route over a map.	Comma-separated list comprising an initial pair of coordinates followed by a series of pairs of x and y displacement vectors, giving details of all the points on a polyline that highlights a route over a map.
Copyright	Route	This element contains the map data providers' copyright-notice text.	None (Text)
Disclaimer	Route	This element contains a link to the Multimap page that shows the full terms and conditions of the map and data use.	None (URL/Text)

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

Route actions

These are the internal names for the full set of Multimap route instructions: you can map the keywords within your own applications according to your preferences.

Action (code)	Description	Example
depart	Depart on [ROADNAME]	Depart on Buckfast Close.
arrive	Arrive at [DESTINATION]	Arrive at your destination.
continue	Continue [STRAIGHT AHEAD] [ALONG/ONTO ROADNAME]	Continue straight ahead onto Coombe Road.
bear_left	Bear left [ONTO ROADNAME]	Bear left onto Chester Road.
bear_right	Bear right [ONTO ROADNAME]	Bear right onto Ramp (M6 J19).
turn_left	Turn left [ONTO ROADNAME]	Turn left onto Wilbraham Road.
turn_right	Turn right [ONTO ROADNAME]	Turn right onto Windmill Road.
sharp_left	Turn sharp left [ONTO ROADNAME]	Turn sharp left onto Dolphin Court Road.
sharp_right	Turn sharp right [ONTO ROADNAME]	Turn sharp left onto Shorton Valley Road.
uturn_left	Take a U-turn left [ONTO ROADNAME]	Take a U-turn left onto A5104.
uturn_right	Take a U-turn right [ONTO ROADNAME]	Take a U-turn right onto I95.
exit	Exit [ONTO ROADNAME]	Exit onto Ramp (M56 J7).
exit_left	Exit [LEFT] [ONTO ROADNAME]	Exit onto Ramp (M6 J19).
exit_right	Exit [RIGHT] [ONTO ROADNAME]	Exit onto Quai de Bercy.
roundabout	At the roundabout (TRAFFIC CIRCLE), take the [Nth] exit [ONTO ROADNAME]	At the roundabout, take the ninth exit onto Gillespie Street.
roundabout_1	At the roundabout, take the first exit [ONTO ROADNAME]	At the roundabout, take the first exit onto North Circular Road.
roundabout_2	At the roundabout, take the second exit [ONTO ROADNAME]	At the roundabout, take the second exit onto Marldon Way.
roundabout_3	At the roundabout, take the third exit [ONTO ROADNAME]	At the roundabout, take the third exit onto Chester Road.
roundabout_4	At the roundabout, take the fourth exit [ONTO ROADNAME]	At the roundabout, take the fourth exit onto Market Street.
roundabout_5	At the roundabout, take the fifth exit [ONTO ROADNAME]	At the roundabout, take the fifth exit onto South Street.
roundabout_6	At the roundabout, take the sixth exit [ONTO ROADNAME]	At the roundabout, take the sixth exit onto Burford Road.
roundabout_7	At the roundabout, take the seventh exit [ONTO ROADNAME]	At the roundabout, take the seventh exit onto Fallow Way.
roundabout_8	At the roundabout, take the eighth exit [ONTO ROADNAME]	At the roundabout, take the eighth exit onto Station Approach.
merge	Merge onto [ROADNAME]	Merge onto M60.
merge_left	Merge left onto [ROADNAME]	Merge left onto A6.
merge_right	Merge right onto [ROADNAME]	Merge right onto N17.
ferry	Board [FERRY ROUTE]	Board Dover - Calais (E15).
rail_ferry	Board [RAIL-FERRY ROUTE]	Board Folkestone - Calais.

Further Help

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

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

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