Multimap Open API V1.2 Web Services Documentation - Routing
Multimap Open API V1.2 Web Services Documentation - Routing
Web services home >> Overview >> Parameters >> Examples >> Error Codes >> API Web Services XML Schema
The Multimap Open API V1.2 Routing web service module allows you to generate driving or walking (where available) directions between a set of locations, provided as points, addresses or search criteria (which find the specific latitude and longitude for an address or search result). In addition to textual information about the route, the service returns a route vector which can be passed to the draggable-maps API to render a highlight of the route over the map.
Multimap Open API Routing web service enables you to generate routes between two or more locations, specifying options such as language, optimization method, road exclusions and mode of travel. The list of languages that Multimap Open API web services currently support is as follows:
| Language | Abbreviation | Language | Abbreviation |
|---|---|---|---|
| Danish | da | German | de |
| Dutch | nl | Italian | it |
| English (United Kingdom) | en_gb | Norwegian | no |
| English (United States) | en_us | Portuguese | pt |
| French | fr | Spanish | es |
| Swedish | sv |
The Routing module accepts parameters that both define the points that a route should include (up to ten) and set various options about the route. The route points can be specified as addresses, coordinate pairs of latitude and longitude or search criteria.
Each point must be numbered consecutively from "1" in the format parameter_n where n is the point number. For example, a route from a coordinate point to the postcode EC4A 2DY, via the postcode SM6 0AZ, in Great Britain would be specified as:
&lat_1=51.3652&lon_1=-0.0763&qs_3=ec4a2dy
| Parameter | Description | Valid values | Mandatory |
|---|---|---|---|
exclude | This parameter specifies whether to try to avoid highways or motorways. | highways or motorways | No |
key | This parameter refers to a Multimap route key which encapsulates the route points and options. | string | No |
lang | This parameter refers to the language code in which you would like your route instructions to be displayed. | two-letter language code | No |
lat_[COUNTER] | This parameter refers to the latitude coordinate, such as lat_1 or lat_2. Here, lat_1 is used for the first route point and lat_2 for the second route point. | float | No |
lon_[COUNTER] | This parameter refers to the longitude coordinate, such as lon_1 or lon_2. Here, lon_1 is used for the first route point and lon_2 for the second route point. | float | No |
mode | This parameter specifies whether to generate a driving or walking route (where available); it gives a driving route by default. | comma-separated list; driving or walking | No |
optimizeFor | This parameter specifies whether to generate the quickest or shortest route; it shows the quickest by default. | distance or time | No |
optimizeIntermediate | This parameter enables you to control the order of the 'via' points of a route or to 'optimize' them by ordering them automatically. | true or false | No |
| Parameter | Description | Valid values | Mandatory |
|---|---|---|---|
city_[COUNTER] | This parameter refers to the city, town or suburb for the input address, such as city_1 or city_2. | string | No |
countryCode_[COUNTER] | This parameter refers to a two-letter ISO country code for the input address, such as countryCode_1 or countryCode_2. | two-letter ISO country code | No |
postalCode_[COUNTER] | This parameter refers to the postal code for the input address, such as postalCode_1 or postalCode_2. | string | No |
qs_[COUNTER] | This parameter refers to an address or place name entered as a single string, usually including a country code, such as qs_1 or qs_2. | string | No |
region_[COUNTER] | This parameter refers to the region for the input address, such as region_1 or region_2; it is a synonym for state. | string | No |
state_[COUNTER] | This parameter refers to the state for the input address, such as state_1 or state_2; it is a synonym for region. | string | No |
street_[COUNTER] | This parameter refers to the street (optionally including a building number) for the input address, such as street_1 or street_2. | string | No |
Here is an example of a URL requesting details of a route in Great Britain between the postcode EC4A 2DY (latitude 51.52055 and longitude -0.10939) and the partial postcode WC1X, with the mode of travel set to "walking":
http://developer.multimap.com/API/route/1.2/[api_key]?lat_1=51.4485&lon_1=-0.9729&qs_1=RG20AT&countryCode_1=GB&qs_2=RG1
&countryCode_2=GB&mode=walking
(In this example, the qs_1 parameter is used to provide a label for the address at the beginning of the route.)
The URL shown above returns the following response:
<?xml version="1.0" encoding="UTF-8" ?> <Route xmlns="http://developer.multimap.com/API" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://developer.multimap.com/API http://developer.multimap.com/Schema/route_1.2.xsd"
key="GBW,-0.97290:51.44850;-0.97069:51.45488,0" reverseKey="GBW,-0.97069:51.45488;-0.97290:51.44850,0"> <Duration> <Minutes>13</Minutes> </Duration> <Distance> <Miles>0.66</Miles> <KM>1.06</KM> </Distance> <Bounds> <NorthEast> <Lat>51.45488</Lat> <Lon>-0.96993</Lon> </NorthEast> <SouthWest> <Lat>51.44838</Lat> <Lon>-0.97370</Lon> </SouthWest> </Bounds> <Stages> <Stage id="1" stepCount="8" summary="A4 (Pell Street) > A327 (Southampton Street) > Bridge Street > Gun Street >
Minster Street" mode="walking"> <StructuredSummary> <Road> <RoadName>Pell Street</RoadName> <RoadNumber>A4</RoadNumber> <StartPoint> <Lat>51.44838</Lat> <Lon>-0.97288</Lon> </StartPoint> <EndPoint> <Lat>51.44984</Lat> <Lon>-0.97004</Lon> </EndPoint> </Road> <Road startIndex="2" endIndex="2"> <RoadName>Southampton Street</RoadName> <RoadNumber>A327</RoadNumber> <StartPoint> <Lat>51.45007</Lat> <Lon>-0.96994</Lon> </StartPoint> <EndPoint> <Lat>51.45184</Lat> <Lon>-0.97208</Lon> </EndPoint> </Road> </StructuredSummary> <StartAddress> <qs>RG20AT</qs> <CountryCode>GB</CountryCode> </StartAddress> <StartPoint> <Lat>51.44838</Lat> <Lon>-0.97288</Lon> </StartPoint> <EndAddress> <PostalCode>RG1</PostalCode> <DisplayName>RG1</DisplayName> <CountryCode>GB</CountryCode> </EndAddress> <EndPoint> <Lat>51.45488</Lat> <Lon>-0.97069</Lon> </EndPoint> <Duration> <Minutes>13</Minutes> </Duration> <Distance> <Miles>0.66</Miles> <KM>1.06</KM> </Distance> <Bounds> <NorthEast> <Lat>51.45488</Lat> <Lon>-0.96993</Lon> </NorthEast> <SouthWest> <Lat>51.44838</Lat> <Lon>-0.97370</Lon> </SouthWest> </Bounds> <Steps> <Step> <Instruction>Depart on</Instruction> <RoadName>Pell Street</RoadName> <RoadNumber>A4</RoadNumber> <Distance> <Miles>0.18</Miles> <KM>0.29</KM> </Distance> <Duration> <Minutes>4</Minutes> </Duration> <Bearing>E</Bearing> <TurnDirection>L</TurnDirection> <StartPoint> <Lat>51.44838</Lat> <Lon>-0.97288</Lon> </StartPoint> <EndPoint> <Lat>51.44984</Lat> <Lon>-0.97004</Lon> </EndPoint> </Step> <Step> <Instruction>Bear left onto</Instruction> <RoadName>Slip Road</RoadName> <RoadNumber /> <Distance> <Miles>0.02</Miles> <KM>0.03</KM> </Distance> <Duration> <Minutes>0</Minutes> </Duration> <Bearing>NE</Bearing> <TurnDirection>L</TurnDirection> <StartPoint> <Lat>51.44984</Lat> <Lon>-0.97004</Lon> </StartPoint> <EndPoint> <Lat>51.45007</Lat> <Lon>-0.96994</Lon> </EndPoint> </Step> </Steps> </Stage> </Stages> <Vector>-97290,5144850,2,-12,109,23,10,4,7,6,19,37,16,20,39,20,82,37,10,8,0,15,-67,57,-36,37,-25,29,-40,14,-19,0,-12,
4,-10,5,-8,12,-1,11,4,8,-4,28,-6,11,-2,6,-38,36,-46,54,-67,61,64,22,22,10,12,11,10,19,9,6,46,12,137,19,3,1,-2,7
Powered by MapInfohttp://www.multimap.com/static/route_disclaimer.htm</Disclaimer> </Route>
| Code | Notes |
|---|---|
<?xml version="1.0" encoding="UTF-8" ?> | The XML declaration specifies the XML version being used and makes a reference to UTF-8 (eight-bit Unicode Transformation Format), which supports any character in the Unicode standard. |
<Route xmlns="http://developer.multimap.com/API" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://developer.multimap.com/API http://developer.multimap.com/Schema/route_1.2.xsd" | This section refers to the parent element of the document and defines the XML name space. The xsi:schemaLocation section defines the XML location schema.The key element is a unique identifier for the route that refers to the short reference for the route. This Multimap route key encapsulates the route points and options.The reversekey element is a unique identifier for the reverse route.
|
<Duration> | The Duration element refers to the total time duration of the entire journey, which in this example is measured in minutes. |
<Distance> | The Distance element refers to the total distance of the entire journey, which in this example is measured both in miles and kilometers. |
<Bounds> | The Bounds element refers to the rectangular area defined by two points, north-east and south-west.The lat element refers to the latitude coordinate for a route.The lon element refers to the longitude coordinate for a route.
|
<Stages> | The Stages element refers to the point-to-point mapping of the entire route. It displays information pertaining to number of stages, total number of steps in the entire journey, and the mode of travel.The mode element specifies whether to generate a driving or walking route (where available). The default value is "driving".
|
<StructuredSummary> | The StructuredSummary element refers to the summary of the entire journey.The Road element refers to the road name and number. It also provides the latitude and longitude values at the start and end of each road.The RoadName element refers to the name of the road.The RoadNumber element refers to the number of the road.The StartPoint element refers to the coordinate location in latitude and longitude at the beginning of each step in the route.The EndPoint element refers to the coordinate location in latitude and longitude at the end of each step in the route.The startIndex element is a unique identifier for the start of each road on the route.The StructuredSummary element closes here.
|
<StartAddress> | The StartAddress element provides details of the address from where the route initiates.The qs element refers to an address or place name entered as a single string. It is preferably used in conjunction with CountryCode.The CountryCode element refers to the two-letter ISO country code for the input address.The StartAddress element closes here.
|
<EndAddress> | The EndAddress element provides details of the address at which the route terminates.The PostalCode element refers to the postal code for the input address.The CountryCode element refers to the two-letter ISO country code for the input address.The EndAddress element closes here. |
<Steps> | The Steps element refers to the different phases or steps on the entire route.The Instruction element refers to the directions provided for the route.
|
<Bearing>E</Bearing>
| The Bearing element refers to the direction of the route.
|
<TurnDirection>L</TurnDirection>
| The TurnDirection element refers to the direction to follow in a particular step. |
</Steps> | The Steps, Stage and Stages elements close here.
|
<Vector>-97290,5144850,2,-12,109,23,10,4,7,6,19,37,16,20,39,20,82,37, | The Vector element refers to the polyline that highlights the route over the map. |
<Copyright>Powered by MapInfo</Copyright>
| The Copyright element contains the map data providers' copyright-notice text.
|
<Disclaimer>http://www.multimap.com/static/route_disclaimer.htm< | The Disclaimer element contains a link to the Multimap page that shows the full terms and conditions of the map and data use. |
</Route>
| The Route element closes here. |
Here is an example of a URL requesting details of a route in Great Britain between the postcodes NW9 5LL and EN5 4BE via the postcode EC4A 2DY. This example illustrates a route that involves an entry into and out of the London Congestion Charge Zone to reach the end point:
http://developer.multimap.com/API/route/1.2/[api_key]?qs_1=NW95LL&countryCode_1=GB&qs_2=EC4A2DY&countryCode_2=GB
&qs_3=EN54BE&countryCode_3=GB
The URL shown above returns the following response:
<?xml version="1.0" encoding="UTF-8" ?> <Route xmlns="http://developer.multimap.com/API" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://developer.multimap.com/API http://developer.multimap.com/Schema/route_1.2.xsd"
key="GB,-0.23816:51.59894;-0.10845:51.51453;-0.20235:51.65282,0" reverseKey="GB,-0.20235:51.65282;-0.10845:51.51453;
-0.23816:51.59894,0"> <Duration> <Hours>1</Hours> <Minutes>8</Minutes> </Duration> <Distance> <Miles>21.52</Miles> <KM>34.63</KM> </Distance> <Bounds> <NorthEast> <Lat>51.65301</Lat> <Lon>-0.10447</Lon> </NorthEast> <SouthWest> <Lat>51.51310</Lat> <Lon>-0.24670</Lon> </SouthWest> </Bounds> <Stages> <Stage id="1" stepCount="23" summary="Aerodrome Road > A502 (Brent Street) > A400 (Kentish Town Road) >
A4200 (Camden High Street)" mode="driving"> <StructuredSummary> <Road> <StartPoint> <Lat /> <Lon /> </StartPoint> <EndPoint> <Lat /> <Lon /> </EndPoint> </Road> <Road startIndex="8" endIndex="10"> <RoadName>Brent Street</RoadName> <RoadNumber>A502</RoadNumber> <StartPoint> <Lat>51.58974</Lat> <Lon>-0.22166</Lon> </StartPoint> <EndPoint> <Lat>51.56265</Lat> <Lon>-0.17974</Lon> </EndPoint> </Road> ... <Road startIndex="15" endIndex="18"> <RoadName>Camden High Street</RoadName> <RoadNumber>A4200</RoadNumber> <StartPoint> <Lat>51.53532</Lat> <Lon>-0.13921</Lon> </StartPoint> <EndPoint> <Lat>51.51337</Lat> <Lon>-0.11750</Lon> </EndPoint> </Road> </StructuredSummary> <StartAddress> <PostalCode>NW9 5LL</PostalCode> <DisplayName>NW9 5LL</DisplayName> <CountryCode>GB</CountryCode> </StartAddress> <StartPoint> <Lat>51.59987</Lat> <Lon>-0.23923</Lon> </StartPoint> <EndAddress> <PostalCode>EC4A 2DY</PostalCode> <DisplayName>EC4A 2DY</DisplayName> <CountryCode>GB</CountryCode> </EndAddress> <EndPoint> <Lat>51.51453</Lat> <Lon>-0.10845</Lon> </EndPoint> <Duration> <Minutes>31</Minutes> </Duration> <Distance> <Miles>9.70</Miles> <KM>15.61</KM> </Distance> <Bounds> <NorthEast> <Lat>51.59987</Lat> <Lon>-0.10843</Lon> </NorthEast> <SouthWest> <Lat>51.51310</Lat> <Lon>-0.24670</Lon> </SouthWest> </Bounds> <Steps> <Step> <Instruction>Depart on</Instruction> <RoadName>Avion Crescent</RoadName> <RoadNumber /> <Distance> <Miles>0.09</Miles> <KM>0.14</KM> </Distance> <Duration> <Minutes>1</Minutes> </Duration> <Bearing>SW</Bearing> <TurnDirection>R</TurnDirection> <StartPoint> <Lat>51.59987</Lat> <Lon>-0.23923</Lon> </StartPoint> <EndPoint> <Lat>51.59984</Lat> <Lon>-0.23949</Lon> </EndPoint> </Step> ... <Step> <Instruction>Continue straight ahead onto</Instruction> <RoadName>Upper Woburn Place</RoadName> <RoadNumber>A4200</RoadNumber> <Distance> <Miles>1.13</Miles> <KM>1.82</KM> </Distance> <Duration> <Minutes>3</Minutes> </Duration> <Bearing>SE</Bearing> <Information> <Info type="london_congestion_charge">entering</Info> </Information> <StartPoint> <Lat>51.52730</Lat> <Lon>-0.13077</Lon> </StartPoint> <EndPoint> <Lat>51.51337</Lat> <Lon>-0.11750</Lon> </EndPoint> </Step> <Step> <Instruction>Turn left onto</Instruction> <RoadName>Slip Road</RoadName> <RoadNumber /> <Distance> <Miles>0.02</Miles> <KM>0.03</KM> </Distance> <Duration> <Minutes>0</Minutes> </Duration> <Bearing>E</Bearing> <TurnDirection>L</TurnDirection> <Information> <Info type="london_congestion_charge">within</Info> </Information> <StartPoint> <Lat>51.51337</Lat> <Lon>-0.11750</Lon> </StartPoint> <EndPoint> <Lat>51.51327</Lat> <Lon>-0.11702</Lon> </EndPoint> </Step> <Step> <Instruction>Continue straight ahead onto</Instruction> <RoadName>Aldwych</RoadName> <RoadNumber>A4</RoadNumber> <Distance> <Miles>0.34</Miles> <KM>0.55</KM> </Distance> <Duration> <Minutes>1</Minutes> </Duration> <Bearing>E</Bearing> <Information> <Info type="london_congestion_charge">within</Info> </Information> <StartPoint> <Lat>51.51327</Lat> <Lon>-0.11702</Lon> </StartPoint> <EndPoint> <Lat>51.51413</Lat> <Lon>-0.10944</Lon> </EndPoint> </Step> ... <Step> <Instruction>Arrive at your destination</Instruction> <RoadName /> <RoadNumber /> <Distance> <Miles>0.02</Miles> <KM>0.03</KM> </Distance> <Duration> <Minutes>0</Minutes> </Duration> <Bearing>N</Bearing> <Information> <Info type="london_congestion_charge">within</Info> </Information> <StartPoint> <Lat>51.51419</Lat> <Lon>-0.10843</Lon> </StartPoint> <EndPoint> <Lat>51.51453</Lat> <Lon>-0.10845</Lon> </EndPoint> </Step> </Steps> </Stage> <Stage id="2" stepCount="14" summary="A201 > A1 (Islington High Street) > B515 (Liverpool Road) > A1 (Holloway Road)
> A1000" mode="driving"> <StructuredSummary> <Road startIndex="1" endIndex="1"> <RoadNumber>A201</RoadNumber> <StartPoint> <Lat>51.51417</Lat> <Lon>-0.10447</Lon> </StartPoint> <EndPoint> <Lat>51.52506</Lat> <Lon>-0.11061</Lon> </EndPoint> </Road> ... <Road startIndex="10" endIndex="10"> <RoadNumber>A1000</RoadNumber> <StartPoint> <Lat>51.58166</Lat> <Lon>-0.15674</Lon> </StartPoint> <EndPoint> <Lat>51.65292</Lat> <Lon>-0.19962</Lon> </EndPoint> </Road> </StructuredSummary> <StartAddress> <PostalCode>EC4A 2DY</PostalCode> <DisplayName>EC4A 2DY</DisplayName> <CountryCode>GB</CountryCode> </StartAddress> <StartPoint> <Lat>51.51419</Lat> <Lon>-0.10843</Lon> </StartPoint> <EndAddress> <PostalCode>EN5 4BE</PostalCode> <DisplayName>EN5 4BE</DisplayName> <CountryCode>GB</CountryCode> </EndAddress> <EndPoint> <Lat>51.65282</Lat> <Lon>-0.20235</Lon> </EndPoint> <Duration> <Minutes>37</Minutes> </Duration> <Distance> <Miles>11.82</Miles> <KM>19.02</KM> </Distance> <Bounds> <NorthEast> <Lat>51.65301</Lat> <Lon>-0.10447</Lon> </NorthEast> <SouthWest> <Lat>51.51417</Lat> <Lon>-0.20235</Lon> </SouthWest> </Bounds> <Steps> <Step> <Instruction>Depart on</Instruction> <RoadName>Fleet Street</RoadName> <RoadNumber /> <Distance> <Miles>0.19</Miles> <KM>0.31</KM> </Distance> <Duration> <Minutes>1</Minutes> </Duration> <Bearing>E</Bearing> <TurnDirection>L</TurnDirection> <Information> <Info type="london_congestion_charge">entering</Info> </Information> <StartPoint> <Lat>51.51419</Lat> <Lon>-0.10843</Lon> </StartPoint> <EndPoint> <Lat>51.51417</Lat> <Lon>-0.10447</Lon> </