Static Map Service Developer's Guide

The static map service enables a user to create static map images that are generated by a simple HTTP request.

See our Release Notes for details on the latest additions to this service.

Hello, World!

In its most basic form, the Static Map Service lets you request a map of a specified size to be centered on a latitude/longitude at a particular zoom level.

Following example shows a simple static map request that generates a 400 by 200 image centered over Lancaster, PA. The JavaScript code which sends the request and displays the result can be viewed here.

(Results will be displayed below)

Contents

Static Maps by Latitude/Longitude

Generating a static map image is as easy as just sending in a center point and a zoom level. The method "getmap" takes a latitude/longitude pair and will center the static map image over that center point. It can also take a latitude/longitude pair as an upper left corner and one for a lower right corner and will then create the map based on those bounds.

Below is a table to describe common parameters used when retrieving a static image by latitude/longitude.

Request Parameter Description Example Request Data Required
key A unique key to authorize use of the Static Map Service. If a key is needed, please visit the Mapquest Developer Network. A valid key string Yes
center A center point for the map image. 40.0378,-76.305801 Yes, if the bestfit parameter is not present and no POIs are present
bestfit If a center point is not desired, a bounding box can be used to specify the area of the map to be shown. This parameter takes a latitude/longitude pair as an upper left corner bound and one for the lower right. It then creates a map based on those bounds given. 40.073246,-76.66658,39.90089,-76.31697 Yes, if the center parameter is not present and no POIs are present
Note: bestfit will override center
size Specifies the dimension of the map image requested.
Note: Width and height values cannot be larger than 2048		 400,200 Yes
zoom Specifies zoom level for the map image. An integer from 1-16 Yes, if the center parameter is present, the scale parameter is not present, and no POIs are present
Note: zoom overrides scale
scale Specifies display scale for map image. A valid scale integer. See Zoom to Scale Mapping for information on scales versus zoom levels. Yes, if the center parameter is present, the zoom parameter is not present, and no POIs are present
type Specifies map mode.
  • map
  • sat (Satellite)
  • hyb (Hybrid)
Default is "map" 		No
imageType Specifies the output image format.
  • jpeg
  • jpg
  • gif
  • png
Default is "jpg" 		No
pois Specifies a list of points of interests to add to the map. pois=LABEL1,LAT1,LNG1,OFFX1,OFFY1|....
|LABELN,LATN,LNGN,OFFXN,OFFYN| 		Accepted values are:
  • LABEL: Name of the icon to display. See the Static Map Standard Icons page for more detailed information.
  • LAT: The latitude of the POI
  • LNG: The longitude of the POI
  • OFFX: An X coordinate offset number for the POI
  • OFFY: A Y coordinate offset number for the POI
Offsets are optional.

Following example shows some of the parameters from above in action. The JavaScript code which sends the request and displays the result can be viewed here.

Static Map by Latitude/Longitude Sample

Option Value(s) Result
center: (Image will be shown here)
bestfit:
size:
type:
zoom:
imagetype:
style:
pois:

Static Map Advanced Options

There are more advanced parameters that can also be used with the Static Map service. These parameters can only be used with the "getmap" method. This is a quick list of some features the advanced options can expose:

  • Using various map styles. (different than the type option seen above)
  • Representing points of interest.
  • Route highlight showing driving directions along with via and stop points.
  • Drawing shapes by just providing latitude/longitude collections in any of the supported formats.
  • Flow of real time traffic.
  • Auto-bestfit and Auto-decluttering

Note: All advanced parameters are optional.

Request Parameter Description Format Accepted Values
mcenter Specifies center point to place a star icon. mcenter=LAT,LNG,OFFX,OFFY Accepted values are:
  • LAT: The latitude of the icon
  • LNG: The longitude of the icon
  • OFFX: An X coordinate offset number for the icon
  • OFFY: A Y coordinate offset number for the icon
Offsets are optional.
See the Static Map Standard Icons page for more detailed information.
pcenter Specifies center point to place a search icon. pcenter=LAT,LNG,OFFX,OFFY Accepted values are:
  • LAT: The latitude of the icon
  • LNG: The longitude of the icon
  • OFFX: An X coordinate offset number for the icon
  • OFFY: A Y coordinate offset number for the icon
Offsets are optional.
See the Static Map Standard Icons page for more detailed information.
xis Specifies a list of external or custom icons to be placed on the map. xis=URI,COUNT,
ALIGNA1,LATA1,LNGA1,TWKOFFXA1,TWKOFFYA1,OFFXA1,OFFYA1,....,
ALIGNAN,LATAN,LNGAN,TWKOFFXAN,TWKOFFYAN,OFFXAN,OFFYAN,....,
URIB,COUNTB,
ALIGNB1,LATB1,LNGB1,TWKOFFXB1,TWKOFFYB1,OFFXB1,OFFYB1,....,
ALIGNBN,LATBN,LNGBN,TWKOFFXBN,TWKOFFYBN,OFFXBN,OFFYBN,.... 		See the Custom Icons section for details on this option.
declutter Enables auto declutter. declutter=DECLUTTER Accepted values are:
  • true
  • false
For each POI(mcenter,pcenter,scenter,ecenter,vias,stops,pois and xis) in the request, the service finds the best possible decluttered position and places it on the map so that it does not overlap with any other POI.
When declutter is true, offsets will be ignored. By default, declutter is false.
shapeformat Specifies the input format of the "shape" parameter. shape=SHAPEFORMAT Accepted values are:
  • delta - First shape point is represented in mutliples of 106 and subsequent points is given as difference from previous point.
  • raw - shape is represented as latitude/longitude pairs.
  • cmp - shape is represented as a compressed path string with 5 digits of precision.
  • cmp6 - Same as cmp, but uses 6 digits of precision.
See the Compressed Lat/Lng Sample description page for more detail on the compressed format, including sample source code and an interactive encoder/decoder.
Also, see http://soulsolutions.com.au/Default.aspx?tabid=96 for a detailed description of the compressed format algorithm.
If "shapeformat" is not specified, then the "shape" parameter is interpreted as shapeformat=raw.
shape Specifies shape as a collection of latitude/longitude points. Using the collection, the static map service will attempt to put a route highlight on to the map image. The format the collection should relies on the value of "shapeformat" parameter. See shapeformat parameter for more information shape=LATLNGCOLLECTION Accepted values are collections of latitude/longitude pairs. The format of these values can differ depending on the "shapeformat" value set. See shapeformat parameter for more information.
scenter Specifies a point to place a route start icon. scenter=LAT,LNG,OFFX,OFFY Accepted values are:
  • LAT: The latitude of the icon
  • LNG: The longitude of the icon
  • OFFX: An X coordinate offset number for the icon
  • OFFY: A Y coordinate offset number for the icon
Offsets are optional.
See the Static Map Standard Icons page for more detailed information.
ecenter Specifies a point to place a route end icon. ecenter=LAT,LNG,OFFX,OFFY Accepted values are:
  • LAT: The latitude of the icon
  • LNG: The longitude of the icon
  • OFFX: An X coordinate offset number for the icon
  • OFFY: A Y coordinate offset number for the icon
Offsets are optional.
See the Static Map Standard Icons page for more detailed information.
stops Specifies a list of stops on the route. stops=LABEL1,LAT1,LNG1,OFFX1,OFFY1|....
|LABELN,LATN,LNGN,OFFXN,OFFYN|		 Accepted values are:
  • LABEL: Name of the icon to display. See Icon doc for detailed information.
  • LAT: The latitude of the POI
  • LNG: The longitude of the POI
  • OFFX: An X coordinate offset number for the POI
  • OFFY: A Y coordinate offset number for the POI
Offsets are optional.
See the Static Map Standard Icons page for more detailed information.
vias Specifies a list of via points on the route. vias=LABEL1,LAT1,LNG1,OFFX1,OFFY1|....
|LABELN,LATN,LNGN,OFFXN,OFFYN|		 Accepted values are:
  • LABEL: Name of the icon to display. See Icon doc for detailed information.
  • LAT: The latitude of the POI
  • LNG: The longitude of the POI
  • OFFX: An X coordinate offset number for the POI
  • OFFY: A Y coordinate offset number for the POI
Offsets are optional.
See the Static Map Standard Icons page for more detailed information.
session Specifies a session ID from a route made with the Mapquest Directions Service. session=SESSIONID A valid session ID
traffic Specifies the inclusion of traffic data such as flow, incidents, and construction pertaining to the requested map location. traffic=TRAFFICON Accepted values are:
  • 4 - flow only
  • 3 - construction + flow
  • 2 - incidents + flow
  • 1 - both + flow
  • 0 - no traffic
trafficstyle Specifies style of the traffic flow highlight. trafficstyle=TRAFFICSTYLE As of now, only "mobile" trafficstyle is supported. The width of the traffic flow highlight is slimmed down when "mobile" used.

Custom Icons

In addition to the variety of icons we provide for you, we have also made it possible you the user to use their own custom icon images on a static map image.

The "xis" parameter handles the custom icons. Its format is:
xis=URI,COUNT,ALIGN,LAT,LNG,TWKOFFX,TWKOFFY,OFFX,OFFY
If the same icon will be used in differnt places you can change each one's indivdual alignment and offsets with this format:
xis=URI,COUNT,ALIGN1,LAT1,LNG1,TWKOFFX1,TWKOFFY1,OFFX1,OFFY1,...,ALIGNN,LATN,LNGN,TWKOFFXN,TWKOFFYN,OFFXN,OFFYN
Lastly, you can also have multiple custom icons in this format:
xis=URI,COUNT,ALIGNA1,LATA1,LNGA1,TWKOFFXA1,TWKOFFYA1,OFFXA1,OFFYA1,...,ALIGNAN,LATAN,LNGAN,TWKOFFXAN,TWKOFFYAN,OFFXAN,OFFYAN,...,
URI,COUNT,ALIGNB1,LATB1,LNGB1,TWKOFFXB1,TWKOFFYB1,OFFXB1,OFFYB1,...,ALIGNBN,LATBN,LNGBN,TWKOFFXBN,TWKOFFYBN,OFFXBN,OFFYBN

Below is a table describing the format of the "xis" parameter.

Property Description
uri URL to the image but without the leading HTTP protocol string. SSL images are not supported and the path cannot contain comma. The icon can be a jpg, png, gif image. The size of the icon is limited to 150KB. Any image that does not fall into list of supported image types, weighs more than the threshold size, or cannot be found, will be replaced with a default red circle.
Example uri: /media/images/money_sign.jpg
count An integer for how many times the particular image will be used on the map.
align This sets an alignment for the icon. There are nine values that can be used:
  • C - center
  • TL - top left
  • TC - top center
  • TR - top right
  • LC - left center
  • RC - right center
  • BL - botton left
  • BC - bottom center
  • BR - bottom right
Default is C
lat The latitude of the icon.
lng The longitude of the icon.
offx This is the offset of the icon on the x axis. This is optional.
offy This is the offset of the icon on the y axis. This is optional.
twkoffx This offset will be applied after the latitude/longitude, alignment, and offset. The main difference is this offset will have a line drawn from the position is should be in to where this offset tells it to be. This is optional.
twkoffy This offset will be applied after the latitude/longitude, alignment, and offset. The main difference is this offset will have a line drawn from the position is should be in to where this offset tells it to be. This is optional.

Any custom icon will be cached for 60 minutes by default. For more information on the way we do this and how to override it see the Flush Icon service page.

Following example shows some of the advanced parameters, including custom icons, in action. The JavaScript code which sends the request and displays the result can be viewed here.

Static Map Advanced Options Sample

Notice in this example there is no "center", "zoom", or "bestfit" parameters. This is because this sample is taking advantage of our auto-bestfit feature. If none of the above parameters are provided, the auto-bestfit uses POIs placed on the map and scales the map to the best center and zoom level to show all the POIs.
Note: Auto-bestfit does not take into account offsets on the icons, so there could be cases where the offsets will make the actual icons be off the map.

Option Value(s) Result
size: (image will be placed here)
type:
mcenter:
pcenter:
xis:
declutter:
shape:
scenter:
ecenter:
traffic:
(The traffic data is real time so incidents and construction icons will only show if it is currently happening)

Static Maps by Place

In addition to using latitude/longitude poits, it is also possible to use single-line address to create a static map image. The method "getplacemap" is used when generating a static map image this way. Minimally, all that is needed is a key, a size for the image, and the location. Currently, single-line locations are only available for the United States. This will be updated, but in the meantime, international static maps can be generated using latitude/longitude pairs. See Static Maps by Latitude/Longitude for details on how to generate static maps without an address.

When using single-line addresses, the following formats are acceptable.

Format Example
city (AA5), state (AA3) Lancaster, PA
city, state, postcode Lancaster, PA, 17601
postcode 17601
street, city, state 300 Granite Run Dr, Lancaster, PA
street, city, state, postcode 300 Granite Run Dr, Lancaster, PA, 17601
street, postcode 300 Granite Run Dr, 17601
JSON Object {street: "Boalsburg, PA"}

Below is a table to describe common parameters used when retrieving a static image by place.

Request Parameter Description Example Request Data Required
key A unique key to authorize use of the Static Map Service. If a key is needed, please visit the Mapquest Developer Network. A valid key string Yes
location A single-line address for the map image to be centered over. See Specifying Locations for details on correct ways of formatting single-line addresses. Lancaster,PA Yes
size Specifies the dimension of the map image requested.
Note: Width and height values cannot be larger than 2048		 400,200 Yes
zoom Specifies a zoom level for the map image. An integer from 1-16 Yes, if the scale parameter is not present
Note: zoom overrides scale
scale Specifies a display scale for map image. A valid scale integer. See Zoom to Scale Mapping for information on scales versus zoom levels Yes, if the zoom parameter is not present
type Specifies the map mode.
  • map
  • sat (Satellite)
  • hyb (Hybrid)
 No
imageType Specifies the output image format.
  • jpeg
  • jpg
  • gif
  • png
Default is "jpg" 		No
showicon The type of POI icon to be placed in at the geocoded addess. If more advanced POIs are desired, the "getmap" method must be used. See the Static Map Standard Icons page for information on icons provided No

Following example shows some of the parameters from above in action. The JavaScript code which sends the request and displays the result can be viewed here.

Static Map by Place Sample

Option Value(s) Result
location: (Image will be placed here)
size:
type:
zoom:
imagetype:
showicon:
style: