Open Static Map Service Developer's Guide

The Open Static Map Service enables a user to create static map images that are generated by a simple HTTP request.

Please 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.039401,-76.307078 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.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
margin 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 is 50. No
size Specifies the dimension of the map image requested.
Note: Width and height values cannot be larger than 3840
400,200 Yes
zoom Specifies zoom level for the map image. A valid zoom integer. 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 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:
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:

  • 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 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.
polyline Draws a line composed of one or more line segments. polyline=color:|width:|latlngs See the Shape Support section for details on this parameter.
polygon Draws a polygon. polyline=color|width|fill|latlngs See the Shape Support section for details on this parameter.
ellipse Draws an ellipse. 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. 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
scalebar Specify whether a scalebar should be displayed scalebar=SCALEBAR Accepted values are:
  • true
  • false
Default is "true"
scalebarPos Specifies location of scalebar scalebarPos=SCALEBARPOS Accepted values are:
  • top (top left hand corner)
  • bottom (bottom left hand corner)
Default is "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. 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 with or 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 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: /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.

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. If the shapeformat is not provided it defaults to raw.

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:
polyline:
polygon:
ellipse
scenter:
ecenter:

Static Maps by Place

In addition to using latitude/longitude points, 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. Single-line locations and lat/lngs are available for the United States and international. 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"}
lat,lng 40.039401,-76.307078

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 or a lat/lng for the map image to be centered over. See Specifying Locations for details on correct ways of formatting single-line addresses. Lancaster,PA OR 40.273602,-76.884697 Yes
size Specifies the dimension of the map image requested.
Note: Width and height values cannot be larger than 3840
400,200 Yes
zoom Specifies a zoom level for the map image. A valid zoom integer. See Zoom to Scale Mapping for information on scales versus zoom levels 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:

OpenStreetMap data is licensed under the Open Data Commons Open Database License (ODbL).

  © MapQuest, Inc. All rights reserved.    Privacy Policy | Terms of Use