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 10⁶ 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`

Open Static Map API

Resource URL

Resource Information

URL Parameters

Advanced URL Parameters

Custom Icons

Shape Support

Example Request: Basic Map

Example Response: Basic Map

Example Request: POIs

Example Response: POIs

Example Request: Route

Example Response: Route