Multimap API V1.2 Web Services Implementation Guidelines

The Multimap API V1.2 web services enable you to add location-based features to your applications, including geocoding, spatial searching and routing capabilities. This API can be accessed over the Internet and executed on a remote system hosting the requested services. All responses from web services are represented in XML. Web services require XML-based technology to transport and transform data between programs and databases. Multimap API web services consist of three constituent services: Geocoding, Searching and Routing. Before you start building your application, we advise you to first read a separate document on maintaining service availability for XML services.

In general, a web service is a software system designed to support machine-to-machine interaction over a network.

The Multimap API web services now incorporate the Static Maps feature, which allows you to add static maps as well as (or instead of) draggable maps to your applications. For example, you may wish to implement a static map as a "fallback" for those users whose browsers do not support JavaScript: for details, please see the Multimap API V1.2 Static Maps "Fallback" JavaScript documentation. If you wish to display static maps on your web pages initially and allow each user to "upgrade" to a draggable map on demand, please see the Multimap API V1.2 Static Maps web service documentation.

Getting Started

Web Services Modules

• Static Maps
• Overview
• Basic Example
• Implementing Static Maps
• Customizing Icons
• Exception - People's Republic of China
• Error Codes
• API Web Services XML Schema
• Geocoding
• Overview
• Parameters
• Examples
• Exception - People's Republic of China
• Error Codes
• API Web Services XML Schema
• Searching
• Overview
• Parameters
• Operators
• Examples
• Exception - People's Republic of China
• Error Codes
• Using Search along a Route
• API Web Services XML Schema
• Routing
• Overview
• Parameters
• Examples
• Carbon Emissions
• Error Codes
• API Web Services XML Schema

Getting Started

How Web Services Work

All web services start with a request being created. The source can be a browser or an application. The request is sent as a query string formatted into an XML document and transmitted across the Internet to a web server. The server has a process that works on a given port (usually port 80, the HTTP port). When a request arrives, the query is parsed to determine which components need to be instantiated and what methods are called. Finally, the result is bundled back up into an XML document and sent back to the application that invoked it.

Request Format

REST

The Multimap API V1.2 web services use the REST (Representational State Transfer) request format, which can be an HTTP GET or POST action. The simplest REST format is an HTTP GET request where the URL specifies the parameters to be represented. On the other hand, in an HTTP POST request the parameters are included in the body of the request itself rather than within the URL.

The Multimap API web services support both the HTTP GET and POST requests. However, we recommend that you use a POST request only if the maximum number of characters in the URL exceeds 2083. Some of the most commonly-used operating systems and browsers do not support URLs of more than 2083 characters. In order to display static maps inline within an HTML document correctly, please ensure that the length of your URLs remains within this limit.

The base URL for a REST request is:

http://clients.multimap.com/API/[module]/1.2/[api_key]

[module] should be replaced with the Multimap API web services module to which the request is being sent, such as the Geocoding, Searching or Routing module.

[api_key] should be replaced with the Multimap API web services API key provided by your Multimap account manager.

REST requests receive an XML response.

Response Format

XML

By default, the Multimap API web services return an XML response. The XML format that is returned depends on the module that has been called, such as the Geocoding, Searching or Routing module, but common elements between each element are defined in the same way across all modules. These common elements are described in the following sections.

Address type

The common Address type is used to present a structured address, for example:

<Address>
  <Street>150 Holborn</Street>
  <Areas>
    <Area>Camden</Area>
    <Area>London</Area>
  </Areas>
  <DisplayName>150 Holborn, London</DisplayName>
  <PostalCode>EC1N 2NS</PostalCode>
  <CountryCode>GB</CountryCode>
</Address>

Point type

The common Point type is used to define a coordinate location in decimal degrees of latitude and longitude, for example:

<Point>
  <Lat>51.51842</Lat>
  <Lon>-0.1112</Lon>
</Point>

Location type

The common Location type wraps a related Address and Point, and optionally also contains geocoding match quality, suggested zoom factor and/or geocoding score, for example:

<Location geocodeQuality="4" zoomFactor="15">
 <Address>
    <Street>150 Holborn</Street>
    <Areas>
      <Area>Camden</Area>
      <Area>London</Area>
    </Areas>
    <DisplayName>150 Holborn, London</DisplayName>
    <PostalCode>EC1N 2NS</PostalCode>
    <CountryCode>GB</CountryCode>
 </Address>
   <Point>
     <Lat>51.51842</Lat>
     <Lon>-0.1112</Lon>
   </Point>
</Location>

Distance type

The common Distance type is used to represent a distance in miles and kilometers:

<Distance>
   <Miles>1.90</Miles>
   <KM>3.06</KM>
</Distance>

Duration type

The common Duration type is used to represent time durations:

 <Duration>
   <Days>1</Days>
   <Hours>3</Hours>
   <Minutes>46</Minutes>
 </Duration>

Bounds type

The common Bounds type is used to represent a rectangular area defined by two Point types, the most south-westerly and north-easterly:

 <Bounds>
   <NorthEast>
     <Lat>53.47944</Lat>
     <Lon>-0.11102</Lon>
   </NorthEast>
   <SouthWest>
     <Lat>51.51763</Lat>
     <Lon>-2.41878</Lon>
   </SouthWest>
 </Bounds>

Multimap API V1.2 Documentation main page >> Static Maps >> Geocoding >> Searching >> Routing

Further Help

If you require further help with your Multimap API V1.2 web services, please contact the Multimap Customer Support team:

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