Multimap logo Multimap API V1.2 Web Services Documentation - Geocoding

Geocoding Overview

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.

Multiple-input geocoding *new*

The Multimap API now allows you to geocode multiple addresses in a single geocoding request in order to show up to 20 locations on a single map. The feature is currently available only for postcodes in Great Britain.

Geocoding Parameters

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

ParameterDescriptionValid valuesMandatory
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
postalCode_1, postalCode_2, etc. 		This parameter refers to the postal (or ZIP) code for the input address or, in the case of multiple-input geocoding, to a comma-separated list of postal codes. 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

The URL shown above returns the following response:

<?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

The URL shown above returns the following response:

<?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>51.51452</Lat>
    <Lon>-0.14839</Lon>
  </Point>
 </Location>
</Results>

Notes on Response 2

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.


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:

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

The URL shown above returns the following response:

<?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>

Example 4

Here is an example of a URL requesting latitude and longitude details for three full or partial postcodes in London, Great Britain, in a single geocoding request:

http://clients.multimap.com/API/geocode/1.2/[api_key]?
postalCode_1=ec4a2dy&postalCode_2=sw1e5jl&postalCode_3=wc2&countryCode_1=GB&countryCode_2=GB&countryCode_3=GB

Response 4

The URL shown above returns the following response:


  <?xml version="1.0" encoding="UTF-8" ?> 
- <ResultSets 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="3">
- <Results xmlns="http://clients.multimap.com/API" locationCount="1" counter="1">
- <Location geocodeQuality="4" geocodeScore="1.000" zoomFactor="16">
- <Address>
  <PostalCode>EC4A 2DY</PostalCode> 
  <DisplayName>EC4A 2DY</DisplayName> 
  <CountryCode>GB</CountryCode> 
  </Address>
- <Point>
  <Lat>51.51453</Lat> 
  <Lon>-0.10845</Lon> 
  </Point>
  </Location>
  </Results>
- <Results xmlns="http://clients.multimap.com/API" locationCount="1" counter="2">
- <Location geocodeQuality="4" geocodeScore="1.000" zoomFactor="16">
- <Address>
  <PostalCode>SW1E 5JL</PostalCode> 
  <DisplayName>SW1E 5JL</DisplayName> 
  <CountryCode>GB</CountryCode> 
  </Address>
- <Point>
  <Lat>51.49725</Lat> 
  <Lon>-0.14004</Lon> 
  </Point>
  </Location>
  </Results>
- <Results xmlns="http://clients.multimap.com/API" locationCount="1" counter="3">
- <Location geocodeQuality="4a" geocodeScore="1.000" zoomFactor="16">
- <Address>
  <PostalCode>WC2</PostalCode> 
  <DisplayName>WC2</DisplayName> 
  <CountryCode>GB</CountryCode> 
  </Address>
- <Point>
  <Lat>51.51307</Lat> 
  <Lon>-0.12167</Lon> 
  </Point>
  </Location>
  </Results>
  </ResultSets>

Top of page

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:

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.

Top of page

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

In response to an address that could not be geocoded:

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

In response to an address with missing parameters:

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" />

Error Example 4

Here is an example of a URL requesting latitude and longitude details for three full or partial postcodes in London, Great Britain, in a single geocoding request, but where the final countryCode parameter is incorrect:

http://clients.multimap.com/API/geocode/1.2/[api_key]?
postalCode_1=ec4a2dy&postalCode_2=sw1e5jl&postalCode_3=wc2&countryCode_1=GB&countryCode_2=GB&countryCode_3=FR

Error Response 4

  <?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_GEOCODE_MULTIPLE_INPUTS_NOT_SUPPORTED</ErrorCode> 
  <Explanation>The geocode service does not currently support multiple inputs in the country requested.</Explanation> 
  </Error>

Top of page

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.

Please see the Geocoding web service XML schema example at http://clients.multimap.com/Schema/geocode_1.2.xsd.

Please also see the Geocoding web service schema documentation at http://www.multimap.com/Schema/docs/geocode_1.2.xsd.html.


Web Services Home >> Static Maps >> Searching >> Routing

Top of page

Further Help

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

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

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

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