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

Geocoding Overview

The Multimap Open 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 parameter 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 for the postcode EC4A 2DY in Great Britain:

http://developer.multimap.com/API/geocode/1.2/[api_key]?qs=EC4A2DY

Response 1

The URL shown above returns the following response:

<?xml version="1.0" encoding="UTF-8" ?> 
<Results 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/geocode_1.2.xsd" locationCount="1">
 <Location geocodeQuality="4" 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>


Example 2

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

http://developer.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://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/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

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://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/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 address 31, St James Avenue, Suite 850, Boston MA 02116, United States:

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

Response 3

The URL shown above returns the following response:

<?xml version="1.0" encoding="UTF-8" ?> 
<Results 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/geocode_1.2.xsd" locationCount="1">
 <Location geocodeQuality="4">
  <Address>
  <Areas />
   <PostalCode>02116</PostalCode>
   <DisplayName>02116</DisplayName> 
   <CountryCode>US</CountryCode> 
  </Address>
  <Point>
   <Lat>42.35019</Lat> 
   <Lon>-71.07575</Lon>
  </Point>
 </Location>
</Results>

Top of page

Top of page

Error Codes

In the event of a service failure or a failure to provide valid parameters, the Multimap Open 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 web services (Geocoding 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://developer.multimap.com/API/geocode/[api_key]?city=Sutton&countryCode=GB

Error Response 1

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

Error Example 3

In response to an address with missing parameters:

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

Error Response 3

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

Geocoding Open 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://developer.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 >> Routing

Top of page

Further Help

If you require further help with your Multimap Open API implementation, please visit the Multimap Developer Forums.

For Open API news, announcements and other information, please see our blog.

For enquiries about further Multimap services, please contact the Multimap Sales team:

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