Skip to content

Static Map API

GET MAP

Resource URL

https://www.mapquestapi.com/staticmap/v5/map

Resource Information

Response Formatsjpeg, jpg, jpg70, jpg80, jpg90, gif, png
AuthenticationYes (Requires Key)
Rate LimitedYes

Request Parameters

Basic Parameters

ParameterDescriptionRequired
keyThe API Key, which is needed to make requests to MapQuest services.Yes
sizeSpecifies the dimensions of the map image, in pixels. If you want a retina image, append @2x to the parameter after the comma-separated integers. If you just want retina resolution at the default size, just append @2x to the size parameter.

Width: minimum 170px, maximum 1920px
Height: minimum 30px, maximum 1920px

Example: Size
size=width,height (size=500,400)
Example: Retina Size
size=width,height@2x (size=500,400@2x)
no, the default size is 400,400
centerA center point for the map image. Can be either a single line address or a latitude,longitude pair.

Note: boundingBox will override center.

Example: latitude,longitude Coordinates
center=40.039401,-76.307078

Example: Single Line Address
center=Denver,CO
no, at least one parameter center, boundingBox, locations, shape, start & end, or session required
boundingBoxIf 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.

Note: boundingBox will override center.

Example:
boundingBox=40.06,-76.73,39.96,-76.30
no, at least one parameter center, boundingBox, locations, shape, start & end, or session required
marginIn some cases when doing a boundingBox, changing the margin can adjust the zoom level accordingly when you are out of the bounds of the map.

Example:
margin=100
no, default is 50
zoomThe zoom level of the map. Integers between 0 and 20.

Example:
zoom=7
no, default is 12
formatThe image format of the map. Available formats are png, jpeg, jpg, jpg70 (70% quality), jpg80 (80% quality), jpg90 (90% quality), and gif.

Example:
format=png
no, default is jpg
typeThe type of base map tiles on the map. The options are map, hyb, sat, light, and dark.

Example:
type=dark
no, default is map
scalebarShow a scale bar on the top of the map.

Example:
scalebar=true

Options:
To change the position of the the scale bar on the map, append a single pipe character | followed by a position string to the end of the scalebar parameter. See the example below.

Example: Bottom scale bar
scalebar=true|bottom
no, default is false

Example Request: Basic Map

GET https://www.mapquestapi.com/staticmap/v5/map?key=KEY&center=Boston,MA&size=600,400@2x

Example Response Image: Basic Map

basic map boston

Example Request: Map with Zoom and Type

GET https://www.mapquestapi.com/staticmap/v5/map?key=KEY&center=San+Francisco,CA&zoom=10&type=hyb&size=600,400@2x

Example Response Image: Map with Zoom and Type

map with zoom and type

Adding Locations to the Map

ParameterDescriptionRequired
locationsA list of locations you want to put on your static map. Locations can be Latitude,Longitude Coordinates or a single line address.

Multiple Locations in the List

Two pipe characters || separate locations in the list.
Example: Three single line addresses
locations=Denver,CO||Boulder,CO||Broomfield,CO
Example: Mixed latitude,longitude Coordinates and Single Line Address
locations=Denver,CO||Boulder,CO||39.9205,-105.0867

Options:
A single pipe character | followed by a string after a location is used to customize the icon for that location. Refer to the Getting Started guide for more information about all the possible custom MapQuest icons. In addition, external icons can also be used by entering the URL after the |. To hide an icon, enter "none" after the |.

Example: Custom Markers for locations using | separator
locations=Denver,CO|marker-red||Boulder,CO|marker-green

Example: External Marker for a location using | separator
locations=Denver,CO|/documentation/assets/img/apple-icon-152x152.png

Example: No Marker for a location using | separator
locations=Denver,CO|none
no, at least one parameter center, boundingBox, locations, shape, start & end, or session required
declutterWhen locations are too close to each other they can be lost or partially overlapped.

With declutter set to true, the service finds the best possible decluttered position for each location and places it on the map so that it does not overlap with any other location.

Example:
declutter=true
no, default is false
defaultMarkerBy default, a dark gray marker is placed on every location in your list. You can use the defaultMarker parameter to override this behavior. You can also set the default marker to none if you don't want markers highlighting the locations on your map. Refer to the Getting Started guide for more information about all the possible custom MapQuest icons.

Example: Large Red Markers
defaultMarker=marker-red-lg

Example: Hex Blue Small Circles
defaultMarker=circle-3B5998-sm

Example: Hide Markers
defaultMarker=none
no

Example Request: Locations

GET https://www.mapquestapi.com/staticmap/v5/map?locations=New+York,NY||Buffalo,NY||Rochester,NY&size=600,400@2x&key=KEY

Example Response Image: Locations

map locations

Example Request: Marker Customization

GET https://www.mapquestapi.com/staticmap/v5/map?key=KEY&locations=San+Francisco,CA||San+Jose,CA|marker-lg-A20000-D51A1A||Sacramento,CA&size=@2x&defaultMarker=marker-sm-22407F-3B5998&size=600,400@2x

Example Response Image: Marker Customization

marker customization

Adding a Banner to the Map

ParameterDescriptionRequired
bannerSometimes you might want to describe what is visible on a map to add context. By default the banner parameter will show a dark gray background with white text at the bottom of the image.

Example: Default banner
banner=Coffee+Shops

Options:

Banners can be customized with three different sizes, two positions, background color, and text color. To customize a banner, add a single pipe character | followed by an options string after the banner's text string. Multiple options can be separated by a dash -. Below are some example banner customizations.

Banner Size: sm (small), md (medium), lg (large)

Example: Large banner
banner=Coffee+Shops|lg

Position: bottom, top

Example: Banner on top of map
banner=Coffee+Shops|top

Banner Color: Any Hex Value

Example: Red banner with default white text
banner=Coffee+Shops|A0021B

Text Color: Any hex value

(requires banner color to be defined first).

Example: Red banner with black text
banner=Coffee+Shops|A0021B-000000

Combining Options

Example: Large Red banner with black text on the top of the Map
banner=Coffee+Shops|lg-top-A0021B-000000
no

Example Request: Banner

GET https://www.mapquestapi.com/staticmap/v5/map?locations=New+York,NY||Buffalo,NY||Albany,NY&size=600,400@2x&key=KEY&banner=Large+Cities+in+New+York

Example Response Image: Banner

map banner new york

Adding a Route to the Map

ParameterDescriptionRequired
startThe starting point of a route request. The start parameter can take a location as either a single line address or a latitude,longitude coordinate pair.

A single pipe character | followed by a string after a location is used to customize the icon for that location. Refer to the Getting Started guide for more information about all the possible custom MapQuest icons. In addition, external icons can also be used by entering the URL after the |. To hide an icon, enter "none" after the |.

Example: latitude,longitude Coordinates
start=40.039401,-76.307078

Example: Single Line Address
start=Denver,CO

Example: Single Line Address with Options
start=Denver,CO|flag-start
no, start and end parameters are required to make a route request.
endThe ending point of a route request. The end parameter can take a location as either a single line address or a latitude,longitude coordinate pair.

A single pipe character | followed by a string after a location is used to customize the icon for that location. Refer to the Getting Started guide for more information about all the possible custom MapQuest icons. In addition, external icons can also be used by entering the URL after the |. To hide an icon, enter "none" after the |.

Example: latitude,longitude Coordinates
end=41.039401,-76.307078

Example: Single Line Address
end=Boulder,CO

Example: Single Line Address with Options
end=Boulder,CO|flag-end
no, start and end parameters are required to make a route request.
sessionSpecifies a session ID from a route made with the MapQuest Directions API.

Example:
session=SESSION_ID
no
routeArcThis parameter specifies that the route should be geodesic (the shortest distance between two points on a sphere) instead of a driving route. This is useful when charting plane routes, long routes, or if you don't want to use our Directions API. Default routeWidth for an arc route is 2.

Example:
routeArc=true
no, default is false
routeWidthThe routeWidth parameter controls the pixel width of the route. The width must be an integer.

Example:
routeWidth=5
no, default is 4.
routeColorSpecify a 24-bit or 32-bit hex color, or a comma-separated rgb or rgba color for the route.

When a 32-bit hex value is specified, the last two characters specify the 8-bit alpha transparency value. This value varies between 00 (completely transparent) and FF (completely opaque).

Example (24-bit hex):
routeColor=812DD3

Example (32-bit hex):
routeColor=812DD396

Example (r,g,b):
routeColor=10,100,200

Example (r,g,b,a):
routeColor=10,100,200,150
no, default is 5882FA

Example Request: Routing

GET https://www.mapquestapi.com/staticmap/v5/map?start=New+York,NY&end=Washington,DC&size=600,400@2x&key=KEY

Example Response Image: Routing

routing image

Example Request: Arc Route

GET https://www.mapquestapi.com/staticmap/v5/map?start=San+Francisco,CA&end=Tokyo,JP&routeArc=true&size=600,400@2x&key=KEY

Example Response Image: Arc Route

arc route image

Adding Traffic and Incidents to the Map

ParameterDescriptionRequired
trafficSpecifies the inclusion of traffic data such as flow (the colored lines on streets), incidents, and construction for the requested map location.

Options

A single pipe character | is used to separate the accepted values. You can have any combination of these options set for a traffic request.

Accepted values are:
  • flow - traffic flow lines
  • con - road construction
  • inc - traffic incidents
Example: all traffic information
traffic=flow|con|inc

Example: only flow
traffic=flow
no

Example Request: Traffic

GET https://www.mapquestapi.com/staticmap/v5/map?center=Los+Angeles,CA&zoom=10&traffic=flow|cons|inc&size=600,400@2x&key=KEY

Example Response Image: Traffic

traffic map

Adding Polygons, Polylines, and Circles to the Map

ParameterDescriptionRequired
shapeThe shape parameter defines a set of locations connected by a path to overlay above the map. The shape parameter can take locations as either a single line address or a latitude,longitude coordinate pair.

shape=shapeStyles|location1|location2|...

Example: Polyline latitude,longitude Coordinates
shape=40,-76|39,-74

Example: Polyline Single Line Address
shape=Denver,CO|Boulder,CO

Example: Polygon latitude,longitude Coordinates
shape=40,-76|39,-74|39,-76|40,-76

Example: Polygon Single Line Address
shape=Denver,CO|Boulder,CO|Golden,CO|Denver,CO

Example: Circle latitude,longitude Coordinates
shape=radius:100km|40.039401,-76.307078

Example: Circle Single Line Address
shape=radius:10mi|Denver,CO

For circle shapes, the radius: value must be specified. The units of radius is either mi (miles) or km (kilometers). If no unit is specified, the default unit is km.

Compressed Shapes

Instead of a series of locations, you may instead declare a path as an encoded shape by using the enc: prefix within the location declaration. You must also define the compressionType from the list below.

Note: For compressed shapes, the enc:encoded_data must be the last value in the shape parameter value assignments.

shape=shapeStyles|compressionType|enc:encoded_data
  • 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.
  • delta - First shape point is represented in multiples of 106 and subsequent points is given as difference from previous point.
Example: Encoded cmp Polyline
shape=cmp|enc:_ocsF~vznM~hbE_seK

Example: Encoded cmp6 Polyline
shape=cmp6|enc:__lhkA~nt}oC~b`|@_gayB

Example: Encoded delta Polyline
shape=delta|enc:40100000,-80000000,-200000,0,100000,100000,0,-200000

Shape Styles:

Shapes can be customized with border weight, border color, and fill color. The set of style descriptors is a series of value assignments separated by the pipe (|).

weight: (optional) specifies the thickness of the path in pixels. If no weight parameter is set, the path will have a default thickness of 3 pixels.

border: (optional) specifies the color of the path in a 24-bit (example: 812DD3) or 32-bit (example: 812DD3CC) hex color. If no border parameter is set, the path will have a default color of 5882fa.

fill: (optional) specifies the fill color of a polygon or circle in a 24-bit (example: 812DD3) or 32-bit (example: 812DD3CC) hex color. If no fill parameter is set, the fill will be transparent.

Example: Thin red line
shape=weight:2|border:ff0000|40,-76|39,-74

Example: Thick black line, blue fill 50% opacity
shape=weight:5|fill:0000ff80|border:000000|40,-76|39,-74|39,-76|40,-76
no, at least one parameter center, boundingBox, locations, shape, start & end, or session required

Example Request: Shapes

GET https://www.mapquestapi.com/staticmap/v5/map?key=KEY&shape=Disney+World|width:7mi|weight:4&shape=28,-81|28,-80.25|27.25,-80.25|27.25,-81|28,-81|fill:ffffff88|border:ff000088&shape=border:333333|weight:5|cmp|enc:encoded_data&size=600,400@2x

Example Response Image: Shapes

image shapes

Formatting Locations

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

FormatExample
city (AA5), state (AA3)Denver, CO
city, state, postalCodeDenver, CO, 80202
postalCode80202
street, city, state1555 Blake St, Denver, CO
street, city, state, postalCode1555 Blake St, Denver, CO 80202
street, postalCode1555 Blake St, 80202
Latitude,Longitude39.750307,-104.999472

More Resources