Static Map API

Get Map

Resource URL

Resource Information

Response Formats jpeg, jpg, jpg70, jpg80, jpg90, gif, png
Authentication Yes (Requires Key)
Rate Limited Yes

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, or start & end required

    A center point for the map image.

    Note: boundingBox will override center.

    Example: Lat,Lng Coordinates


    Example: Single Line Address


  • boundingBox optional, at least one parameter center, boundingBox, locations, shape, or start & end 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.



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



  • zoom optional, default is 12

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



  • format optional, default is jpg70

    The image format of the map. Available formats are png, jpeg, jpg, jpg70, jgp80, jpg90, and gif.



  • type optional, default is map

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



  • scalebar optional, default is false

    Show a scale bar on the top of the map.




    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


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, or start & end required

    A list of locations you want to put on your static map. Locations can be Latitude,Longitude Coordinates or Single Line Addresses.

    Multiple Locations in the List

    Twos pipe characters || separate locations in the list

    Example: Three single line addresses


    Example: Mixed Lat,Lng Coordinates and Single Line Address



    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


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



  • defaultMarker optional

    By default, a dark gray marker is put on every location in your list. You can use the defaultMarker parameter to override this default behavior. You can also set the default marker to none if you don't want markers highlighting the locations on your map.

    Example: Large Red Markers


    Example: Hex Blue Small Circles


    Example: Hide Markers


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



    Banners can have custom sizes, positions, background colors, and text colors. 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


    Position: bottom, top

    Example: Banner on top of map


    Banner Color: Any Hex Value

    Example: Red banner with default white text


    Text Color: Any hex value

    (requires banner color to be defined first).

    Example: Red banner with black text


    Combining Options

    Example: Large Red banner with black text on the top of the Map


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 locations as either single line addresses or latitude,longitude coordinate pairs.

    Example: Lat,Lng Coordinates


    Example: Single Line Address


  • 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 locations as either single line addresses or latitude,longitude coordinate pairs.

    Example: Lat,Lng Coordinates


    Example: Single Line Address


  • session optional

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



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



  • routeWidth optional, default is 4.

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



  • 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):


    Example (32-bit hex):


    Example (r,g,b):


    Example (r,g,b,a):


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, incidents, and construction pertaining to the requested map location.


    A single pipe character | is used to separate the accepted values

    Accepted values are:

    • flow - traffic flow lines
    • con - road construction
    • inc - traffic incidents


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, or start & end 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 single line addresses or latitude,longitude coordinate pairs.


    Example: Polyline Lat,Lng Coordinates


    Example: Polyline Single Line Address


    Example: Polygon Lat,Lng Coordinates


    Example: Polygon Single Line Address


    Example: Circle Lat,Lng Coordinates


    Example: Circle Single Line Address


    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.


    • 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


    Example: Encoded cmp6 Polyline


    Example: Encoded delta Polyline


    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


    Example: Thick black line, blue fill 50% opacity


Example Request: Shapes


Example Response Image: Shapes

Formatting Locations

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

Format Example
city (AA5), state (AA3) Denver, CO
city, state, postalCode Denver, CO, 80202
postalCode 80202
street, city, state 1555 Blake St, Denver, CO
street, city, state, postalCode 1555 Blake St, Denver, CO 80202
street, postalCode 1555 Blake St, 80202
Latitude,Longitude 39.750307,-104.999472