Static Map Service Developer's Guide

The Static Map Service provides a simple interface to avail the following services.

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

Contents

Static Map Service: getmap

This service is intended to generate a map based on the parameters subjected through HTTP request. There is absolutely zero need for any development to consume the service.

Request Formats

A request for staticmap 'getmap' service can be placed with a plain HTTP request. Following protocols are supported.

  • HTTP GET
  • HTTP POST

Response Formats

Below are response formats for any 'getmap' request.

  • Either of image/gif, image/png, image/jpeg, image/jpg format, based on the 'imagetype' parameter.
  • text/plain format, incase of error.

Hello, World!

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

Request via HTTP GET

If you send your request via an HTTP GET, you will need to provide your input as query parameters.

Following example shows the map for Lancaster, PA using HTTP GET request. 
/staticmap/v3/getmap?size=400,200&zoom=7&center=40.054600,-76.313100&key=[YOUR_KEY_HERE]

Request via HTTP POST

You can also send map request on HTTP POST by placing the parameters and their respective values in the request body. As with certain browsers like IE the URL length is limited to only 2048 characters, in such cases, the support for HTTP POST method comes handy.

Following example shows a HTTP POST request to display map of Lancaster, PA. 
/staticmap/v3/getmap
HTTP POST Body: 
size=400,200&center=40.044600,-76.413100&zoom=10&key=[YOUR_KEY_HERE]

Note: HTTP POST request can not be invoked using <IMG> tag.

Basic Options

The following table describes the minimal set of parameters for 'getmap':

Request Parameter Description Format Accepted Values Required?
key The key you received when you registered for service. If you have not registered for service, you will need to do so at the MapQuest Developer Network site. key=KEY KEY: A valid key string Yes
size Specifies dimension of the map requested. size=WIDTH,HEIGHT WIDTH: 1<= width <= 2048
HEIGHT: 1 <= height <= 2048 		Yes
type Specifies map mode. type=TYPE TYPE: must be one of the following -
  • map
  • sat
  • hyb
 No, default is 'map' type
center Specifies center point of the map requested. center=CLAT,CLNG CLAT: -90.00 <= clat <= 90.00
CLNG: -180.00 <= clng <= 180.00 		No, if bestfit is present or atleast one point of interest(POI) is present to trigger auto-bestfit.
zoom Specifies zoom level for the map. zoom=ZOOM ZOOM: 1 <= zoom <= 16 No, if bestfit or (scale and center) or atleast one POI is present to auto-bestfit. Overrides scale parameter if present.
scale Specifies display scale for map. scale=SCALE SCALE: 88011773, 29337258, 9779086, 3520471, 1504475, 701289, 324767, 154950, 74999, 36000, 18000, 9000, 4700, 2500, 1500, 1000
Click here to find out the scale for a particular zoom level. 		No, if bestfit or (zoom and center) or atleast one POI is present to auto-bestfit.
bestfit Specifies lat/lng bounding box of display elements to best fit on. In cases where zoom level/scale is unknown, one can let the application decide the attributes using 'bestfit' option. bestfit=ULLAT,ULLNG,LRLAT,LRLNG ULLAT: -90.00 <= ullat <= 90.00
ULLNG: -180.00 <= ullng <= 180.00
LRLAT: -90.00 <= lrlat <= 90.00
LRLNG: -180.00 <= lrlng <= 180.00		 No, if (zoom and center) or (scale and center) or atleast one POI is present to auto-bestfit. Overrides [zoom/scale] and center.
imagetype Specifies the output image format. imagetype=IMAGETYPE IMAGETYPE: jpeg, jpg, gif, png
No, by default, the image format type will be jpeg.

Example showing Map/ Arial/ Hybrid types in different image formats

Map in JPEG format:

/staticmap/v3/getmap?type=map&center=40.044600,-76.413100&size=360,200&scale=154950&imagetype=jpeg&key=[YOUR_KEY_HERE]

Satellite/Arial in PNG format:

/staticmap/v3/getmap?type=sat&center=40.044600,-76.413100&size=360,200&scale=154950&imagetype=png&key=[YOUR_KEY_HERE]

Hyrbid in GIF format:

/staticmap/v3/getmap?type=hyb&center=40.044600,-76.413100&size=360,200&scale=154950&imagetype=gif&key=[YOUR_KEY_HERE]

Example using 'zoom' & 'center'

/staticmap/v3/getmap?center=40.044600,-76.413100&size=400,200&zoom=6&key=[YOUR_KEY_HERE]

Example using 'scale' & 'center'

/staticmap/v3/getmap?center=40.044600,-76.413100&size=400,200&scale=701289&key=[YOUR_KEY_HERE]

Example using 'bestfit'

/staticmap/v3/getmap?size=400,200&bestfit=40.1,-76.7,40.0,-76.0&key=[YOUR_KEY_HERE]

Advanced Options

Advanced parameters can be used to render a static map for either of the following.
  • Using various map styles.
  • Representing points of interest.
  • Route highlight showing driving direction along with via and stop points.
  • Drawing shapes by just providing LatLng Collections in any of the supported formats.
  • Flow of real time traffic.
  • Auto-bestfit and Auto-decluttering
Note: All advanced parameters are optional. To surf all the standard icons available within static map service go to Static Map Service : Standard Icons

Request Parameter Description Format Accepted Values
style Specifies the style of the map. style=STYLE STYLE:
  • 2k6a
  • bw
  • classic
  • european
  • style5
Applicable only when 'type' is 'map'.
If 'style' is not specified, map will be rendered with a default style as configured in the application.
mcenter Specifies center point to place map star icon. mcenter=MLAT,MLNG,MOFFX,MOFFY MLAT: -90.00 <= mlat <= 90.00
MLNG: -180.00 <= mlng <= 180.00
MOFFX: declutter offset for x coordinate
MOFFY: declutter offset for y coordinate

Offsets are optional. Works with auto-bestfit.
pcenter Specifies center point to place search star icon. pcenter=PLAT,PLNG,POFFX,POFFY PLAT: -90.00 <= plat <= 90.00
PLNG: -180.00 <= plng <= 180.00
POFFX: declutter offset for x coordinate
POFFY: declutter offset for y coordinate

Offsets are optional. Works with auto-bestfit.
scenter Specifies center point to place route start icon. scenter=SLAT,SLNG,SOFFX,SOFFY SLAT: -90.00 <= slat <= 90.00
SLNG: -180.00 <= slng <= 180.00
SOFFX: declutter offset for x coordinate
SOFFY: declutter offset for y coordinate

Offsets are optional. Works with auto-bestfit.
ecenter Specifies center point to place route end icon. ecenter=ELAT,ELNG,EOFFX,EOFFY ELAT: -90.00 <= elat <= 90.00
ELNG: -180.00 <= elng <= 180.00
EOFFX: declutter offset for x coordinate
EOFFY: declutter offset for y coordinate

Offsets are optional. Works with auto-bestfit.
pois Specifies a list of point of interests. pois=PLABEL1,PLAT1,PLNG1,POFFX1,POFFY1|..|..
|PLABELN,PLATN,PLNGN,POFFXN,POFFYN|		 PLABELN: name of icon to display - expected format is one of the following:
  • <#> (1:150)
  • <color> (***see supported colors below)
  • <color>-s (super POI)
  • <color>-<#> (0:150)
PLATN: -90.00 <= latn <= 90.00
PLNGN: -180.00 <= lngn <= 180.00
POFFXN: declutter offset for x coordinate
POFFYN: declutter offset for y coordinate

Offsets are optional. Works with auto-bestfit.

*** Following are the supported colors :
  • blue
  • green
  • orange
  • purple
  • white
  • yellow
stops Specifies a list of stops on the route. stops=SLABEL1,SLAT1,SLNG1,SOFFX1,SOFFY1|..|..
|SLABELN,SLATN,SLNGN,SOFFXN,SOFFYN|		 SLABELN: name of icon to display (A:J )
SLATN: -90.00 <= latn <= 90.00
SLNGN: -180.00 <= lngn <= 180.00
SOFFXN: declutter offset for x coordinate
SOFFYN: declutter offset for y coordinate

Offsets are optional. Works with auto-bestfit.
vias Specifies a list of via points on the route. vias=VLABEL1,VLAT1,VLNG1,VOFFX1,VOFFY1|..|..
|VLABELN,VLATN,VLNGN,VOFFXN,VOFFYN|		 VLABELN: name of icon to display (red-circle)
VLATN: -90.00 <= latn <= 90.00
VLNGN: -180.00 <= lngn <= 180.00
VOFFXN: declutter offset for x coordinate
VOFFYN: declutter offset for y coordinate

Offsets are optional. Works with auto-bestfit.
shapeformat Specifies the input format of the 'shape' parameter. shape=SHAPEFORMAT SHAPEFORMAT: delta, raw, cmp, cmp6
  • 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 float pairs.
  • cmp - shape is represented as a compressed path string with 5 digits of precision.
  • cmp6 - Same as for cmp, but uses 6 digits of precision.
See the Compressed Lat/Lng description page for more detail, including sample source code and an interactive encoder/decoder. If 'shapeformat' is not specified, then shape is interpreted in 'raw' shape format.
shape Specifies shape as collection of lat/lng points in the 'shape' format specified. shape=SALTERNATED_LATLNGCOLLECTION SALTERNATED_LATLNGCOLLECTION : Alternated array of lat/lngs. Evens are lat and odds are lng. Below is it's representation depending on the 'shape' formats.
  1. delta:
    SFIRSTLAT,SFIRSTLNG,SDELTA_LAT2,SDELTA_LNG2,..,..,SDELTA_LATN,SDELTA_LNGN
    Specify first shape point pair SLAT,SLNG in multiples of 106.
    SFIRSTLAT: -90000000 <= slat <= 90000000
    SFIRSTLNG: -180000000 <= slng <= 180000000
    • Ex 1: SLAT for 80.123456 should be 80123456
    • Ex 2: SLAT for 80.12345678 will be 80123456.78
    SDELTA_LATN: Difference from previous latitude point.
    SDELTA_LNGN: Difference from previous longitude point.
  2. raw:
    SLAT1,SLNG1,SLAT2,SLNG2,..,..,SLATN,SLNGN
    SLATN: -90.00 <= lrlat <= 90.00
    SLNGN: -180.00 <= lrlng <= 180.00
  3. cmp:
    SLAT1,SLNG1,SLAT2,SLNG2,..,..,SLATN,SLNGN compressed with 5 digits of precision.
    SLATN: -90.00 <= lrlat <= 90.00
    SLNGN: -180.00 <= lrlng <= 180.00
    See http://soulsolutions.com.au/Default.aspx?tabid=96 for a detailed description of the compressed format
  4. cmp6:
    SLAT1,SLNG1,SLAT2,SLNG2,..,..,SLATN,SLNGN compressed with 6 digits of precision.
    SLATN: -90.00 <= lrlat <= 90.00
    SLNGN: -180.00 <= lrlng <= 180.00
    Same as 'cmp' but uses 6 digits of precision.
session Specifies session containing route highlight from MapQuest Routing Service. session=SESSIONID SESSIONID: session id that links to route shape points

You can refer to Routing Services Developer's Guide to acquire a session id.
traffic Specifies the inclusion of traffic data such as flow, incidents and construction pertaining to the requested map location. traffic=TRAFFICON TRAFFICON: 0 <= traffic <= 4
  • 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 TRAFFICSTYLE: mobile
As of now, 'mobile' trafficstyle is supported. The width of the traffic flow highlight is slimmed down when 'mobile' used.
xis Specifies a list of external or custom icons to be placed on the map. xis=XIURIA,XICOUNTA,
XIALIGNA1,XILATA1,XILNGA1,XITWKOFFXA1,XITWKOFFYA1,
XIOFFXA1,XIOFFYA1,....,
XIALIGNAN,XILATAN,XILNGAN,XITWKOFFXAN,XITWKOFFYAN,
XIOFFXAN,XIOFFYAN,....,
XIURIB,XICOUNTB,
XIALIGNB1,XILATB1,XILNGB1,XITWKOFFXB1,XITWKOFFYB1,
XIOFFXB1,XIOFFYB1,....,
XIALIGNBN,XILATBN,XILNGBN,XITWKOFFXBN,XITWKOFFYBN,
XIOFFXBN,XIOFFYBN,....		 -- Repeatable Arbitrary Number of Times --
  1. XIURI: URL to the image but without the leading HTTP protocol string.
    The URI of the custom icon is assumed to be non-SSL. SSL images are not supported. The path must not contain comma.
    Icon can be of jpg, png, gif image format.
    Size of the icon is limited to 5000 bytes.

    Any image that does not fall into list of supported image types or weighs more than the threshold size will be replaced with a default red circle. If the application can not fetch the image from the given URL, default icon will be substituted.
  2. XICOUNT: Total number of times, the icon referenced by this URI will be repeating on the map.
  3. -- Repeatable 'XICOUNT' number of times --
    1. XIALIGNN: One of nine choices: C TL TC TR RC BR BC BL LC.
      Alignment defaults to C.
    2. XILATN: -90.00 <= latn <= 90.00. Applicable to non-decluttered icons.
    3. XILNGN: -180.00 <= lngn <= 180.00
    4. XIOFFXN: declutter offset for x coordinate
    5. XIOFFYN: declutter offset for y coordinate. If either coordinates of declutter offset are non 0, the alignment and tweak offsets are ignored.
    6. XITWKOFFXN: tweak offset for x coordinate
    7. XITWKOFFYN: tweak offset for y coordinate.Applicable to non-decluttered icons.
    Offsets are optional.
All icons are cached for predefined time period. Works with auto-bestfit.
declutter Enables auto declutter. declutter=DECLUTTER DECLUTTER: true, false
For each POI(mcenter,pcenter,scenter,ecenter,vias,stops,pois and xis) in the request, the service finds a best possible decluttered position and places it on the map so that it doesnt overlap with any other POI.

When declutter is true, offsets will be ignored. By default, declutter is false.

Example showing map star icon centering the map and place search icon pointing to Lancaster, PA on various map styles.

Map and Search Center on Black & White map style:

/staticmap/v3/getmap?style=bw&center=40.044600,-76.413100&size=360,200&zoom=6&mcenter=40.024600,-76.413100,10,40,&pcenter=40.054600,-76.313100,0,-40,&key=[YOUR_KEY_HERE]

Map and Search Center on Classic Map Style:

/staticmap/v3/getmap?style=classic&center=40.044600,-76.413100&size=360,200&zoom=6&mcenter=40.024600,-76.413100,10,40,&pcenter=40.054600,-76.313100,0,-40,&key=[YOUR_KEY_HERE]

Map and Search Center on European Map Style:

/staticmap/v3/getmap?style=european&center=40.044600,-76.413100&size=360,200&zoom=6&mcenter=40.024600,-76.413100,10,40,&pcenter=40.054600,-76.313100,0,-40,&key=[YOUR_KEY_HERE]

Example demonstrating usage of all types of point of interest's

POI's placed at 4 corners clockwise :

/staticmap/v3/getmap?center=40.044600,-76.413100&size=600,200&&zoom=12&pois=1,40.044900,-76.413450|orange-100,40.044900,-76.412700|green,40.044200,-76.413450|yellow-s,40.044200,-76.412700|&key=[YOUR_KEY_HERE]

POI's placed outside 4 corners clockwise(decluttered) :

/staticmap/v3/getmap?center=40.044600,-76.413100&size=600,200&zoom=12&pois=1,40.044900,-76.413450,-40,-40|orange-100,40.044900,-76.412700,40,-40|green,40.044200,-76.413450,-40,40|yellow-s,40.044200,-76.412700,40,40|&key=[YOUR_KEY_HERE]

Example using following parameters to illustrate driving directions

  • scenter - Placed at the start of the route shape
  • ecenter - Placed at the end of the route shape
  • stops - Placed at stop point A, point B of the route
  • vias - Via point at the intersection of the shape marker
  • shape - Displays route shape composed of 4 lat/lng collection using 'delta' as shape input format.
/staticmap/v3/getmap?size=400,300&scale=324767&center=40,-80&scenter=40.0,-80.1&ecenter=40.1,-80.0&stops=A,39.9,-80.0|B,40.0,-79.9|&vias=red-circle,40.0,-80.00|&shapeformat=delta&shape=40100000,-80000000,-200000,0,100000,100000,0,-200000,&key=[YOUR_KEY_HERE]

Below static map exhibits the same shape represented using 'cmp6' as shape format having 6 digits of precision.

/staticmap/v3/getmap?size=400,300&scale=324767&center=40,-80&scenter=40.0,-80.1&ecenter=40.1,-80.0&stops=A,39.9,-80.0|B,40.0,-79.9|&vias=red-circle,40.0,-80.00|&shapeformat=cmp6&shape=_ionkA~~xqwC~reK?_ibE_ibE?~reK&key=[YOUR_KEY_HERE]

Example illustrating Auto-BestFit feature

The auto-bestfit feature is helpful when you want to place a bunch of POI's on the map but you dont know center and zoom/scale.
  • This feature will be auto-enabled if bestfit or (zoom & center) or (scale & center) is not specified and if atleast a point of interest is given in the request.
  • Auto-bestfit works with all the POI's such as mcenter,pcenter,scenter,ecenter,vias,stops,pois and xis.
  • The service will automatically arrive at the boundaries based on the POI's in the request leaving enough margin around the corners and produce a static map that will best fit the POI's.
Note:
The best fit algorithm does not take into account the offsets which inturn means there is a possibility that your points of interests fall outside the chosen best fitted map. This behavior also applies to decluttered icons when declutter is true. 
/staticmap/v3/getmap?size=690,670&pois=A,39.740112,-104.984856|orange,39.763825,-104.978539|orange,39.800931,-104.978075|orange,39.84929,-104.979308|orange,39.548777,-105.035028|orange,39.534811,-105.014489|orange,39.484608,-105.07322|orange,39.900348,-105.34506|orange,39.74176,-105.498009|orange-s,39.70717239379883,-104.9803695678711|orange-s,39.75521469116211,-105.03445816040039|orange-s,39.682132720947266,-104.87955093383789|orange-s,39.60875701904297,-104.88941192626953|orange-s,39.84825134277344,-105.06231307983398|orange-s,39.61883354187012,-104.99708938598633|orange-s,39.75290107727051,-104.88232040405273|orange-s,39.90666198730469,-105.03323364257812|orange-s,39.72735404968262,-105.1574478149414|orange-s,39.62531089782715,-104.77931594848633|orange-s,39.51768112182617,-104.9342155456543|orange-s,39.53243064880371,-104.8261489868164|orange-s,40.001121520996094,-105.25022888183594|orange-s,39.89250564575195,-104.96465301513672|orange-s,39.80877494812012,-105.13554763793945|orange-s,39.905452728271484,-105.11037063598633|orange-s,39.62358856201172,-105.0954475402832|orange-s,39.694820404052734,-104.80562210083008|orange-s,39.56029510498047,-104.73867797851562|orange-s,39.98643684387207,-105.13315963745117|orange-s,39.55867385864258,-105.30075454711914|orange-s,39.66493225097656,-105.33738327026367|orange-s,39.97106170654297,-104.96699142456055|orange-s,39.76371765136719,-104.80131149291992|orange-s,39.97116661071777,-104.80183029174805|&key=[YOUR_KEY_HERE]

Example to showing traffic flow highlight along with construction and incidents for Detroit, MI.

/staticmap/v3/getmap?size=650,600&scale=324767&center=42.331614,-83.045196&traffic=3&key=[YOUR_KEY_HERE]

Example using 'trafficstyle' parameter to draw a slim traffic flow of Detroit, MI.

/staticmap/v3/getmap?size=650,600&scale=324767&center=42.331614,-83.045196&traffic=1&trafficstyle=mobile&key=[YOUR_KEY_HERE]

Below example uses 'xis' parameter to highlight Hempfield Football ground in Landisville,PA and couple of restaurants surrounding the play field.

/staticmap/v3/getmap?size=650,541&zoom=9&center=40.090694,-76.394177&xis=www.iconarchive.com/icons/aha-soft/sport/football-48x48.png,1,BL,40.090694,-76.394177,,,-30,-55,www.iconarchive.com/icons/iconshock/food/french-fries-32x32.png,1,C,40.05034,-76.394769,www.iconarchive.com/icons/aha-soft/food/burger-48x48.png,1,BC,40.090474,-76.34659,&key=[YOUR_KEY_HERE]

Example to depict the significance of auto decluttering option.

/staticmap/v3/getmap?pois=1,39.740112,-104.984856|2,39.740112,-104.984856|3,39.708225,-104.94083|4,39.652603,-105.07765|5,39.78477,-104.9904|6,39.782925,-105.11073|7,39.7327,-105.1641|8,39.6894,-104.8283|9,39.58016,-105.13998|10,39.5829,-104.8725|11,39.8587,-104.9142|12,39.82187,-104.77188|13,39.82355,-104.77174|14,39.552574,-104.7718|15,39.9755,-104.7969|16,39.7456,-104.985|17,39.7565,-105.016|18,39.7002,-104.939|19,39.6498,-105.081|20,39.7157,-105.133|21,39.6254,-104.895|22,39.5663,-105.028|23,39.5951,-104.881|24,39.7076,-105.204|25,39.8588,-105.053|26,39.5778,-105.137|27,39.9142,-104.986|28,39.811,-104.772|29,39.5566,-104.77|30,39.9584,-105.157|31,39.971,-104.831|&size=650,606&scale=324767&center=39.704063,-105.009441&declutter=true&key=[YOUR_KEY_HERE]