Multimap API V1.2 : Web Services Documentation

The Multimap API V1.2 Geocoding web service module allows you to find the specific latitude and longitude for an address. The address can be provided as either a single string or a structured set of parameters.

Geocoding Parameters

The Geocoding web service parameters, description and values are as follows:

Parameter	Description	Valid values	Mandatory
`city`	This parameter refers to the city, town or suburb for the input address.	String	No
`countryCode`	This parameter refers to the two-letter ISO country code for the input address.	Two-letter ISO country code	No
`postalCode`	This parameter refers to the postal code for the input address.	String	No
`qs`	This is a 'quick search' parameter which refers to an address or place name entered as a single string, preferably with `countryCode`.	String	No
`region`	This parameter refers to the region for the input address; it is a synonym for `state`.	String	No
`state`	This parameter refers to the state for the input address; it is a synonym for `region`.	String	No
`street`	This parameter refers to the street, optionally including a building number, for the input address.	String	No
`ZIP`	This parameter refers to the ZIP code for the input address; it is a synonym for `postalCode`.	String	No

For details of permissible values for countries, states and regions, please see Multimap's Countries and States web page.

Geocoding Examples

Example 1

Here is a simple example of a URL requesting latitude and longitude details by performing a 'quick search' for the postcode EC4A 2DY in London, Great Britain:

http://clients.multimap.com/API/geocode/1.2/[api_key]?qs=EC4A2DY&city=London&countryCode=GB

Response 1

<?xml version="1.0" encoding="UTF-8" ?> 
<Results 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/geocode_1.2.xsd" locationCount="1">
 <Location geocodeQuality="4" geocodeScore="1.000" zoomFactor="15">
  <Address>
   <PostalCode>EC4A 2DY</PostalCode> 
   <DisplayName>EC4A 2DY</DisplayName> 
  </Address>
  <Point>
   <Lat>51.51453</Lat> 
   <Lon>-0.10845</Lon> 
  </Point>
 </Location>
</Results>

Example 2

Here is an example of a URL requesting latitude and longitude details for the address 15, Oxford Street, London, Great Britain:

http://clients.multimap.com/API/geocode/1.2/[api_key]?street=15%20Oxford%20Street
&city=London&countryCode=GB

Response 2

<?xml version="1.0" encoding="UTF-8" ?>
<Results 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/geocode_1.2.xsd" locationCount="1">
 <Location geocodeQuality="1">
  <Address>
    <Street>Oxford Street</Street>
   <Areas>
    <Area>LONDON</Area> 
   </Areas>
    <PostalCode>W1</PostalCode>
    <DisplayName>Oxford Street, LONDON, W1</DisplayName> 
    <CountryCode>GB</CountryCode> 
  </Address>
  <Point>
    <Lat>51452</Lat>
    <Lon>14839</Lon>
  </Point>
 </Location>
</Results>

Notes on Response 2

Example 3

Here is another example of a URL requesting latitude and longitude details for the full address 31, St James Avenue, Suite 850, Boston MA 02116, United States:

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.
`<Results 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/geocode_1.2.xsd" locationCount="1">`	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 `locationCount` element refers to the total number of locations identified by the input address.
`<Location geocodeQuality="1"> <Address> <Street>Oxford Street</Street> <Areas> <Area>LONDON</Area> </Areas> <PostalCode>W1</PostalCode> <DisplayName>Oxford Street, LONDON, W1</DisplayName> <CountryCode>GB</CountryCode> </Address>`	The `Location` element refers to the location to be geocoded. The `geocodeQuality` element refers to the Geocoding precision. For each record, the Geocoding precision is indicated by a set of pre-defined GeoQuality codes. The `Address` element refers to the input address to be geocoded. It comprises elements such as `Street`, `Area`, `postalCode`, `displayName` and `countryCode`. The `Street` element refers to the street name of the input address. The `PostalCode` element refers to the postal code of the input address. The `CountryCode` element refers to the two-letter ISO country code for the input address.
`<Point> <Lat>51.51452</Lat> <Lon>-0.14839</Lon> </Point> </Location> </Results>`	The `Point` element returns the latitude and longitude points of the input address.

http://clients.multimap.com/API/geocode/1.2/[api_key]?
street=31%20St%20James%20Avenue,%20Suite%20850&ZIP=02116
&state=MA&city=Boston&countryCode=US

Response 3

<?xml version="1.0" encoding="UTF-8" ?> 
<Results 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/geocode_1.2.xsd" locationCount="1">
 <Location geocodeQuality="1" geocodeScore="0.850" zoomFactor="16">
  <Address>
   <Street>31 Saint James Ave Ste 850</Street> 
  <Areas>
   <Area>Boston</Area> 
  </Areas>
   <State>MA</State> 
   <PostalCode>02116-4108</PostalCode> 
   <DisplayName>31 Saint James Ave Ste 850, Boston, MA 02116-4108</DisplayName> 
   <CountryCode>US</CountryCode> 
  </Address>
  <Point>
   <Lat>42.35103</Lat> 
   <Lon>-71.07037</Lon> 
  </Point>
 </Location>
</Results>

Exception - People's Republic of China

If you have a Multimap service that includes records for stores located in the People's Republic of China (PRC) that have been geocoded to street level, legal restrictions mean that Multimap cannot expose those stores' coordinates either to you or to your users by any means, whether via Client Zone, in downloaded files or in any customer-designed interface. Specifically, this means that you:

must host all your records for stores located in the PRC on Multimap's Chinese servers and host all your other store records on Multimap's global servers;
cannot host any records for stores located in the PRC on Multimap's global servers or host other store records on Multimap's Chinese servers;
must maintain separate Multimap service accounts if you wish to cover locations both inside and outside the PRC; and
cannot have your Multimap service(s) integrate records for stores located in the PRC with records for stores located elsewhere.

Street-level geocoding in the PRC is currently available via the Multimap API only. For further details of how this restriction affects your Multimap service(s), please see Multimap's separate Geocoding and Data Management in Client Zone: Implementation Guidelines documentation which is available via Client Zone or from your Multimap account manager.

Error Codes

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 three web services (Geocoding, Searching and Routing). Please see these Error Codes to know more about them.

Error Example 1

In response to a geocode request with an ambiguous address, the result returns multiple latitude and longitude point details:

http://clients.multimap.com/API/geocode/[api_key]?city=Sutton&countryCode=GB

Error Response 1

<?xml version="1.0" encoding="UTF-8" ?> 
<Results 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/geocode_1.0.xsd" locationCount="15">
 <Location geocodeQuality="3">
  <Address>
   <Areas>
    <Area>Sutton</Area> 
    <Area>South Yorkshire</Area> 
   </Areas>
    <DisplayName>Sutton, South Yorkshire</DisplayName> 
    <CountryCode>GB</CountryCode> 
  </Address>
  <Point>
   <Lat>53.60620</Lat> 
   <Lon>-1.16940</Lon> 
  </Point>
 </Location>
 <Location geocodeQuality="3">
  <Address>
   <Areas>
    <Area>Sutton</Area> 
    <Area>Nottinghamshire</Area> 
   </Areas>
    <DisplayName>Sutton, Nottinghamshire</DisplayName> 
    <CountryCode>GB</CountryCode> 
  </Address>
  <Point>
   <Lat>53.35540</Lat> 
   <Lon>-0.98740</Lon> 
  </Point>
 </Location>
 <Location geocodeQuality="3">
  <Address>
   <Areas>
    <Area>Sutton</Area> 
    <Area>Lincolnshire</Area> 
   </Areas>
    <DisplayName>Sutton, Lincolnshire</DisplayName> 
    <CountryCode>GB</CountryCode> 
  </Address>
  <Point>
   <Lat>53.06200</Lat> 
   <Lon>-0.69100</Lon> 
  </Point>
 </Location>
 <Location geocodeQuality="3">
  <Address>
   <Areas>
    <Area>Sutton</Area> 
    <Area>Nottinghamshire</Area> 
   </Areas>
    <DisplayName>Sutton, Nottinghamshire</DisplayName> 
    <CountryCode>GB</CountryCode> 
  </Address>
  <Point>
   <Lat>52.93070</Lat> 
   <Lon>-0.86700</Lon> 
  </Point>
 </Location>
 <Location geocodeQuality="3">
  <Address>
   <Areas>
    <Area>Sutton</Area> 
    <Area>Shropshire</Area> 
   </Areas>
    <DisplayName>Sutton, Shropshire</DisplayName> 
    <CountryCode>GB</CountryCode> 
  </Address>
  <Point>
   <Lat>52.88320</Lat> 
   <Lon>-2.49800</Lon> 
  </Point>
 </Location>
 <Location geocodeQuality="3">
  <Address>
   <Areas>
    <Area>Sutton</Area> 
    <Area>Norfolk</Area> 
   </Areas>
    <DisplayName>Sutton, Norfolk</DisplayName> 
    <CountryCode>GB</CountryCode> 
  </Address>
  <Point>
   <Lat>52.75970</Lat> 
   <Lon>1.53560</Lon> 
  </Point>
 </Location>
 <Location geocodeQuality="3">
  <Address>
   <Areas>
    <Area>Sutton</Area> 
    <Area>Staffordshire</Area> 
   </Areas>
    <DisplayName>Sutton, Staffordshire</DisplayName> 
    <CountryCode>GB</CountryCode> 
  </Address>
  <Point>
   <Lat>52.79500</Lat> 
   <Lon>-2.35170</Lon> 
  </Point>
 </Location>
 <Location geocodeQuality="3">
  <Address>
   <Areas>
    <Area>Sutton</Area> 
    <Area>Shropshire</Area> 
   </Areas>
    <DisplayName>Sutton, Shropshire</DisplayName> 
    <CountryCode>GB</CountryCode> 
  </Address>
  <Point>
   <Lat>52.69000</Lat> 
   <Lon>-2.73340</Lon> 
  </Point>
 </Location>
 <Location geocodeQuality="3">
  <Address>
   <Areas>
    <Area>Sutton</Area> 
    <Area>Peterborough</Area> 
   </Areas>
    <DisplayName>Sutton, Peterborough</DisplayName> 
    <CountryCode>GB</CountryCode> 
  </Address>
  <Point>
   <Lat>52.57330</Lat> 
   <Lon>-0.38210</Lon> 
  </Point>
 </Location>
 <Location geocodeQuality="3">
  <Address>
   <Areas>
    <Area>Sutton</Area> 
    <Area>Shropshire</Area> 
   </Areas>
    <DisplayName>Sutton, Shropshire</DisplayName> 
    <CountryCode>GB</CountryCode> 
  </Address>
  <Point>
   <Lat>52.47830</Lat> 
   <Lon>-2.40210</Lon> 
  </Point>
 </Location>
 <Location geocodeQuality="3">
  <Address>
   <Areas>
    <Area>Sutton</Area> 
    <Area>Cambridgeshire</Area> 
   </Areas>
    <DisplayName>Sutton, Cambridgeshire</DisplayName> 
    <CountryCode>GB</CountryCode> 
  </Address>
  <Point>
   <Lat>52.38780</Lat> 
   <Lon>0.11650</Lon> 
  </Point>
 </Location>
 <Location geocodeQuality="3">
  <Address>
   <Areas>
    <Area>Sutton</Area> 
    <Area>Bedfordshire</Area> 
   </Areas>
    <DisplayName>Sutton, Bedfordshire</DisplayName> 
    <CountryCode>GB</CountryCode> 
  </Address>
  <Point>
   <Lat>52.11000</Lat> 
   <Lon>-0.22560</Lon> 
  </Point>
 </Location>
 <Location geocodeQuality="3">
  <Address>
   <Areas>
    <Area>Sutton</Area> 
    <Area>Suffolk</Area> 
   </Areas>
    <DisplayName>Sutton, Suffolk</DisplayName> 
    <CountryCode>GB</CountryCode> 
  </Address>
  <Point>
   <Lat>52.06610</Lat> 
   <Lon>1.36530</Lon> 
  </Point>
 </Location>
 <Location geocodeQuality="3">
  <Address>
  <Areas>
   <Area>Sutton</Area> 
   <Area>Pembrokeshire</Area> 
  </Areas>
   <DisplayName>Sutton, Pembrokeshire</DisplayName> 
   <CountryCode>GB</CountryCode> 
  </Address>
  <Point>
   <Lat>51.80150</Lat> 
   <Lon>-5.03510</Lon> 
  </Point>
 </Location>
 <Location geocodeQuality="3">
  <Address>
   <Areas>
    <Area>Sutton</Area> 
    <Area>Oxfordshire</Area> 
   </Areas>
    <DisplayName>Sutton, Oxfordshire</DisplayName> 
    <CountryCode>GB</CountryCode> 
  </Address>
  <Point>
   <Lat>51.75540</Lat> 
   <Lon>-1.38650</Lon> 
  </Point>
 </Location>
</Results>

Error Example 2

http://clients.multimap.com/API/geocode/1.2/[api_key]?street=1eetStrt&city=London&countryCode=WW

Error Response 2

<?xml version="1.0" encoding="UTF-8" ?> 
<Results 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/geocode_1.2.xsd" 
errorCode="MM_GEOCODE_NO_MATCHES" locationCount="0" />

Error Example 3

http://clients.multimap.com/API/geocode/1.2/[api_key]?countryCode=GB

Error Response 3

<?xml version="1.0" encoding="UTF-8" ?> 
<Results 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/geocode_1.2.xsd" 
errorCode="MM_GEOCODE_REQUIRED_PARAMETERS_MISSING" locationCount="0" />

Geocoding API Web Service XML Schema

The Multimap Geocoding 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.

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

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

Multimap API V1.2 Web Services Documentation - Geocoding

Geocoding Overview