Multimap Open API V1.2 Web Services Documentation - Static Maps
Multimap Open API V1.2 Web Services Documentation - Static MapsA static map is a simple image of a map, normally shown within a web page; it does not provide the same 'rich' features, such as dragging and smooth panning and zooming, that are found in the Multimap Open API V1.2 JavaScript applications. Static maps are often used to display maps to those users who do not have the required browser software to display maps based on the JavaScript Open API.
In addition to static maps, the Multimap Open API allows you to add draggable maps to your implementations. You may wish to display a static map as a "fallback" for those users whose browser configuration does not support the Multimap Open API. For details of how to do this, please see the Static Maps "Fallback" JavaScript example.
The Multimap Open API allows you to embed static maps in your own web pages. You can vary the map's appearance and behavior by means of several parameters.
You can use static maps to show:
However, please note that you can show only one of these feature types in any single request for a static map.
Here is an example of a URL for a basic example of a static map and the map that it generates. If you view this in your browser you should see a Multimap static map centered on Constitution Avenue, Washington, DC, USA at zoom factor 15:
http://developer.multimap.com/API/map/1.2/[api_key]?lat=38.89207&lon=-77.0362 &zoomFactor=15&width=400&height=400
In all the example URLs shown on this page, [api_key] should be replaced
with your own Open API key assigned by Multimap.
The maps and data used to provide this service represent copyrighted information, which is owned by Multimap's data partners. When implementing Multimap Open API Static Maps, you must display the link to Multimap's full Terms and Conditions of use near the map in your web pages: the URL for which is included in the code sample below:
<a href="http://clients.multimap.com/about/legal_and_copyright/">Terms of use</a>
The general parameters, their description and examples are as follows:
| Parameter Name | Description | Example |
|---|---|---|
bb |
This string specifies the bounding box for a search. | bb=-0.1426,51.5086; |
height |
This denotes the height in pixels of a static map. | height=400 |
lat, lat_2, etc. |
These denote one or more latitude coordinates. Please note that you should use the lat coordinate only when specifying a static map that shows a single location;
if you wish to show multiple locations, you must specify their coordinates using lat_1, lat_2, etc.
|
lat=42.29857 |
lon, lon_2, etc. |
These denote one or more longitude coordinates. Please note that you should use the lon coordinate only when specifying a static map that shows a single location;
if you wish to show multiple locations, you must specify their coordinates using lon_1, lon_2, etc. |
lon=-71.16817 |
locale |
This determines the appearance of labels and other text on a static map, based on settings for language and geographic area. | locale=de-DE |
mapType |
This controls whether your Multimap service shows a static map or a static aerial photograph. | mapType=Map |
moveMap |
This comma-separated pair denotes the distances in pixels to move a static map east and north respectively. | moveMap=40.0 |
moveMapMeters |
This comma-separated pair denotes the distances in meters to move a static map east and north respectively. | moveMapMeters=-100,0 |
output |
This parameter determines the type or file format of the map or image that the Multimap Static Maps service returns. | output=png |
width |
This denotes the width in pixels of a static map. | width=400 |
zoom |
These 'delta parameters' denote the number of zoom factors to zoom a static map inwards (positive value) or outwards (negative value). | zoom=1 |
zoomFactor |
This number denotes the zoom factor at which the map appears. | zoomFactor=15 |
You can also control the static map type and show static maps of earlier location-search results.
You can specify one or more locations using coordinates of latitude and longitude:
You can specify a coordinate pair using a single parameter for each coordinate. All coordinate pairs are expressed in decimal degrees using the unprojected WGS84 coordinate system:
http://developer.multimap.com/API/map/1.2/[api_key] ?lat=51.123&lon=-0.9911&zoomFactor=15&width=400&height=400
A coordinate list consists of a series of coordinates as shown below; the name of each element must include an enumerated suffix. All coordinate pairs are expressed in decimal degrees using the unprojected WGS84 coordinate system:
http://developer.multimap.com/API/map/1.2/[api_key]? &lat_1=42.29857&lon_1=-71.16817&lat_2=42.40553&lon_2=-70.99651 &lat_3=42.87652&lon_3=-70.38762&width=400&height=400
Please note that maps whose URLs contain coordinates for more than one location are automatically scaled to show all their locations by default: there is no need to specify a zoomFactor parameter. If a zoomFactor parameter is specified in a URL showing multiple coordinates, some of the locations' markers might not be visible if they are located outside the view of the map.
You can specify an address to be shown on your map using address input parameters:
| Parameter Name | Description | Permissible Values | Example |
|---|---|---|---|
city |
This parameter refers to the city, town or suburb for the input address. | string | city=Boston |
countryCode |
This parameter refers to a two-letter ISO country code for the input address. If countryCode is not specified, it defaults to Great Britain. | two-letter ISO country code | countryCode=GB |
gcFirstAlt |
This parameter displays all possible matches as multiple locations on a single map. The default value of this parameter is "1" so, if you wish your map to display all possible results, you should specify this parameter with a value "0". | Boolean ("1" (default) or "0") | gcFirstAlt=0 |
postalCode |
This parameter refers to the postal code for the input address. | Any valid full or partial postal code | postalCode=EC4A2DY |
qs |
This parameter refers to an address or place name entered as a single string, preferable with countryCode. |
string | qs=EC4A2DY |
region |
This parameter refers to the region or local area for the input address. | string | region=England |
state |
This parameter refers to the state, province or territory for the input address. | string | state=MA |
street |
This parameter refers to street (optionally including a building name) for the input address. | string | street=Fleet%20Street |
ZIP |
The ZIP code for the input address; it is a synonym for postalCode. |
string | ZIP=02116 |
Here is an example of an embedded URL showing the location of Fleet Street in London, Great Britain:
http://developer.multimap.com/API/map/1.2/[api_key]?qs=Fleet%20Street,London&countryCode=GB
When the result of a geocoding request returns more than one possible match, your 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 map, please use the gcFirstAlt parameter. The default Boolean value of this parameter is 1 so, if you wish your 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://developer.multimap.com/API/map/1.2/[api_key] ?street=Clapham%20Road&town=Clapham&countryCode=GB&gcFirstAlt=0
Please note that:
| Parameter Name | Description | Permissible Values | Example |
|---|---|---|---|
routeColor |
This is a three- or six-digit hexadecimal code which determines the color in which the polyline or polygon representing a route appears on a map. | Any valid HTML hexadecimal color name | routeColor=0000FF |
routeEndLabel |
This label is displayed over the icon marking the end of the route. | Any string of characters | routeEndLabel=Finish |
routeKey |
This is the unique route key that identifies a route from a previous enquiry. The COUNTER with this parameter should always start with 1, followed by 2 and so on. | Any valid Multimap route key | routeKey=DC,-0.97290:51.44850;-0.97069:51.45488,8 |
routeOpacity |
This attribute determines the degree of transparency of the polyline or polygon that represents a route on a map. | Any real number between 0 and 1 | routeOpacity=0.75 |
routeStartLabel |
This label is displayed over the icon marking the beginning of the route. | Any string of characters | routeStartLabel=Start |
routeThickness |
This attribute determines the thickness of the polyline or polygon that represents a route on a map. | Any real number (1.0 for default thickness, 2.0 for twice default thickness, 0.5 for half default thickness, etc.) | routeThickness=0.5 |
Here is an example of a URL showing a single route in Florida, US
using routeColor and routeOpacity parameters:
http://developer.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
Multimap Open API V1.2 Static Maps support the Local Information module which allows you to display points of interest of various types within the bounds of a static map.
| Parameter Name | Description | Permissible Values | Example |
|---|---|---|---|
overlayCount |
This parameter specifies the number of records returned in the results. | Integer or comma-separated list of integers | overlayCount=10 |
overlayDataSource |
This parameter specifies the data source to use. It is possible to search multiple data sources in one request by specifying a comma-separated list. | Comma-separated list | overlayDataSource=mm.poi.global.general.atm,
mm.poi.UK.premium.parking |
overlayLabel |
This parameter is a list of labels that are displayed over the markers for the corresponding data sources. | Comma-separated list of strings of characters | overlayLabel=%24,P |
overlayOpacity |
This parameter is a list of values that determine the degree of transparency of the markers for the corresponding data sources. | Any real numbers between 0 and 1 | overlayOpacity=0.8,1.0 |
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://developer.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
You can specify the size of your map by using the width
and height parameters to specify the map's dimensions in pixels:
http://developer.multimap.com/API/map/1.2/[api_key]?lat=51.123&lon=-0.9911 &zoomFactor=15&width=400&height=400
If you do not specify the dimensions of your static map, it appears at a default size of 200 pixels wide by 200 pixels high.
Please note that Multimap's recommended limits on map size are:
Multimap Open API V1.2 Static Maps support panning of a map in any direction by means of the moveMap and moveMapMeters parameters.
The coordinate system of the map has its point of origin (0,0) at the top left-hand corner of the web page, with the positive x-axis increasing toward the right and the positive y-axis increasing in value as its position moves downwards. This is in accordance with several recognized standards for coordinate systems that are in use.
A graphic depiction is shown below.
You should specify panning directions in a comma-separated pair with positive values for south and east and negative values for north and west:
To pan by a number of pixels, suffix the moveMap parameter with the number of pixels by which you wish to pan:
http://developer.multimap.com/API/map/1.2/[api_key]?lat=51.123&lon=-0.9911 &zoomFactor=15&width=400&height=400&moveMap=-25,0
http://developer.multimap.com/API/map/1.2/[api_key]?lat=51.123&lon=-0.9911 &zoomFactor=15&width=400&height=400&moveMap=0,25
http://developer.multimap.com/API/map/1.2/[api_key]?lat=51.123&lon=-0.9911 &zoomFactor=15&width=400&height=400&moveMap=25,-25
To pan by a specific distance in meters, include the moveMapMeters parameter.
http://developer.multimap.com/API/map/1.2/[api_key]?lat=51.123&lon=-0.9911 &zoomFactor=15&width=400&height=400&moveMapMeters=-100,0
http://developer.multimap.com/API/map/1.2/[api_key]?lat=51.123&lon=-0.9911 &zoomFactor=14&width=400&height=400&moveMapMeters=0,-500
http://developer.multimap.com/API/map/1.2/[api_key]?lat=51.123&lon=-0.9911 &zoomFactor=12&width=400&height=400&moveMapMeters=10000,10000
Please note that panning a map by a fixed distance in meters becomes less noticeable for maps that are rendered at low zoom factors ('zoomed out').
A static map request with the parameter "output=xml" gives you URLs to pan your current map in different directions. For details, please see the Multimap Open API V1.2 Static Maps XML documentation.
Maps can be zoomed in and out by means of the zoomFactor and zoom parameters. Maps are available between zoom factor 1 ("zoomed out") and zoom factor 18 ("zoomed in"), although not all zoom factors are available for all areas.
If you specify a map without including a zoom factor in your URL, the map is automatically zoomed to an appropriate zoom factor. This behavior can be overridden by using the zoomFactor and zoom parameters.
The zoomFactor parameter returns the map at a specific zoom factor:
http://developer.multimap.com/API/map/1.2/[api_key]?lat=51.123&lon=-0.9911 &zoomFactor=14&width=400&height=400
You can zoom a map from its current default factor using the zoom delta parameter, which specifies the number of zoom factors to zoom in or out. The resultant map is clipped to the extents of coverage, and does not change if the map is already at the largest or smallest available zoom factor. A positive value zooms in and a negative value zooms out. The maximum zoom out value is "1" whereas the maximum zoom in value depends on the map data available for the area.
http://developer.multimap.com/API/map/1.2/[api_key]?lat=51.123&lon=-0.9911 &zoom=2&width=400&height=400
(You could also zoom a map from a specified zoom factor by combining the zoomFactor and zoom parameters.)
Here is an example of a URL showing a static map centered on Constitution Avenue, Washington, DC, USA at zoom factor 15, with controls added to allow users to pan and zoom the map:
http://developer.multimap.com/API/map/1.2/[api_key]?lat=38.89207&lon=-77.0362 &zoomFactor=15&width=500&height=300
You can use the mapType parameter to request a static map or a static aerial photograph:
the default value is "map".
http://developer.multimap.com/API/map/1.2/[api_key]?lat=51.123&lon=-0.9911 &zoomFactor=15&width=400&height=400&mapType=map
http://developer.multimap.com/API/map/1.2/[api_key]?lat=51.123&lon=-0.9911 &zoomFactor=15&width=400&height=400&mapType=aerial
If required, you can use the optional output parameter
to determine the file format in which a static map image is rendered:
http://developer.multimap.com/API/map/1.2/[api_key]?output=png &lat=51.123&lon=-0.9911&zoomFactor=15&width=400&height=400
http://developer.multimap.com/API/map/1.2/[api_key]?output=jpg &lat=51.123&lon=-0.9911&zoomFactor=15&width=400&height=400
http://developer.multimap.com/API/map/1.2/[api_key]?output=gif &lat=51.123&lon=-0.9911&zoomFactor=15&width=400&height=400
http://clients.multimap.com/API/map/1.2/[api_key]?output=json &lat=51.123&lon=-0.9911&zoomFactor=15&width=400&height=400
http://developer.multimap.com/API/map/1.2/[api_key]?output=xml &lat=51.123&lon=-0.9911&zoomFactor=15&width=400&height=400
The default output format is PNG for static maps and JPG for static aerial photographs. The XML output returns information about the static map and allows pan and zoom links to be easily constructed, in addition to the static map URL. For details, please see the Multimap Open API V1.2 Static Maps XML Documentation.
The locale parameter lets you create different versions of the Multimap Open API
that offer support in several different languages,
by specifying the user's language and geographic area, for:
The default value is "en-US" for US-English, but other locales are possible:
http://developer.multimap.com/API/map/1.2/[api_key]?locale=es-ES &lat=41.38792&lon=2.16992&zoomFactor=15&width=400&height=400
http://developer.multimap.com/API/map/1.2/[api_key]?locale=fr-FR &lat=51.123&lon=-0.9911&zoomFactor=15&width=400&height=400
http://developer.multimap.com/API/map/1.2/[api_key]?locale=en-GB &lat=51.51453&lon=-0.10845&zoomFactor=15&width=400&height=400
Please follow this link to see a
full list of permissible values for the locale parameter.
In the event of a service failure or a failure to provide valid parameters, Multimap Open 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://developer.multimap.com/API/map/1.2/[api_key]?lat=-33.8684&long=151.20851
Instead of a 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://developer.multimap.com/API/map/1.2/[api_key]?lat=-33.8684&long=151.20851&output=xml
<?xml version="1.0" encoding="UTF-8" ?> <Error 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/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.
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 Open API service.
Web Services Home >> Multimap Open API V1.2 Static Maps XML Documentation
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 |