Static Map API

Request Parameters

• Basic Parameters

• key required

  The API Key, which is needed to make requests to MapQuest services.

• size optional, the default size is 400,400

  Specifies 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.

  	Minimum	Maximum
  Width	170 (pixels)	1920 (pixels)
  Height	30 (pixels)	1920 (pixels)

  Example: Size

  size=width,height (size=500,400)

  Example: Retina Size

  size=width,height@2x (size=500,400@2x)

• center optional, at least one parameter center, boundingBox, locations, shape, start & end, or session required

  A 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

• boundingBox optional, at least one parameter center, boundingBox, locations, shape, start & end, or session required

  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.

  Note: boundingBox will override center.

  Example:

  boundingBox=40.06,-76.73,39.96,-76.30

• margin optional, default is 50

  In 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

• zoom optional, default is 12

  The zoom level of the map. Integers between 0 and 20.

  Example:

  zoom=7

• format optional, default is jpg

  The 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

• type optional, default is map

  The type of base map tiles on the map. The options are map, hyb, sat, light, and dark.

  Example:

  type=dark

• scalebar optional, default is false

  Show 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

Example Request: Basic Map

Example Response Image: Basic Map

Example Request: Map with Zoom and Type

Example Response Image: Map with Zoom and Type

• Adding Locations to the Map

• locations optional, at least one parameter center, boundingBox, locations, shape, start & end, or session required

  A 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

• declutter optional, default is false

  When 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

• defaultMarker optional

  By 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

Example Request: Locations

Example Response Image: Locations

Example Request: Marker Customization

Example Response Image: Marker Customization

• Adding a Banner to the Map

• banner optional

  Sometimes 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

Example Request: Banner

Example Response Image: Banner

• Adding a Route to the Map

• start optional, start and end parameters are required to make a route request.

  The 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

• end optional, start and end parameters are required to make a route request.

  The 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

• session optional

  Specifies a session ID from a route made with the MapQuest Directions API.

  Example:

  session=SESSION_ID

• routeArc optional, default is false

  This 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

• routeWidth optional, default is 4.

  The routeWidth parameter controls the pixel width of the route. The width must be an integer.

  Example:

  routeWidth=5

• routeColor optional, default is 5882FA

  Specify 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

Example Request: Routing

Example Response Image: Routing

Example Request: Arc Route

Example Response Image: Arc Route

• Adding Traffic and Incidents to the Map

• traffic optional

  Specifies 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

Example Request: Traffic

Example Response Image: Traffic

• Adding Polygons, Polylines, and Circles to the Map

• shape optional, at least one parameter center, boundingBox, locations, shape, start & end, or session required

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

Example Request: Shapes

Example Response Image: Shapes

Formatting Locations

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

More Resources