Open Static Map API

GET
Static Map

Open Static Map Service lets you request a map of a specified size to be centered on a latitude/longitude at a particular zoom level.

Resource URL

http://www.mapquestapi.com/staticmap/v4/getmap

Resource Information

Response Formats jpeg, jpg, gif, png
Authentication Yes (Requires Key)
Rate Limited Yes

URL Parameters

Request Parameter Description Required?
key
String
The API Key, which is needed to make requests to MapQuest services. Yes
center
Lat/Lng Coordinates
A center point for the map image.

Example:

40.039401,-76.307078

Yes, if the bestfit parameter is not present and no POIs are present
bestfit
Two Lat/Lng Coordinates
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.

Example:

40.063175,-76.734664,39.960338,-76.306892

Yes, if the center parameter is not present and no POIs are present

Note: bestfit will override center
zoom
Integer
Specifies zoom level for the map image.

See Zoom to Scale Mapping for information on scales versus zoom levels.
Yes, if the center parameter is present, the scale parameter is not present, and no POIs are present

Note: zoom overrides scale
scale
Integer
Specifies display scale for map image.

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
size
Integer Pair
Specifies the dimension of the map image requested. The width and height values cannot be larger than 3840.

Example: 400,200
Yes
margin
Integer
In some cases when doing a bestfit, changing the margin can adjust the zoom level accordingly when you are out of the bounds of the map.

Default: 50
No
imagetype
String
Specifies the output image format. Available formats:
  • jpeg
  • jpg
  • gif
  • png
Default: jpg
No
type
String
Specifies map mode. Available formats:
  • map
  • sat (Satellite)
  • hyb (Hybrid)
Default: map
No
pois Specifies a list of points of interests to add to the map. 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
Example:

pois=LABEL1,LAT1,LNG1,OFFX1,OFFY1|...|LABELN,LATN,LNGN,OFFXN,OFFYN

Offsets are optional

Advanced URL Parameters

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

  • 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.
  • Auto-bestfit and auto-decluttering

Note: All advanced parameters are optional.

Request Parameter Description Accepted Values
mcenter Specifies center point to place a star icon.

Example: 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.

Example: 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.

Example:

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.

Default: false

Example: 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.
shapeformat Specifies the input format of the shape parameter.

Example: 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.

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 of the collection should relies on the value of the shapeformat parameter.

See the shapeformat parameter for more information.

Example: shape=LATLNGCOLLECTION
Accepted values are collections of latitude/longitude pairs.

The format of these values can differ depending on the shapeformat value set.
polyline Draws a line composed of one or more line segments.

Example: polyline=color:|width:|latlngs
See the Shape Support section for details on this parameter.
polygon Draws a polygon.

Example: polyline=color|width|fill|latlngs
See the Shape Support section for details on this parameter.
ellipse Draws an ellipse.

Example: ellipse=color|width|fill|latlngs
See the Shape Support section for details on this parameter.
scenter Specifies a point to place a route start icon.

Example: 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.

Example: 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.

Example:

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.

Example:

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.

Example: session=SESSIONID
A valid session ID
scalebar Specify whether a scalebar should be displayed

Example: scalebar=SCALEBAR
Accepted values are:
  • true
  • false
Default: true
scalebarPos Specifies location of scalebar

Example: scalebarPos=SCALEBARPOS
Accepted values are:
  • top - top left hand corner
  • bottom - bottom left hand corner
Default: bottom

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. The format is:

xis=URI,COUNT,ALIGN,LAT,LNG,TWKOFFX,TWKOFFY,OFFX,OFFY

If the same icon will be used in different 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 Required?
uri The URL to the image with or without the leading HTTP protocol string. SSL images are not supported and the path cannot contain a comma. The icon can be a jpg, png, or gif image and the size is limited to 64px x 64px.

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: http://developer.mapquest.com/api-docs/doc/images/money_sign.jpg
Yes
count An integer for how many times the particular image will be used on the map. Yes
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: C
Yes
lat The latitude of the icon. Yes
lng The longitude of the icon. Yes
offx This is the offset of the icon on the x axis. No
offy This is the offset of the icon on the y axis. No
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. No
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. No

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.

Shape Support

The static map API also supports three geometric primitive parameters – polyline, polygon, and ellipse. The values for all three parameters are specified using the following format:

polyline=style1:value|style2:value|latlngs

Property Description
color 24 bit or 32 bit hex value. Bits 24-31 specify the alpha component, the red component in bits 16-23, green component in 8-15, and the blue in 0-7. An example being 0x77ff0000.
width An integer value specifying the width of the path.
fill Fill color for closed primitives. See color property above for format.
raw|cmp|cmp6 List of lat/lng pairs in accordance with the shape and shapeformat parameters. For ellipses points are the upper-left and lower-right points of the bounding rectangle.

Default: raw

Example Request: Basic Map

GET

https://open.mapquestapi.com/staticmap/v4/getmap?key=KEY&size=600,400&zoom=13&center=47.6062,-122.3321

Example Response: Basic Map

Example Request: POIs

GET

https://open.mapquestapi.com/staticmap/v4/getmap?key=KEY&size=600,400&type=map&imagetype=png&pois=1,40.0986,-76.3988,-20,-20|2,40.0692,-76.4012|3,40.0981,-76.3461|4,40.0697,-76.352

Example Response: POIs

Example Request: Route

GET

https://open.mapquestapi.com/staticmap/v4/getmap?key=KEY&size=600,400&type=map&imagetype=png&declutter=false&shapeformat=cmp&shape=uajsFvh}qMlJsK??zKfQ??tk@urAbaEyiC??y]{|AaPsoDa~@wjEhUwaDaM{y@??t~@yY??DX&scenter=40.0337,-76.5047&ecenter=39.9978,-76.3545

Example Response: Route