Multimap API V1.2 Web Services Documentation - Static Maps

• Web Services Home
• Overview
• Basic Example
• Implementing Static Maps
• Displaying static maps using latitude and longitude
• Displaying static maps using addresses
• Displaying static maps using your own data
• Displaying a route on a static map
• Displaying local information on a static map
• Static map dimensions
• Panning and zooming
• Static map types
• Output formats
• Changing Local Language Settings
• Customizing Icons on Static Maps
• Exception - People's Republic of China
• Error Codes

Overview

http://clients.multimap.com/API/map/1.2/[api_key]?lat=38.89207&lon=-77.0362
&zoomFactor=15&width=400&height=400

<a href="http://www.multimap.com/about/terms_of_use/">Terms of use</a>

Top of page

General Parameters

The general parameters, their description and examples are as follows:

You can also control the static map type, filter your data, show static maps of earlier location-search results and overlay info boxes and markers on your static maps.

Top of page

Implementing Static Maps

Displaying static maps using latitude and longitude

Displaying static maps using addresses

You can specify an address to be shown on your static map using address input parameters:

Address input parameters

Here is an example of an embedded URL showing the location of Fleet Street in London, Great Britain:

http://clients.multimap.com/API/map/1.2/[api_key]?qs=Fleet%20Street,London&countryCode=GB

Terms of use

Multiple address results

When the result of a geocoding request returns more than one possible match, your static map's default behavior is to show the first alternative that it finds. If you wish to alter this behavior to show all possible matches as multiple locations on a single static map, please use the gcFirstAlt parameter. The default Boolean value of this parameter is "1" so, if you wish your static map to display all possible results, you should specify this parameter with the value "0".

Please note that you can also use the gcFirstAlt parameter to determine whether a result of a geocoding request is the only possible match or whether multiple matches exist.

Here is an example of an embedded URL showing all possible matches of "Clapham Road" in Great Britain:

http://clients.multimap.com/API/map/1.2/[api_key]
?street=Clapham%20Road&town=Clapham&countryCode=GB&gcFirstAlt=0

Terms of use

Please note that:

• you should encode any spaces between characters in an address string using the separator "+" or the combination "%20"; and
• you must identify each country by its unique two-character International Organization for Standardization (ISO) country code.

Displaying static maps using your own data

You can show one or more locations on your static map using addresses you have uploaded in your table of addresses using Client Zone. For details of uploading and managing your own data, please see the separate Implementation Guidelines documentation which is available via Client Zone or from your Multimap account manager.

Please note that, if your data includes addresses that are located within the People's Republic of China, special rules apply; for details, please see the separate section entitled Exception - People's Republic of China.

Here is an example of a URL searching for a location within your Multimap service's table of addresses whose "client_id" field matches the value "21641":

http://clients.multimap.com/API/map/1.2/[api_key]
?fieldname_1=client_id&operator_1=eq&value_1=21641

Terms of use

Here is another example of a URL searching for all locations within your Multimap service's table of addresses have have car parks:

http://clients.multimap.com/API/map/1.2/[api_key]?width=400&height=400
&fieldname_1=has_car_park&operator_1=eq&value_1=true

Multiple filters

You can add multiple filters to your URLs by specifying the logic parameter, with a value of "AND" or "OR", which applies to two or more filter conditions:

http://clients.multimap.com/API/map/1.2/[api_key]?width=400&height=400
&fieldname_1=town&operator_1=eq&value_1=boston
&fieldname_2=client_id&operator_2=eq&value_2=621&logic=OR

Search input parameters

Preview and Live Environments

The Multimap API allows you to upload your store data via Multimap's Client Zone extranet and test it in a preview environment before making the data live. To view your preview data on a web page similar to this one, specify

<script type="text/javascript" src="http://preview.multimap.com/API/maps/1.2/[api_key]">

instead of

<script type="text/javascript" src="http://www.multimap.com/API/maps/1.2/[api_key]">

in the <HEAD> section of your web page.

For further details of your preview and live environments, 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.

Displaying a route on a static map

You can display a route on your static map via a two-step process.

1. Request a route from the Multimap API Routing module and retrieve the route key from the XML response.
2. Include the route key within your static map request.

Here is an example of a URL displaying a single route in London, Great Britain on a static map:

http://clients.multimap.com/API/map/1.2/[api_key]
?routeKey=DC,-0.11102:51.51842;-0.14400:51.51638,0

Terms of use

Route input parameters

You can adjust the exact positions of the start and end icons on your static maps by using the XML configuration file that is described in the Markers section of this web page.

Here is an example of a URL showing a single route in Florida, US using routeColor and routeOpacity parameters:

http://clients.multimap.com/API/map/1.2/[api_key]
?routeKey=US,-80.28732:25.78210;-80.45884:25.07744,0
&width=400&height=400&routeColor=255,0,0&routeOpacity=1

Terms of use

Displaying local information on a static map

Multimap API V1.2 Static Maps support the optional Local Information module which allows you to display points of interest of various types within the bounds of a static map. For a list of all the types that are available, please contact your Multimap account manager.

Local Information parameters

Here is an example of a static map centered on the City of Westminster in London, Great Britain. The example displays local information markers for bank ATMs and parking spaces, where overlayLabel "ATM" denotes bank ATMs and "P" denotes parking spaces. The overlayCount parameter specifies the maximum number of markers to display for each of the data sources in the overlayDataSourcelist, mm.poi.global.general.atm and mm.poi.UK.premium.parking:

http://clients.multimap.com/API/map/1.2/[api_key]
?overlayCount=100,100&lat=51.50002&lon=-0.12618
&overlayDataSource=mm.poi.global.general.atm,mm.poi.UK.premium.parking
&zoomFactor=16&overlayLabel=ATM,P

Terms of use

Static map dimensions (width and height)

http://clients.multimap.com/API/map/1.2/[api_key]?lat=51.123&lon=-0.9911
&zoomFactor=15&width=400&height=400

http://clients.multimap.com/API/map/1.2/[api_key]?lat=38.89207&lon=-77.0362
&zoomFactor=15&width=500&height=300

From Constitution Avenue:

• Pan west
• Pan north-west
• Pan north
• Pan north-east
• Pan east
• Pan south-east
• Pan south
• Pan south-west
• Zoom in by one factor
• Zoom out by two factors

Terms of use

Static map types

http://clients.multimap.com/API/map/1.2/[api_key]?lat=51.123&lon=-0.9911
&zoomFactor=15&width=400&height=400&mapType=map

http://clients.multimap.com/API/map/1.2/[api_key]?lat=51.123&lon=-0.9911
&zoomFactor=15&width=400&height=400&mapType=aerial

Output formats

Changing Local Language Settings

Top of page

Customizing Icons on Static Maps

Markers

Markers are overlaid on a static map to highlight the coordinates, addresses and other locations that you have specified. You can show your own image on your static map by uploading the image via Client Zone (in PNG, JPG or GIF format), then specifying it as the source image for a marker on your static map.

Please note that the Multimap API supports marker files in PNG, JPG or GIF formats; if you do not specify a suffix as part of the file name, the Multimap API assumes a default format of PNG.

List of marker options

The parameters marker, label and opacity apply to all markers on the static map (including markers for geocode, search and route results). The existence of the parameters marker_n, label_n and opacity_n overwrites the values set in the parameters marker, label and opacity for the n-th coordinate lon_n and lat_n.

Please note that you should encode spaces between characters in any marker option string using either the separator "+" or the combination "%20".

Example showing markers

Here is an example of an embedded URL for a static map that uses custom markers to show two locations, one identified by coordinates and the other by an address:

http://clients.multimap.com/API/map/1.2/[api_key]?width=500&height=500&lat=51.5139&lon=-0.10147
&marker=myicon.png&label=hi&opacity=0.5
&street=Fleet%20Street&city=London&countryCode=GB

Terms of use

Disabling markers

If you wish, you can prevent your static maps from showing markers by specifying "none" as the value for any marker:

http://clients.multimap.com/API/map/1.2/[api_key]?width=500&height=500
&lat=51.5139&lon=-0.10147&marker=none
&street=Fleet%20Street&city=London&countryCode=GB

Setting a marker's value to "none" completely disables that marker, including any label that it has.

XML configuration file

In addition to the URL parameters for markers, there is also an XML configuration file which can be uploaded into Client Zone along with your marker icon(s).

Each configuration file has a name that corresponds to the icon to which it relates, but with the extension ".xml" so that, for example, an icon called "default.png" relates to a configuration file called "default.xml". The configuration file for the default marker looks like this:

<?xml version="1.0" encoding="utf-8"?>
<Marker 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/map_marker.xsd">
    <Icon>
        <AnchorPoint>
            <X>9</X>
            <Y>20</Y>
        </AnchorPoint>
    </Icon>
    <Label>
        <AnchorPoint>
            <X>10</X>
            <Y>9</Y>
        </AnchorPoint>
        <Alignment>Center</Alignment>
        <TextSize>9</TextSize>
    </Label>
</Marker>

XML configuration schema

The values in the AnchorPoint attribute of the Icon element are pixel coordinates: in the default example shown above, the top-left corner of the icon is nine pixels to the left and twenty pixels upwards from the coordinate marked. An additional property in this is the Alignment attribute of the Label element: if this is set to "Center", the text label is centered horizontally and vertically on the anchor; if it is not set, the label is placed with its first letter at the anchor point.

If no configuration file exists for a marker and no URL parameters have been specified, any instance of that marker that appears on a static map is centered horizontally and vertically over its location.

Please validate your XML configuration file against the schema which is located at http://clients.multimap.com/Schema/map_marker.xsd

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:

• 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.

Top of page

Error Codes

In the event of a service failure or a failure to provide valid parameters, Multimap API V1.2 Static Maps return an error code.

Here is an example of a request which does not contain or could not be resolved to any valid coordinates (for example, if you specify "long" instead of "lon" in the input address):

http://clients.multimap.com/API/map/1.2/[api_key]?lat=-33.8684&long=151.20851

Instead of a static map, the output of this request is displayed as:

In order to view the corresponding XML output of a request, add output=xml anywhere in the request, for example:

http://clients.multimap.com/API/map/1.2/[api_key]?lat=-33.8684&long=151.20851&output=xml

Response

<?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_MAP_ERROR_NO_COORDINATES</ErrorCode> 
  <Explanation>We're sorry; you didn't specify any search criteria. Please try again.</Explanation> 
 </Error>

For a complete list of error messages, please see XML Error Codes.

Top of page

Browser Limitation on Static Map URL

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 correctly, the length of your URLs must remain within this limit. To ensure this, Multimap recommends that you do not specify more than 50 pairs of coordinates when creating a request for multiple locations.

Please note, also, that using long lists of paired coordinate parameters to show more than a few locations is inefficient and may affect the performance of your Multimap API service.

If you wish to show many locations on static maps on a regular basis, Multimap recommends that you upload your records into your table of addresses via Client Zone and display static maps using your own data.

(For details of uploading and managing your own data, please see the separate Implementation Guidelines documentation which is available via Client Zone or from your Multimap account manager.)

Multimap API V1.2 Static Maps XML Documentation

Web Services Home >> Geocoding >> Searching >> Routing

Top of page