Multimap logo Multimap Open API V1.2 Web Services Documentation - Static Maps XML Response

Multimap Open API V1.2 Web Services >> Multimap Open API V1.2 Static Maps Documentation

Static Maps XML Documentation - Introduction

The Static Maps module can provide an XML output in addition to other image based formats. The XML format provides a map URL, as well as more information about the current map (such as its center, bounds and the position of any markers), and allows links for panning and zooming to be constructed easily.

Basic Example

Here is an example of a URL for a basic static map example and the XML output it generates: 

http://developer.multimap.com/API/map/1.2/[api_key]?output=xml&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 API key which your Multimap account manager has provided.

Response

The URL shown above returns the following response:

<?xml version="1.0" encoding="UTF-8"?>
<Map 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/map_1.2.xsd">
  <MapURL>http://developer.multimap.com/API/map/1.2/[api_key]?output=png&amp;lat=38.89207&amp;lon=-77.0362&amp;zoomFactor=15&amp;width=400&amp;height=400</MapURL>
  <PanURLs>
    <North>http://developer.multimap.com/API/map/1.2/[api_key]?output=xml&amp;lat=38.89207&amp;lon=-77.0362&amp;zoomFactor=15&amp;width=400&amp;height=400&amp;moveMap=0,-240</North>
    <East>http://developer.multimap.com/API/map/1.2/[api_key]?output=xml&amp;lat=38.89207&amp;lon=-77.0362&amp;zoomFactor=15&amp;width=400&amp;height=400&amp;moveMap=240,0</East>
    <South>http://developer.multimap.com/API/map/1.2/[api_key]?output=xml&amp;lat=38.89207&amp;lon=-77.0362&amp;zoomFactor=15&amp;width=400&amp;height=400&amp;moveMap=0,240</South>
    <West>http://developer.multimap.com/API/map/1.2/[api_key]?output=xml&amp;lat=38.89207&amp;lon=-77.0362&amp;zoomFactor=15&amp;width=400&amp;height=400&amp;moveMap=-240,0</West>
    <NorthEast>http://developer.multimap.com/API/map/1.2/[api_key]?output=xml&amp;lat=38.89207&amp;lon=-77.0362&amp;zoomFactor=15&amp;width=400&amp;height=400&amp;moveMap=240,-240</NorthEast>
    <SouthEast>http://developer.multimap.com/API/map/1.2/[api_key]?output=xml&amp;lat=38.89207&amp;lon=-77.0362&amp;zoomFactor=15&amp;width=400&amp;height=400&amp;moveMap=240,240</SouthEast>
    <SouthWest>http://developer.multimap.com/API/map/1.2/[api_key]?output=xml&amp;lat=38.89207&amp;lon=-77.0362&amp;zoomFactor=15&amp;width=400&amp;height=400&amp;moveMap=-240,240</SouthWest>
    <NorthWest>http://developer.multimap.com/API/map/1.2/[api_key]?output=xml&amp;lat=38.89207&amp;lon=-77.0362&amp;zoomFactor=15&amp;width=400&amp;height=400&amp;moveMap=-240,-240</NorthWest>
  </PanURLs>
  <ZoomURLs>
    <In>http://developer.multimap.com/API/map/1.2/[api_key]?output=xml&amp;lat=38.89207&amp;lon=-77.0362&amp;zoomFactor=15&amp;width=400&amp;height=400&amp;zoom=1</In>
    <Out>http://developer.multimap.com/API/map/1.2/[api_key]?output=xml&amp;lat=38.89207&amp;lon=-77.0362&amp;zoomFactor=15&amp;width=400&amp;height=400&amp;zoom=-1</Out>
  </ZoomURLs>
  <MapCenter>
    <Lat>38.89207</Lat>
    <Lon>-77.0362</Lon>
  </MapCenter>
  <Bounds>
    <NorthEast>
      <Lat>38.90548</Lat>
      <Lon>-77.01903</Lon>
    </NorthEast>
    <SouthWest>
      <Lat>38.87865</Lat>
      <Lon>-77.05337</Lon>
    </SouthWest>
  </Bounds>
  <Marker>
    <IconName>default.png</IconName>
    <MetaData>
      <X>200</X>
      <Y>200</Y>
    </MetaData>
    <Point>
      <Lat>38.89207</Lat>
      <Lon>-77.0362</Lon>
    </Point>
    <Label>1</Label>
  </Marker>
  <Dimensions>
    <Width>400</Width>
    <Height>400</Height>
  </Dimensions>
  <ZoomFactor>15</ZoomFactor>
</Map>

Notes On Response

CodeNotes
<?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.
<Map 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/map_1.2.xsd">

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.
<MapURL>http://developer.multimap.com/API/map/1.2/[api_key]?
output=png&amp;lat=38.89207&amp;lon=-
77.0362&amp;zoomFactor=15&amp;width=400
&amp;height=400</MapURL>

The MapUrl element contains a URL that returns a map image for the current request.

 

<PanURLs>
 <North>http:// ... &amp;moveMap=0,-240</North>
 <East>http:// ... &amp;moveMap=240,0</East>
 <South>http:// ... &amp;moveMap=0,240</South>
 <West>http:// ... &amp;moveMap=-240,0</West>
 <NorthEast>http:// ... &amp;moveMap=240,-240</NorthEast>
 <SouthEast>http:// ... &amp;moveMap=240,240</SouthEast>
 <SouthWest>http:// ... &amp;moveMap=-240,240</SouthWest>
 <NorthWest>http:// ... &amp;moveMap=-240,-240</NorthWest>
</PanURLs>

The PanURL element contains URLs for panning the current map request in eight compass-point directions.

 

<ZoomURLs>
    <In>http:// ... <em>&amp;zoom=1</em></In>
    <Out>http:// ... <em>&amp;zoom=-1</em></Out>
</ZoomURLs>

The ZoomURL element contains URLs to zoom the map in or out one by one zoom level.

 

<MapCenter>
    <Lat>38.89207</Lat>
    <Lon>-77.0362</Lon>
</MapCenter>

The MapCenter element contains latitude and longitude for the center of the map request.

 

<Bounds>
    <NorthEast>
        <Lat>38.90548</Lat>
        <Lon>-77.01903</Lon>
    </NorthEast>
    <SouthWest>
        <Lat>38.87865</Lat>
        <Lon>-77.05337</Lon>
    </SouthWest>
</Bounds>

The Bounds element contains latitude and longitude for the north-east (top-right) and south-west (bottom-left) corner of the map.

 

<Marker>
    <IconName>default.png</IconName>
    <MetaData>
        <X>200</X>
        <Y>200</Y>
    </MetaData>
    <Point>
        <Lat>38.89207</Lat>
        <Lon>-77.0362</Lon>
    </Point>
    <Label>1</Label>
</Marker>

There may be one or more Marker elements in the response. The Marker element contains information about the markers that will be displayed on the map. The IconName and Label elements show the name of the icon that will be used for the marker and the text that will be used to label it. The Point and MetaData elements contain the latitude and longitude of the marker and its location on the map in pixels. 


<Dimensions>
    <Width>400</Width>
    <Height>400</Height>
</Dimensions>

The Dimensions element shows the width and height of the map image in pixels.
<ZoomFactor>15</ZoomFactor>

The ZoomFactor element shows the zoom factor for the map.

Top of page

Routing

Routing example

Here is an example of a URL for a single route in Florida, US: 

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&output=xml

Response

The URL shown above returns the following response:

<?xml version="1.0" encoding="UTF-8"?>
<Map 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/map_1.2.xsd">
  <MapURL>http://developer.multimap.com/API/map/1.2/[api_key]?output=png&amp;routeKey=US,-80.28732:25.78210;-80.45884:25.07744,0&amp;width=400&amp;height=400&amp;routeColor=255,0,0&amp;routeOpacity=1</MapURL>
  <PanURLs>
    <North>http://developer.multimap.com/API/map/1.2/[api_key]?output=xml&amp;routeKey=US,-80.28732:25.78210;-80.45884:25.07744,0&amp;width=400&amp;height=400&amp;routeColor=255,0,0&amp;routeOpacity=1&amp;moveMap=0,-240</North>
    <East>http://developer.multimap.com/API/map/1.2/[api_key]?output=xml&amp;routeKey=US,-80.28732:25.78210;-80.45884:25.07744,0&amp;width=400&amp;height=400&amp;routeColor=255,0,0&amp;routeOpacity=1&amp;moveMap=240,0</East>
    <South>http://developer.multimap.com/API/map/1.2/[api_key]?output=xml&amp;routeKey=US,-80.28732:25.78210;-80.45884:25.07744,0&amp;width=400&amp;height=400&amp;routeColor=255,0,0&amp;routeOpacity=1&amp;moveMap=0,240</South>
    <West>http://developer.multimap.com/API/map/1.2/[api_key]?output=xml&amp;routeKey=US,-80.28732:25.78210;-80.45884:25.07744,0&amp;width=400&amp;height=400&amp;routeColor=255,0,0&amp;routeOpacity=1&amp;moveMap=-240,0</West>
    <NorthEast>http://developer.multimap.com/API/map/1.2/[api_key]?output=xml&amp;routeKey=US,-80.28732:25.78210;-80.45884:25.07744,0&amp;width=400&amp;height=400&amp;routeColor=255,0,0&amp;routeOpacity=1&amp;moveMap=240,-240</NorthEast>
    <SouthEast>http://developer.multimap.com/API/map/1.2/[api_key]?output=xml&amp;routeKey=US,-80.28732:25.78210;-80.45884:25.07744,0&amp;width=400&amp;height=400&amp;routeColor=255,0,0&amp;routeOpacity=1&amp;moveMap=240,240</SouthEast>
    <SouthWest>http://developer.multimap.com/API/map/1.2/[api_key]?output=xml&amp;routeKey=US,-80.28732:25.78210;-80.45884:25.07744,0&amp;width=400&amp;height=400&amp;routeColor=255,0,0&amp;routeOpacity=1&amp;moveMap=-240,240</SouthWest>
    <NorthWest>http://developer.multimap.com/API/map/1.2/[api_key]?output=xml&amp;routeKey=US,-80.28732:25.78210;-80.45884:25.07744,0&amp;width=400&amp;height=400&amp;routeColor=255,0,0&amp;routeOpacity=1&amp;moveMap=-240,-240</NorthWest>
  </PanURLs>
  <ZoomURLs>
    <In>http://developer.multimap.com/API/map/1.2/[api_key]?output=xml&amp;routeKey=US,-80.28732:25.78210;-80.45884:25.07744,0&amp;width=400&amp;height=400&amp;routeColor=255,0,0&amp;routeOpacity=1&amp;zoom=1</In>
    <Out>http://developer.multimap.com/API/map/1.2/[api_key]?output=xml&amp;routeKey=US,-80.28732:25.78210;-80.45884:25.07744,0&amp;width=400&amp;height=400&amp;routeColor=255,0,0&amp;routeOpacity=1&amp;zoom=-1</Out>
  </ZoomURLs>
  <MapCenter>
    <Lat>25.43133</Lat>
    <Lon>-80.38177</Lon>
  </MapCenter>
  <Bounds>
    <NorthEast>
      <Lat>25.9291</Lat>
      <Lon>-79.83245</Lon>
    </NorthEast>
    <SouthWest>
      <Lat>24.93148</Lat>
      <Lon>-80.93109</Lon>
    </SouthWest>
  </Bounds>
  <Marker>
    <IconName>default.png</IconName>
    <MetaData>
      <X>234.3882</X>
      <Y>59.16647</Y>
    </MetaData>
    <Point>
      <Lat>25.78206</Lat>
      <Lon>-80.28732</Lon>
    </Point>
    <Label>S</Label>
  </Marker>
  <Marker>
    <IconName>default.png</IconName>
    <MetaData>
      <X>171.93967</X>
      <Y>341.68301</Y>
    </MetaData>
    <Point>
      <Lat>25.07744</Lat>
      <Lon>-80.45884</Lon>
    </Point>
    <Label>F</Label>
  </Marker>
  <RouteOverlay>
    <Opacity>1</Opacity>
    <Thickness>1</Thickness>
    <Color>
      <RGB>255,0,0</RGB>
    </Color>
    <MetaData>
      <StartPoint>
        <X>234</X>
        <Y>59</Y>
      </StartPoint>
      <EndPoint>
        <X>172</X>
        <Y>342</Y>
      </EndPoint>
    </MetaData>
  </RouteOverlay>
  <Dimensions>
    <Width>400</Width>
    <Height>400</Height>
  </Dimensions>
  <ZoomFactor>10</ZoomFactor>
</Map>

Notes On Response

In addition to the previous response, a RouteOverlay element is added when adding a route to a map:

CodeNotes
<Opacity>1</Opacity>

The Opacity element shows the level of opacity applied to the route highlight. It is a value between 0 and 1 where 1 is fully opaque.
<Thickness>1</Thickness>

The Thickness element shows the thickness of the line used to draw the route highlight. It is a proportional value where 1 is the default thickness. 


<Color>
    <RGB>255,0,0</RGB>
</Color>

The Color element contains the RGB value for the color used for the route highlight. 


<MetaData>
    <StartPoint>
        <X>234</X>
        <Y>59</Y>
    </StartPoint>
    <EndPoint>
        <X>172</X>
        <Y>342</Y>
    </EndPoint>
</MetaData>

The MetaData element contains pixel coordinates for the start and end of the route. If you request for the start and/or end icons to be displayed on the route, the MetaData element corresponds with the Marker elements.

Error Codes

In the event of a service failure or a failure to provide valid parameters, error codes are returned in the XML output. These error codes are listed below:

Error CodeError MessageDescription
MM_API_ERROR_INTERNAL_ERROR We're sorry; we couldn't complete your request. Please try again later.An unexpected error occurred.
MM_MAP_ERROR_INVALID_COORDINATES We're sorry; we do not recognize the set of search criteria that you have entered. Please re-enter your search criteria and try again.The request contained invalid coordinates.
MM_API_ERROR_DIRECTION_REQUEST_FAILED We're sorry; we are unable to generate this route.A problem occurred with the route request.
MM_MAP_ERROR_NO_COORDINATES We're sorry; you didn't specify any search criteria. Please try again.The request did not contain, or could not be resolved to, any valid coordinates.
MM_SEARCH_NO_MATCHES We're sorry; we found no results for this set of search terms. Please try again.There are no records that match your search criteria.

Example

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

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

Response

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

Multimap Open API V1.2 Web Services >> Multimap Open API V1.2 Static Maps Documentation

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:

Australia, Sydney + 61 (0) 2 9262 6551
Great Britain, London +44 (0)20 7632 7800
United States, Boston + 1 617 423 4510
email: sales@multimap.com