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
| Parameter | Description | Required |
|---|---|---|
| key | The API Key, which is needed to make requests to MapQuest services. | Yes |
| size | 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. 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 |
| center | 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 | no, at least one parameter center, boundingBox, locations, shape, start & end, or session required |
| boundingBox | 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 | no, at least one parameter center, boundingBox, locations, shape, start & end, or session required |
| margin | 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 | no, default is 50 |
| zoom | The zoom level of the map. Integers between 0 and 20. Example: zoom=7 | no, default is 12 |
| format | 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 | no, default is jpg |
| type | The type of base map tiles on the map. The options are map, hyb, sat, light, and dark. Example: type=dark | no, default is map |
| scalebar | 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 | no, default is false |
Example Request: Basic Map
GET https://www.mapquestapi.com/staticmap/v5/map?key=KEY¢er=Boston,MA&size=600,400@2x
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
| Parameter | Description | Required |
|---|---|---|
| locations | 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 | no, at least one parameter center, boundingBox, locations, shape, start & end, or session required |
| declutter | 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 | no, default is false |
| defaultMarker | 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 | no |
Example Request: Locations
Example Response Image: Locations
Example Request: Marker Customization
Example Response Image: Marker Customization
Adding a Banner to the Map
| Parameter | Description | Required |
|---|---|---|
| banner | 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 | no |
Example Request: Banner
Example Response Image: Banner
Adding a Route to the Map
| Parameter | Description | Required |
|---|---|---|
| start | 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 | no, start and end parameters are required to make a route request. |
| end | 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 | no, start and end parameters are required to make a route request. |
| session | Specifies a session ID from a route made with the MapQuest Directions API. Example: session=SESSION_ID | no |
| routeArc | 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 | no, default is false |
| routeWidth | The routeWidth parameter controls the pixel width of the route. The width must be an integer. Example: routeWidth=5 | no, default is 4. |
| routeColor | 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 | no, default is 5882FA |
Example Request: Routing
Example Response Image: Routing
Example Request: Arc Route
Example Response Image: Arc Route
Adding Traffic and Incidents to the Map
| Parameter | Description | Required |
|---|---|---|
| traffic | 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:
traffic=flow|con|inc Example: only flow traffic=flow | no |
Example Request: Traffic
Example Response Image: Traffic
Adding Polygons, Polylines, and Circles to the Map
| Parameter | Description | Required |
|---|---|---|
| shape | 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
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
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 |