Static Map API

GET
Map

Resource URL

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

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, 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

GET

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

Example Response Image: Basic Map

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

  • 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

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

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

  • 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

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

  • 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

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

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

  • 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

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

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

Example Request: Shapes

GET

https://www.mapquestapi.com/staticmap/v5/map?key=KEY&shape=Disney+World%7Cwidth: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

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