Multimap API V1.2 Web Services Documentation - Routing
Multimap API V1.2 Web Services Documentation - Routing
The Multimap 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.
The Multimap API Routing web service enables you to generate routes between two or more locations, specifying options such as language, road exclusions and mode of travel.
The Multimap API can now also include information about carbon emissions in the directions it returns for journeys by road; if you wish your service to contain this additional option, please contact your Multimap account manager.
The Multimap 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 API route structure, please see the Route Structure page.
Please see the Notes on Response 1 section of this web page for a example of a typical route structure contained in an XML response.
Where the start or end point of a route does not correspond to a point on a recognized route network, the Multimap 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 API Routing web service returns an Error code 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).
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_2=sm60az&qs_3=ec4a2dy
Similarly, to use search criteria to specify a point, you must specify a data source to search on.
This is done by including the dataSource_n parameter, (where n is the point number)
with a value as described in the Searching Parameters section
of this document.
A single-field filter parameter must also be used. So, for example:
&dataSource_2=mm.clients.[datasource1]&fieldname_2=id&operator_2=eq&value_2=2
This example would search the specified data source for a row with an identifier of "2". This search result would be used as the second route point (since "_2" is used on each parameter).
[Note: Please replace "parameter_[COUNTER]" with incremental numbers
such as parameter_1,parameter_2,...,parameter_n.
In these examples, parameter_1 is used for the first route point
and parameter_2 for the second route point.]
The Routing web service parameters, description and values are as follows:
| 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 |
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 |
locale |
This parameter determines the language of route instructions, appearance of labels and other text on a static map, based on settings for language and geographic area. | Any of the set of codes prescribed in the
list of permissible locale values |
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 |
(*Please note that the exclude parameter does not currently apply to routes in North America.)
| 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 |
| Parameter | Description | Valid values | Mandatory |
|---|---|---|---|
bb_[COUNTER] |
This parameter refers to a string that specifies the bounding box for a search,
such as bb_1 or bb_2. |
String of format: min_lon,min_lat;max_lon,max_lat |
No |
compoundOrder_[COUNTER] |
This parameter refers to the order in which the operators should be applied,
such as compoundOrder_1,compoundOrder_2,...,compoundOrder_n. |
Comma-separated list | No |
compoundThreshold_[COUNTER] |
This parameter refers to the number of records the compound query should try to retrieve. If set to "0", the compound query stops as soon as one of the operators matches at least one row. If set to "10", the compound query continues to run until at least ten matches are found, or there are no more operators to use. | Integer | No |
dataSource_[COUNTER] |
This parameter specifies the data source to use for a particular route point,
such as dataSource_1 or dataSource_2. |
String | No |
distanceUnits_[COUNTER] |
This parameter specifies the units in which the maxDistance
and minDistance parameters are shown,
such as distanceUnits_1 or distanceUnits_2. |
"KM" or "miles" | No |
fieldname_[COUNTER] |
This parameter specifies the name of the field in the data source to filter on,
such as fieldname_1 or fieldname_2. |
String | No |
maxDistance_[COUNTER] |
This parameter specifies the maximum distance a record must be
from the specified search point ("KM" by default),
such as maxDistance_1 or maxDistance_2. |
Float | No |
minDistance_[COUNTER] |
This parameter specifies the minimum distance a record must be
from the specified search point ("KM" by default),
such as minDistance_1 or minDistance_2. |
Float | No |
operator_[COUNTER] |
This parameter specifies the operator to be used in the field filter,
such as operator_1 or operator_2. |
String | No |
orderByFields_[COUNTER] |
This parameter specifies a comma-separated list of field names by which ordering should be applied,
such as orderByFields_1 or orderByFields_2. |
String or comma-separated list | No |
orderByOrder_[COUNTER] |
This parameter specifies a comma-separated list of orders by which ordering should be applied.
This should match with the orderByFields value. |
Comma-separated list of ascending or descending values | No |
returnFields_[COUNTER] |
This parameter specifies a comma-separated list of field names that should appear on the results page,
such as returnFields_1 or returnFields_2.
All fields are returned by default. |
String or comma-separated list | No |
searchFirstAlt_[COUNTER] |
If set to 1, the first result of a multiple-match search is used as the route point. | 1 or 0 | No |
startIndex_[COUNTER] |
This parameter specifies the index of the first record to display
(starting at and defaulting to 1), such as startIndex_1 or startIndex_2. |
Integer | No |
value_[COUNTER] |
This parameter specifies the value used in a field-filter search,
such as value_1 or value_2. |
String | No |
If your Multimap API Routing service includes the "Carbon Emissions" option, your XML responses contain emission-related information for a series of default vehicle types; you can also specify your own custom types of vehicle using the parameters described in this section.
| Parameter | Description | Valid values | Mandatory |
|---|---|---|---|
emissions |
This parameter determines whether the XML response should return carbon-emission details (where they are available). | "true" or "false" (default is "false") | emissions=true |
custom_value_[COUNTER] |
This parameter represents the amount of fuel burned per custom unit (see below). | Float | custom_value_1=35 |
custom_unit_[COUNTER] |
This parameter describes the type of unit in which carbon emissions are be measured:
| "mpg", "mpg_imp" or "lper100km" | custom_unit_2=mpg_imp |
custom_type_[COUNTER] |
This parameter describes the type of fuel used. | "diesel" or "gas" (default is "gas") | custom_type_3=diesel |
custom_name_[COUNTER] |
This parameter contains the name or label by which you wish to denote this type of vehicle. | String | custom_name_4=GreenCar |
Please follow this link to see an example of an XML response including Carbon Emissions.
Here is an example of a URL requesting details of a route in Great Britain between the postcode RG2 0AT (latitude 51.4485 and longitude -0.9729) and the partial postcode RG1, with the mode of travel set to "walking":
http://clients.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://clients.multimap.com/API" xmlns:xsi="http://www.w3.org/2001/XMLSchema-
instance" xsi:schemaLocation="http://clients.multimap.com/API http://clients.multimap.com/
Schema/route_1.2.xsd" key="DC,-0.97290:51.44850;-0.97050:51.45446,8" reverseKey="DC,-0.97050:
51.45446;-0.97290:51.44850,8"> <Duration> <Minutes>13</Minutes> </Duration> <Distance> <Miles>0.65</Miles> <KM>1.05</KM> </Distance> <Bounds> <NorthEast> <Lat>51.45448</Lat> <Lon>-0.96715</Lon> </NorthEast> <SouthWest> <Lat>51.44836</Lat> <Lon>-0.97307</Lon> </SouthWest> </Bounds> <Stages> <Stage id="1" stepCount="8" summary="A4 (Pell Street) > A327 (London Street) > Yield
Hall Place" mode="walking"> <StartAddress> <qs>RG20AT</qs> <CountryCode>GB</CountryCode> </StartAddress> <StartPoint> <Lat>51.44847</Lat> <Lon>-0.97307</Lon> </StartPoint> <EndAddress> <PostalCode>RG1</PostalCode> <DisplayName>RG1</DisplayName> <CountryCode>GB</CountryCode> </EndAddress> <EndPoint> <Lat>51.45448</Lat> <Lon>-0.97037</Lon> </EndPoint> <Duration> <Minutes>13</Minutes> </Duration> <Distance> <Miles>0.65</Miles> <KM>1.05</KM> </Distance> <Bounds> <NorthEast /> <SouthWest /> </Bounds> <Steps> <Step> <Instruction>Depart on</Instruction> <RoadName>Katesgrove Lane</RoadName> <RoadNumber /> <Distance> <Miles>0.01</Miles> <KM>0.02</KM> </Distance> <Duration> <Minutes>0</Minutes> </Duration> <Bearing>S</Bearing> <Information> <Info type="country_code">GB</Info> <Info type="road_class">tertiary</Info> </Information> <StartPoint> <Lat>51.44847</Lat> <Lon>-0.97307</Lon> </StartPoint> <EndPoint> <Lat>51.44836</Lat> <Lon>-0.97302</Lon> </EndPoint> </Step> ... <Step> <Instruction>Arrive at your destination</Instruction> <RoadName /> <RoadNumber /> <Distance> <Miles>0.01</Miles> <KM>0.02</KM> </Distance> <Duration> <Minutes>0</Minutes> </Duration> <Bearing /> <Information /> <StartPoint> <Lat>51.45448</Lat> <Lon>-0.97037</Lon> </StartPoint> <EndPoint> <Lat>51.45448</Lat> <Lon>-0.97037</Lon> </EndPoint> </Step> </Steps> </Stage> </Stages> <Vector>-97290,5144850,-17,-3,5,-11,123,25,18,11,19,37,17,19,39,20,91,40,52,19,136,17,78,12,12
,8,2,6,-13,31,-73,122,-24,46,-6,45,-9,45,-7,24,-37,22,-117,50,-5,2,-23,1,-5,4,-3,6,-13,-2</
Vector> <Copyright>Powered by deCarta</Copyright> <Disclaimer>http://clients.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://clients.multimap.com/API" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://clients.multimap.com/API http://clients.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".
|
<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.
|
<StartPoint> | The StartPoint element refers to the coordinate location in latitude and longitude
at the beginning of each step in the route.
|
<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. |
<EndPoint> | The EndPoint element refers to the coordinate location in latitude and longitude
at the end of each step in the route.
|
<Duration> | The Duration element refers
to the total duration of the current stage of the journey, which in this example is measured in minutes.The Distance element refers to the total distance of the current stage of the journey,
which in this example is measured both in miles and kilometers.The Bounds element refers to the rectangular area defined by two points, north-east and south-west. |
<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.The RoadNumber element refers to the number of the road.The Distance element refers to the total distance of the current step of the journey, which in this example is measured both in miles and kilometers.The Duration element refers to the total duration of the current step of the journey, which in this example is measured in minutes.
|
<Bearing>E</Bearing>
| The Bearing element refers
to the direction of the route.
|
</Steps> | The Steps, Stage
and Stages elements close here.
|
<Vector>-97290,5144850,-17,-3,5,-11,123,25,18,11,19,37,17,19,39,20,91,40,52,19,136,17,78,12,12,8,2,6,-13,31,-73,122,-24,46,-6,45,-9,45,-7,24,-37,22,-117,50,-5,2,-23,1,-5,4,-3,6,-13,-2</Vector>
| 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://clients.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://clients.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://clients.multimap.com/API" xmlns:xsi="http://www.w3.org/2001/XMLSchema-
instance" xsi:schemaLocation="http://clients.multimap.com/API http://clients.multimap.com/Schema
/route_1.2.xsd" key="DC,-0.23816:51.59894;-0.10845:51.51453;-0.20235:51.65282,0" reverseKey="
DC,-0.20235:51.65282;-0.10845:51.51453;-0.23816:51.59894,0"> <Duration> <Hours>1</Hours> <Minutes>6</Minutes> </Duration> <Distance> <Miles>38.67</Miles> <KM>62.23</KM> </Distance> <Bounds> <NorthEast> <Lat>51.67234</Lat> <Lon>-0.10838</Lon> </NorthEast> <SouthWest> <Lat>51.51310</Lat> <Lon>-0.37137</Lon> </SouthWest> </Bounds> <Stages> <Stage id="1" stepCount="24" summary="M1 > A1 (Great North Way) > A400 (Junction Road)
> A4200 (Eversholt Street)" mode="driving"> <StartAddress> <PostalCode>NW9 5LL</PostalCode> <DisplayName>NW9 5LL</DisplayName> <CountryCode>GB</CountryCode> </StartAddress> <StartPoint> <Lat>51.59917</Lat> <Lon>-0.23658</Lon> </StartPoint> <EndAddress> <PostalCode>EC4A 2DY</PostalCode> <DisplayName>EC4A 2DY</DisplayName> <CountryCode>GB</CountryCode> </EndAddress> <EndPoint> <Lat>51.51423</Lat> <Lon>-0.10838</Lon> </EndPoint> <Duration> <Minutes>38</Minutes> </Duration> <Distance> <Miles>26.92</Miles> <KM>43.32</KM> </Distance> <Bounds> <NorthEast /> <SouthWest /> </Bounds> <Steps> <Step> <Instruction>Depart on</Instruction> <RoadName /> <RoadNumber>M1</RoadNumber> <Distance> <Miles>8.17</Miles> <KM>13.15</KM> </Distance> <Duration> <Minutes>8</Minutes> </Duration> <Bearing>N</Bearing> <Information> <Info type="country_code">GB</Info> <Info type="road_class">primary</Info> </Information> <StartPoint> <Lat>51.59917</Lat> <Lon>-0.23658</Lon> </StartPoint> <EndPoint> <Lat>51.66929</Lat> <Lon>-0.36447</Lon> </EndPoint> </Step> ... <Step> <Instruction>Turn left onto</Instruction> <RoadName>Aldwych</RoadName> <RoadNumber>A4</RoadNumber> <Distance> <Miles>0.10</Miles> <KM>0.16</KM> </Distance> <Duration> <Minutes>0</Minutes> </Duration> <Bearing>E</Bearing> <TurnDirection>L</TurnDirection> <Information> <Info type="country_code">GB</Info> <Info type="road_class">secondary</Info> <Info type="london_congestion_charge">within</Info> </Information> <StartPoint> <Lat>51.51335</Lat> <Lon>-0.11750</Lon> </StartPoint> <EndPoint> <Lat>51.51310</Lat> <Lon>-0.11522</Lon> </EndPoint> </Step> ... <Step> <Instruction>Arrive at your destination</Instruction> <RoadName /> <RoadNumber /> <Distance> <Miles>0.01</Miles> <KM>0.02</KM> </Distance> <Duration> <Minutes>0</Minutes> </Duration> <Bearing /> <Information /> <StartPoint> <Lat>51.65301</Lat> <Lon>-0.20234</Lon> </StartPoint> <EndPoint> <Lat>51.65301</Lat> <Lon>-0.20234</Lon> </EndPoint> </Step> </Steps> </Stage> </Stages> <Vector>-23816,5159894,158,23,-3,9,-12,26,-25,58,-39,65,-13,23,-8,12,-11,17,-9,14,-3,5,-6,8,
-19,30,-110,138,-45,47,-91,96,-38,33,-112,119,-26,27,-69,70,-183,187,-75,77,-76,77,-288,294,
-30,31,-5,5...2,-23,2,-35,3,-13,1,-181,1,-1,-19</Vector> <Copyright>Powered by deCarta</Copyright> <Disclaimer>http://clients.multimap.com/static/route_disclaimer.htm</Disclaimer> </Route>
In response to a request for a route between two locations in Great Britain with multiple intermediate 'via' points:
http://clients.multimap.com/API/route/1.2/[api_key] ?qs_1=ec1n2ns&qs_2=ct27rs&qs_3=w1a1aa&qs_4=hitchin
<?xml version="1.0" encoding="UTF-8" ?> <Route xmlns="http://clients.multimap.com/API" xmlns:xsi="http://www.w3.org/2001/XMLSchema-
instance" xsi:schemaLocation="http://clients.multimap.com/API http://clients.multimap.com/Schema
/route_1.2.xsd" key="DC,-0.11102:51.51842;1.07550:51.28544;-0.14377:51.51856;-0.26667:
51.95000,0" reverseKey="DC,-0.26667:51.95000;-0.14377:51.51856;1.07550:51.28544;-0.11102:
51.51842,0"> <Duration> <Hours>3</Hours> <Minutes>32</Minutes> </Duration> <Distance> <Miles>163.10</Miles> <KM>262.48</KM> </Distance> <Bounds> <NorthEast> <Lat>51.97497</Lat> <Lon>1.07532</Lon> </NorthEast> <SouthWest> <Lat>51.28127</Lat> <Lon>-0.26966</Lon> </SouthWest> </Bounds> <Stages> <Stage id="1" stepCount="27" summary="A102 (Blackwall Tunnel Approach) > A2 (Rochester Way
Relief Road) > M2 > A2 (Boughton Bypass)" mode="driving"> <StartAddress> <PostalCode>EC1N 2NS</PostalCode> <DisplayName>EC1N 2NS</DisplayName> <CountryCode>GB</CountryCode> </StartAddress> <StartPoint> <Lat>51.51842</Lat> <Lon>-0.11069</Lon> </StartPoint> <EndAddress> <PostalCode>CT2 7RS</PostalCode> <DisplayName>CT2 7RS</DisplayName> <CountryCode>GB</CountryCode> </EndAddress> <EndPoint> <Lat>51.28551</Lat> <Lon>1.07532</Lon> </EndPoint> <Duration> <Hours>1</Hours> <Minutes>15</Minutes> </Duration> <Distance> <Miles>60.85</Miles> <KM>97.93</KM> </Distance> <Bounds> <NorthEast /> <SouthWest /> </Bounds> <Steps> <Step> <Instruction>Depart on</Instruction> <RoadName>Brooke Street</RoadName> <RoadNumber /> <Distance> <Miles>0.02</Miles> <KM>0.03</KM> </Distance> <Duration> <Minutes>0</Minutes> </Duration> <Bearing>S</Bearing> <Information> <Info type="country_code">GB</Info> <Info type="road_class">tertiary</Info> <Info type="london_congestion_charge">entering</Info> </Information> <StartPoint> <Lat>51.51842</Lat> <Lon>-0.11069</Lon> </StartPoint> <EndPoint> <Lat>51.51814</Lat> <Lon>-0.11069</Lon> </EndPoint> </Step> ... <Step> <Instruction>Continue onto</Instruction> <RoadName /> <RoadNumber>A1(M)</RoadNumber> <Distance> <Miles>13.54</Miles> <KM>21.79</KM> </Distance> <Duration> <Minutes>14</Minutes> </Duration> <Bearing>NE</Bearing> <Information> <Info type="country_code">GB</Info> <Info type="road_class">primary</Info> </Information> <StartPoint> <Lat>51.77626</Lat> <Lon>-0.22530</Lon> </StartPoint> <EndPoint> <Lat>51.95959</Lat> <Lon>-0.20800</Lon> </EndPoint> </Step> ... <Step> <Instruction>Arrive at your destination</Instruction> <RoadName /> <RoadNumber /> <Distance> <Miles>0.04</Miles> <KM>0.06</KM> </Distance> <Duration> <Minutes>0</Minutes> </Duration> <Bearing /> <Information /> <StartPoint> <Lat>51.95056</Lat> <Lon>-0.26653</Lon> </StartPoint> <EndPoint> <Lat>51.95056</Lat> <Lon>-0.26653</Lon> </EndPoint> </Step> </Steps> </Stage> </Stages> <Vector>-11102,5151842,33,0,0,-6,0,-22,-2,-11,-18,2,-10,8,-14,1,-21,3,-16,31,-3,5,-19,32,-24,
43,-25,43,-32,54,-29,...-191,-21,-2,-8,-13,-6,-11,1,-7,3,-4,5,-44,-7,-33,-3,-16,-2,-59,-7,-68,
-26,-47,-18,-15,-7,-25,-17,-13,-7,-1,-2,-2,-2,-3,-2,-20,-23,-14,-16,-26,-24,-79,-52,-134,-73,-29,
-13,-105,-37,-69,-24,1,-2,1,-2,0,-2,-1,-1,0,-2,-2,-2,-1,-1,12,-7,61,-10,240,-22,-14,-56</Vector> <Copyright>Powered by deCarta</Copyright> <Disclaimer>http://clients.multimap.com/static/route_disclaimer.htm</Disclaimer> </Route>
The Multimap API can now also include information about carbon emissions in the directions it returns for journeys by road; if you wish your service to contain this additional option, please contact your Multimap account manager.
In response to a request for details of carbon emissions for three custom types of vehicle, for a route between the European cities of Vienna and Bratislava (with the mode of transport set to "driving"):
http://clients.multimap.com/API/route/1.2/[api_key] ?qs_1=wien,at&qs_2=bratislava,sk&emissions=true&custom_value_1=35 &custom_unit_1=mpg_imp&custom_type_1=diesel&custom_name_1=CustomDieselCar_1 &custom_value_2=20&custom_unit_2=mpg&custom_type_2=diesel&custom_name_2=CustomDieselCar_2 &custom_value_3=20&custom_unit_3=lper100km&custom_type_3=gas&custom_name_3=CustomGasCar
<?xml version="1.0" encoding="UTF-8" ?> <Route xmlns="http://clients.multimap.com/API" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://clients.multimap.com/API http://clients.multimap.com/Schema/route_1.2.xsd"
key="DC,16.37274:48.20919;17.12970:48.15310,0" reverseKey="DC,17.12970:48.15310;16.37274:48.20919,0"> <Duration> <Minutes>58</Minutes> </Duration> <Distance> <Miles>50.44</Miles> <KM>81.18</KM> </Distance> <Bounds> <NorthEast> <Lat>48.21297</Lat> <Lon>17.13233</Lon> </NorthEast> <SouthWest> <Lat>48.02019</Lat> <Lon>16.37277</Lon> </SouthWest> </Bounds> <Emissions> <Emission type="small_gas_motorbike" mpg=&74.691" mpg_imp="89.700" lper100km="3.149"> <Value unit="lb">13.017</Value> <Value unit="kg">5.917</Value> <Emission type="medium_gas_motorbike" mpg=&58.037" mpg_imp="69.700" lper100km="4.053"> <Value unit="lb">16.767</Value> <Value unit="kg">7.621</Value> <Emission type="average_gas_motorbike" mpg=&51.043" mpg_imp="61.300" lper100km="4.608"> <Value unit="lb">19.064</Value> <Value unit="kg">8.666</Value> <Emission type="large_gas_motorbike" mpg=&42.383" mpg_imp="50.900" lper100km="5.550"> <Value unit="lb">22.959</Value> <Value unit="kg">10.436</Value> <Emission type="small_diesel_car" mpg=&41.051" mpg_imp="49.300" lper100km="5.730"> <Value unit="lb">26.910</Value> <Value unit="kg">12.232</Value> <Emission type="medium_diesel_car" mpg=&32.891" mpg_imp="39.500" lper100km="7.151"> <Value unit="lb">33.590</Value> <Value unit="kg">15.268</Value> <Emission type="average_diesel_car" mpg=31.309" mpg_imp="37.600" lper100km="7.513"> <Value unit="lb">35.277</Value> <Value unit="kg">16.035</Value> <Emission type="large_diesel_car" mpg=&23.481" mpg_imp="28.200" lper100km="10.017"> <Value unit="lb">47.050</Value> <Value unit="kg">21.387</Value> <Emission type="regular_bus"> <Value unit="lb">5.460</Value> <Value unit="kg">2.482</Value> <Emission type="long_haul_coach"> <Value unit="lb">3.274</Value> <Value unit="kg">1.488</Value> <Emission type="CustomDieselCar1" mpg=&29.144" mpg_imp="35.000" lper100km="8.071"> <Value unit="lb">38.916</Value> <Value unit="kg">17.689</Value> <Emission type="CustomDieselCar2" mpg=&20.000" mpg_imp="24.019" lper100km="11.761"> <Value unit="lb">56.707</Value> <Value unit="kg">25.776</Value> <Emission type="CustomGasCar" mpg=&11.761" mpg_imp="14.124" lper100km="20.000"> <Value unit="lb">82.150</Value> <Value unit="kg">37.341</Value> </Emissions> ...
| Code | Notes |
|---|---|
|
The Emissions element introduces a list of vehicle types.
In addition to the standard vehicles types, the XML response also contains details
of the custom vehicle types that were submitted
as input parameters in the URL. |
|
Each Emission element contains details of fuel consumption
for one standard or custom vehicle type.
The type attribute contains a description of the vehicle and the response also returns
details of that vehicle's fuel consumption
in miles per gallon (in US gallons), miles per gallon (in Imperial gallons) and liters per 100 kilometers.
Please note that you can can sort, filter and format the results in your list of Emission
elements using your own application(s).
|
|
The Value attribute contains the mass of fuel
that is calculated to be consumed by the vehicle
over the course of the entire journey. Values are given in pounds and kilograms. |
|
The Emission element closes here. |
|
The Emissions element list closes here. |
The locale parameter lets you create different versions of the Multimap API
that offer support in several different languages (where applicable),
by specifying the user's language and geographic area, for:
http://clients.multimap.com/API/route/1.2/[api_key]?locale=es-ES &street_1=Camino%20San%20Lazaro&city_1=Tenerife&countryCode_1=ES &street_2=Calle%20Luis%20Vivies&city_2=Tenerife&countryCode_2=ES
http://clients.multimap.com/API/route/1.2/[api_key]?locale=fr-FR &city_1=Fort-de-France&countryCode_1=MQ &city_2=Le%20Lorrain&countryCode_2=MQ
http://clients.multimap.com/API/route/1.2/[api_key]?locale=en-GB &street_1=15%20Oxford%20Street&city_1=London&countryCode_1=GB &street_2=Royal%20Crescent&city_2=Bath&countryCode_2=GB
Please follow this link to see a
full list of permissible values for the locale parameter.
In the event of a service failure or a failure to provide valid parameters, the Multimap API V1.2 web services return an error code. Some of these error codes are specific to a particular web service while some are common to all the three web services (Geocoding, Searching and Routing). Please see these Error Codes to know more about them.
In response to a route requested with search criteria that return no matches:
http://clients.multimap.com/API/route/1.2/[api_key] ?fieldname_1=id&value_1=notmatching&qs_2=RG1&countryCode_2=GB&mode=walking
<?xml version="1.0" encoding="UTF-8" ?> <Route xmlns="http://clients.multimap.com/API" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://clients.multimap.com/API http://clients.multimap.com/Schema/route_1.2.xsd"> <Error inputID="1" errorCode="MM_SEARCH_NO_MATCHES" action="search" /> </Route>
In response to a request for a route with search criteria that return multiple matches, an error document is returned:
http://clients.multimap.com/API/route/1.2/[api_key] ?fieldname_1=id&operator_1=lt&value_1=9&qs_2=RG1&countryCode_2=GB&mode=walking
<?xml version="1.0" encoding="UTF-8" ?> <Route xmlns="http://clients.multimap.com/API" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://clients.multimap.com/API http://clients.multimap.com/Schema/route_1.2.xsd"> <Error inputID="1" errorCode="MM_SEARCH_MULTIPLE_MATCHES" action="search"> <RecordSet dataSource="mm.clients.[datasource1]" totalRecordCount="8"> <Record counter="1"> <Fields> <Field name="client_id">AU01</Field> <Field name="name">Australian Museum</Field> <Field name="street">6 College Street</Field> <Field name="town">Sydney</Field> <Field name="pc">2010</Field> <Field name="state">NSW</Field> <Field name="country">AU</Field> <Field name="telephone">+612 9320 6000</Field> <Field name="fax" /> <Field name="url" /> <Field name="id">1</Field> <Field name="GeoQuality">2b</Field> <Field name="GeocodeDate">2007-04-05</Field> <Field name="GeocodeSource">AU0441</Field> </Fields> <Point> <Lat>-33.87530</Lat> <Lon>151.21240</Lon> </Point> </Record> <Record counter="2"> <Fields> <Field name="client_id">GB02</Field> <Field name="name">Bronte Parsonage Museum</Field> <Field name="street">Church Street</Field> <Field name="town">Haworth</Field> <Field name="pc">BD22 8DR</Field> <Field name="state" /> <Field name="country">GB</Field> <Field name="telephone" /> <Field name="fax" /> <Field name="url" /> <Field name="id">2</Field> <Field name="GeoQuality">4</Field> <Field name="GeocodeDate">2007-04-05</Field> <Field name="GeocodeSource">cp071</Field> </Fields> <Point> <Lat>53.83135</Lat> <Lon>-1.95656</Lon> </Point> </Record> <Record counter="3"> <Fields> <Field name="client_id">DE01</Field> <Field name="name">German Museum of Technology Berlin (GMTB)</Field> <Field name="street">Trebbiner Str. 9</Field> <Field name="town">Berlin</Field> <Field name="pc">10963</Field> <Field name="state" /> <Field name="country">DE</Field> <Field name="telephone" /> <Field name="fax" /> <Field name="url" /> <Field name="id">3</Field> <Field name="GeoQuality">1i</Field> <Field name="GeocodeDate">2007-04-05</Field> <Field name="GeocodeSource">DE06_1</Field> </Fields> <Point> <Lat>52.49865</Lat> <Lon>13.37640</Lon> </Point> </Record> ... </RecordSet> </Error> </Route>
In response to a route requested with an address that cannot be geocoded:
http://clients.multimap.com/API/route/1.2/[api_key] ?lat_1=51.5136&lon_1=0.1126&qs_1=EC4A2DY&countryCode_1=GB&qs_2=WC2A&countryCode_2=FT
<?xml version="1.0" encoding="UTF-8" ?> <Route xmlns="http://clients.multimap.com/API" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://clients.multimap.com/API http://clients.multimap.com/Schema/route_1.2.xsd"> <Error inputID="2" errorCode="MM_GEOCODE_NO_MATCHES" action="geocode" /> </Route>
In response to a route requested where the server is busy and returns an error code:
http://clients.multimap.com/API/route/1.2/[api_key] ?lat_1=51.4485&lon_1=-0.9729&qs_1=RG20AT&countryCode_1=GB
<?xml version="1.0" encoding="UTF-8" ?> <Error xmlns="http://clients.multimap.com/API" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://clients.multimap.com/API http://clients.multimap.com/Schema/error_1.2.xsd"> <ErrorCode>MM_ROUTE_ERROR_SERVER_BUSY</ErrorCode> <Explanation>The Multimap route service encountered an unexpected error whilst servicing your request, please try again.
If this problem persists please contact Multimap Customer Services.</Explanation> </Error>
In response to a route requested with identical start and end points:
http://clients.multimap.com/API/route/1.2/[api_key] ?qs_1=RG20AT&countryCode_1=GB&qs_2=RG20AT&countryCode_2=GB&mode=walking
<?xml version="1.0" encoding="UTF-8" ?> <Error xmlns="http://clients.multimap.com/API" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://clients.multimap.com/API http://clients.multimap.com/Schema/error_1.2.xsd"> <ErrorCode>MM_ROUTE_ERROR_START_END_POINTS_SAME</ErrorCode> <Explanation>The start and end points provided for the route were the same.</Explanation> </Error>
In response to a route requested with identical consecutive points:
http://clients.multimap.com/API/route/1.2/[api_key] ?qs_1=london,gb&qs_2=bristol,gb&qs_3=bristol,gb&qs_4=liverpool,gb
<?xml version="1.0" encoding="UTF-8" ?> <Error xmlns="http://clients.multimap.com/API" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://clients.multimap.com/API http://clients.multimap.com/Schema/error_1.2.xsd"> <ErrorCode>MM_ROUTE_ERROR_CONSECUTIVE_POINTS_SAME</ErrorCode> <Explanation>Two consecutive points provided for the route were the same.</Explanation> </Error>
In response to a route requested with identical 'via' points:
http://clients.multimap.com/API/route/1.2/[api_key] ?qs_1=RG20AT&countryCode_1=GB&qs_2=RG20AT&countryCode_2=GB
&mode=walking
<?xml version="1.0" encoding="UTF-8" ?> <Error xmlns="http://clients.multimap.com/API" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://clients.multimap.com/API http://clients.multimap.com/Schema/error_1.2.xsd"> <ErrorCode>MM_ROUTE_ERROR_START_END_POINTS_SAME</ErrorCode> <Explanation>The start and end points provided for the route were the same.</Explanation> </Error>
The Multimap Routing web service XML schema defines a set of rules to which an XML document must conform in order to be considered valid according to that schema.
Please see the Routing web service XML schema example at http://clients.multimap.com/Schema/route_1.2.xsd.
Please also see the Routing web services schema documentation at http://clients.multimap.com/Schema/docs/route_1.2.xsd.html.
Web Services Home >> Static Maps >> Geocoding >> Searching
If you require further help with your Multimap service implementation, additional Multimap services or general account enquiries, please contact Multimap:
| Sales: | +44 (0)20 7632 7800 |
| Customer Support: | +44 (0)20 7632 7777 |
| email: | mminform@microsoft.com |