Skip to content

Static Map API

Getting Started with Static Map

Map Basics

In this first example, we are going to generate a MapQuest Static Map image of Boston with retina resolution.,MA&size=@2x

map basic

Centering a Map

We used the center parameter above with a single line address to center our map on Boston. You can also use a comma-separated latitude,longitude pair to specify the center of the map.,-122.4194&size=@2x

centering a map

Zoom Levels

The zoom parameter controls magnification of the map. The parameter takes an integer value between 0 and 20. If the zoom parameter is not defined, then the default zoom level is 12.,NY&size=@2x,NY&zoom=14&size=@2x

brooklynn centered map

brooklynn zoomed centered map

Map Dimensions

The size parameter controls the dimensions and scale of the map image. The parameter takes a string of two comma-separated integers. For example: 500,400 defines a map 500 pixels wide by 400 pixels high. Maps that have a width of 500 pixels and below will display a reduced-size MapQuest logo. The minimum and maximum dimensions are defined in the table below. By default, if no size parameter is defined then a 400 pixel by 400 pixel map is returned.

ResolutionRetina (@2x)
Minimum170,30170,30 (returns 340x60 pixels)
Maximum1920,19201920,1920 (returns 3840x3840 pixels)

The size parameter also controls the scale of the map image. If the size parameter contains "@2x" then the map returns twice as many pixels while retaining the same coverage area and level of detail (i.e. the contents of the map don't change). Usually, this is called a retina image. For example, 500,400@2x defines a map 1000 pixels wide by 800 pixels high. The size parameter with just @2x defined will return a 800 pixel by 800 pixel map at 2x scale. Examples of this can be seen below.

Standard Resolution,MA&size=200,200,MA&size=400,400

boston center map size 200x200
boston center map size 400x400

Retina Resolution,MA&size=200,200@2x,MA&size=@2x

boston map size 200x200
boston map size 2x

Map Types

The type parameter controls the style of the map returned. The parameter takes a string with five possible values: map, hyb, sat, light, and dark. The parameter defaults to map. Below are examples of the various map types.,CA&zoom=14&type=map,CA&zoom=14&type=hyb,CA&zoom=14&type=sat,CA&zoom=14&type=light,CA&zoom=14&type=dark

van ness type map
van ness type hyb
van ness type sat
van ness type light
van ness type dark

Map Bounding Box

Some users might want to use a bounding box instead of a center parameter to define the area of the map. The boundingBox parameter takes two comma-separated latitude,longitude pairs, for example: 38.915,-77.072,38.876,-77.001. The first latitude,longitude specifies the upper left corner bound and the second latitude,longitude pair specifies the bottom right corner bound.,-77.072,38.876,-77.001

map bounding box

In some cases, when doing a boundingBox, changing the margin parameter can adjust the zoom level accordingly when you are out of the bounds of the map. Below is an example where the margin parameter is 100 instead of the default value of 50.,-77.072,38.876,-77.001&margin=100

bounding box margin

Add a Scale Bar to the Map

We also have a parameter that allows you to toggle a scale bar on and off. The scalebar parameter by default is set to false. When set to true, a scale bar will be visible on the map in the top left corner. You also have the option to control if the scale bar is on the bottom of the map. A single pipe character (|) followed by a position string is used to set the position of the scale bar. The acceptable position options are top and bottom. See the example requests below.|bottom

map with scalebar upper left

map with scalebar lower left

Adding Locations to the Map

It is very easy to add a location marker to a static map. Just enter a single line address or latitude,longitude pair to the locations parameter.,NY&size=@2x&key=KEY

location map

Now let's add two more of the largest cities in New York to the Map. This is done by adding two more single line addresses to the request. You separate addresses by appending two pipe characters (||) between addresses.,NY||Buffalo,NY||Rochester,NY&size=@2x&key=KEY

multiple location maps

You can also use latitude,longitude pair in addition to single line addresses in the locations parameter.,CO||Boulder,CO||39.9205,-105.0867&size=@2x&key=KEY

multiple locations map

Marker Types

You can also customize the look of your markers. We have a variety of marker types including markers, circles, vias, and flags. These markers can be customized to include text, different colors, and have different sizes. Below is a table with the various marker types and customization you can do.


marker-{size}"sm" "md" "lg"

Example: "marker-md"
marker-sm marker-md marker-lg
marker-{symbol}Any letter (letters will be capitalized) or integer from 0-999

Example: "marker-A" or "marker-100"
marker-symbol marker-number
marker-{color}Any hex value

Example: "marker-7B0099"
marker-{color1}-{color2}Any two hex values

Example: "marker-F8E71C-417505"

Any combination of various custom attributes.

Example: "marker-md-F8E71C-417505-A"

Ex. "marker-lg-7B0099-42
marker-multiple-attributes marker-multi-letter


circle-{size}"sm" "md" "lg"

Example: "circle-md"
circle-sm circle-md circle-lg
circle-{symbol}Any letter (letters will be uppercase) or integer from 0-999

Example: "circle-A" or "circle-100"
circle-A circle-number
circle-{color}Any hex value

Example: "circle-7B0099"
circle-{color1}-{color2}Any two hex values

Example: "circle-F8E71C-417505"
circle-{size}-{color1}-{color2}-{symbol}Any combination of various custom attributes.

Either one or two hex values, a size (sm, md, lg), a letter or integer between 0-999

Example: "circle-md-F8E71C-417505-A"

Ex. Example: "circle-lg-7B0099-42"
circle-multi-attributes circle-multi-number


via-{size}"sm" "md" "lg"

Example: "via-md"
via-small via-medium via-large
via-{color}Any hex value

Example: "via-7B0099"
via-{color1}-{color2}Any two hex values

Example: "via-3B5998-22407F"


flag-{size}"sm" "md" "lg"

Example: "flag-hello-sm"

Example: "flag-hello-md"

Example: "flag-lg-hello"
flag-small flag-medium flag-large
flag-{color}Any hex value

Example: "flag-7B0099"
flag-{color1}-{color2}Any two hex values

Example: "flag-3B5998-22407F"
flag-{symbols}Up to five letters, numbers, and characters except for "-" and "." (Characters will need to be URL escaped) (Letters will be capitalized)

Example: "flag-1""

Example: "flag-$99"

Example: "flag-75%25"

Example: "flag-Hello"
flag-1 flag-dollars flag-percent flag-hello

Any combination of various custom attributes.

Either one or two hex values, a size (sm, md, lg), a letter or integer between 0-999

Example: "flag-md-3B5998-22407F-food"

Example. "flag-lg-7B0099-drink"
flag-multi-attribute flag-multi-drink

Set a Default Marker for a Map

If you want to have a default marker type for all locations on your map, use the defaultMarker parameter. The defaultMarker parameter can also be set to none to hide all markers by default. If you want your markers to be numbered and incremented by default use the value "marker-num". Below is a table with the three different types of defaultMarker requests we support.

marker, circle, via, flagAny of the markers available in the icon marker circle 99 blue dot flag icon
marker-numMarkers that are incremented numerically from 1marker 1 marker 2 marker 3
noneMarkers are not displayed for locations by default.

In the below example, we have defined the default marker type to be markers with incrementing numbers.,CO||Boulder,CO||39.9205,-105.0867&size=@2x&defaultMarker=marker-num&key=KEY

marker type num

For this example, we want to show San Francisco, San Jose, and Sacramento on the map. However, we don't want to show any markers. In this case we have set the defaultMarker parameter to none.,CA||San+Jose,CA||Sacramento,CA&size=@2x&defaultMarker=none&key=KEY

map marker none

Finally, in this example, we have customized the default marker to be a medium sized light and dark blue marker using the marker customization options.,CA||San+Jose,CA||Sacramento,CA&size=@2x&defaultMarker=marker-md-3B5998-22407F&key=KEY

custom map markers

Customize Markers

You can also define custom markers for individual locations. This can be used in combination with the defaultMarker parameter.

A single pipe character (|) followed by a string after a location is used customize the marker for that location.

Example: Custom Markers for locations using | separator

In the example below, we have three custom markers on the map. The first location, New York, has a large marker with the number one. The second location, Buffalo, has a medium sized marker with the number two. The third location, Rochester, has a small marker with the number three.,NY|marker-lg-1||Buffalo,NY|marker-md-2||Rochester,NY|marker-sm-3&size=@2x&key=KEY

numbered map markers

In this example, we have a medium sized light and dark blue marker set to be our default marker. The San Jose location has a custom large sized light and dark red marker defined in its options.,CA||San+Jose,CA|marker-lg-D51A1A-A20000||Sacramento,CA&size=@2x&defaultMarker=marker-md-3B5998-22407F&key=KEY

colored markers

External Markers

The Static Map API also allows you to use markers from external sources such as CDNs. This is useful if you want to have complete control over your markers' shape or branding. This is easily done in the API by appending an image url in the options section of a location. Note that for retina static maps, your marker images will also need to be scaled by 2x or will be half sized.,NY|

external marker map

Adding a Route to the Map

Let's add a basic route between two cities to a map. The start parameter takes a single line address or latitude,longitude pair. The end parameter takes a single line address or latitude,longitude pair. Both parameters need to exist for a route to be generated.,NY&end=Washington,DC&size=@2x&key=KEY

map with route

Lets customize the start and end markers of our route to be flags instead of markers. This is done using the | character followed by the customized marker name after our start and end locations.,NY|flag-start&end=Washington,DC|flag-end&size=@2x&key=KEY

map with route and flags

We can also use the locations parameter to mark a city that might be interesting along our route.,NY|flag-start&end=Washington,DC|flag-end&locations=Philadelphia,PA&size=@2x&key=KEY

map with route and flags and pin

Creating an Arc Route

Routes can also cross oceans or simulate flight paths by using the routeArc parameter. This will create a geodesic route between our two locations. Below we have an example of a basic route with an arc, and an arc route with custom styling.,NY&end=London,England&routeArc=true&size=@2x&key=KEY,CA|via-812DD3-812DD3&end=Tokyo,JP|circle-812DD3-sm&routeArc=true&routeWidth=1&routeColor=812DD3&type=light&size=@2x&key=KEY

map arc route
map arc colored

Adding Traffic and Incidents to the Map

It's very easy to add traffic flow to a static map. For the parameter traffic set the value to flow.,CA&zoom=10&traffic=flow&size=@2x&key=KEY

traffic flow map

In addition to traffic flow, you can also show incidents and construction on the map as well. For the parameter traffic set the value to either "cons" or "inc".

If you want more than one type of traffic condition shown on the map, use the | character between condition types. Example: "traffic=flow|cons|inc",CA&zoom=10&traffic=flow|cons|inc&size=@2x&key=KEY

incidents map

Incidents and construction markers have three levels of severity (low, medium, and high).

Traffic Markers and Severity

Lowconstruction low iconincident low icon
Mediumconstruction medium iconincident medium icon
Highconstruction high iconincident high icon

Adding a Banner to the Map

Sometimes, you might want to add context to a static map. You can do so with the banner parameter. This parameter takes a url encoded text string and puts that string on a dark gray background with white text at the bottom of the image.,WA&banner=Seattle+Washington&size=@2x&key=KEY

banner map

A single pipe character (|) followed by various options can change the size, position, background color, and text color of the banner. To read about all the different options please see the banner parameter documentation. Below is an example map using the banner customization to show imaginary coffee shop locations around the Seattle area with custom markers and a small banner that uses branded colors.|sm-top-562C22-EEDFD8&locations=Seattle,WA||Tacoma,WA||Redmond,WA||Maple+Valley,WA&defaultMarker=marker-562C22&size=@2x&key=KEY

banner top map

Adding Shapes to the Map

In addition to displaying a map, you might want to highlight a specific polyline, polygon, or circle on your map. The shape parameter lets you add as many shapes as you like to your map. The shape parameter can take locations as either single line addresses or latitude,longitude coordinate pairs.

The basic format of a shape request looks like: shape=shapeStyles|location1|location2|.... Locations are separated from each other with the pipe character (|).

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.

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

Note: For compressed shapes style information must appear first, the compression type needs to be defined, and the enc:encoded_data must be the last value in the shape parameter value assignments.

The compressed format of a shape request looks like: shape=shapeStyles|compressionType|enc:encoded_data.

Example: Encoded cmp Polyline

Example: Encoded cmp6 Polyline

Example: Encoded delta Polyline

Shape Styles

Shape style 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 character (|).

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

Adding a Polyline

A polyline is a set of two or more locations on the map connected by a path. The Static Map API will connect the points as they appear in specified order from left to right.

The polyline below is a basic two point polyline between Atlanta,GA and Pensacola,FL.,GA|Pensacola,FL&size=@2x

polyline map

The example below is the same as the one above except the polyline has the border style that makes it solid red.|Atlanta,GA|Pensacola,FL&size=@2x

red polyline map

Adding a Polygon

A polygon is a set of three or more locations on the map connected by a path, the first and last location must be the same. The Static Map API will connect the points as they appear in specified order from left to right.

In the example below, we have a polygon around some Colorado cities, starting and ending in Denver,CO.,CO|Boulder,CO|Golden,CO|Denver,CO&size=@2x

polygon map

You can take polygons to the next level by stylizing them with border and fill style options. In the example below, we are highlighting the Colorado border in red with a slightly transparent white fill.|border:ff000088|36.985003,-102.041016|40.996484,-102.041016|40.979898,-109.072266|37.002553,-109.02832|36.985003,-102.041016&size=@2x

border map

Adding a Circle

A circle shape is defined as a location on the map with a radius. 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.

Below is an example of a circle that has a ten mile radius around Chicago, IL.|Chicago,IL

circle map