Render - Get Map Image

The static image service renders a user-defined, rectangular image containing a map section using a zoom level from 0 to 20.

The supported resolution range for the map image is from 1x1 to 8192x8192.

If you are deciding when to use the static image service over the map tile service, you may want to consider how you would like to interact with the rendered map. If the map contents will be relatively unchanging, a static map is a good choice. If you want to support a lot of zooming, panning and changing of the map content, the map tile service would be a better choice.

Note : Either center or bbox parameter must be supplied to the API. The supported Lat and Lon ranges when using the bbox parameter, are as follows:

Zoom Level Max Lon Range Max Lat Range
0 360.0 170.0
1 360.0 170.0
2 360.0 170.0
3 360.0 170.0
4 360.0 170.0
5 180.0 85.0
6 90.0 42.5
7 45.0 21.25
8 22.5 10.625
9 11.25 5.3125
10 5.625 2.62625
11 2.8125 1.328125
12 1.40625 0.6640625
13 0.703125 0.33203125
14 0.3515625 0.166015625
15 0.17578125 0.0830078125
16 0.087890625 0.0415039063
17 0.0439453125 0.0207519531
18 0.0219726563 0.0103759766
19 0.0109863281 0.0051879883
20 0.0054931641 0.0025939941
GET https://atlas.microsoft.com/map/static/png?subscription-key={subscription-key}&api-version=1.0
GET https://atlas.microsoft.com/map/static/png?subscription-key={subscription-key}&api-version=1.0&layer={layer}&style=main&zoom={zoom}&center={center}&bbox={bbox}&height={height}&width={width}&language={language}

URI Parameters

Name In Required Type Description
format
path True

Desired format of the response. Possible value: png.

subscription-key
query True
  • string

Azure Maps subscription key

api-version
query True
  • string

Version number of Azure Maps API. Current version is 1.0

layer
query

Map layer requested. If layer is set to labels or hybrid, the format should be png.

style
query
  • string

Map style to be returned. Currently, only style available is main.

zoom
query
  • integer

Desired zoom level of the map. Zoom value must be in the range: 0-20 (inclusive). Default value is 12.

Please see Zoom Levels and Tile Grid for details.

center
query
  • string

Coordinates of the center point. Format: 'lon,lat'. Projection used - EPSG:3857. Longitude range: -180 to 180. Latitude range: -85 to 85. Note: Either center or bbox are required parameters. They are mutually exclusive.

bbox
query
  • string

Bounding box. Projection used - EPSG:3857. Format : 'minLon, minLat, maxLon, maxLat'. Note: Either bbox or center are required parameters. They are mutually exclusive. It shouldn’t be used with height or width. The maximum allowed ranges for Lat and Lon are defined for each zoom level in the table at the top of this page.

height
query
  • integer

Height of the resulting image in pixels. Range is 1 to 8192. Default is 512. It shouldn’t be used with bbox.

width
query
  • integer

Width of the resulting image in pixels. Range is 1 to 8192. Default is 512. It shouldn’t be used with bbox.

language
query
  • string

Language in which search results should be returned. Should be one of supported IETF language tags, case insensitive. When data in specified language is not available for a specific field, default language is used.

Please refer to Supported Languages for details.

Responses

Name Type Description
200 OK
  • string

OK

Media Types: "image/png", "application/json"

400 Bad Request

Bad request: one or more parameters were incorrectly specified or are mutually exclusive.

Media Types: "image/png", "application/json"

401 Unauthorized

Access denied due to invalid subscription key. Make sure to provide a valid key for an active subscription.

Media Types: "image/png", "application/json"

403 Forbidden

Permission, capacity, or authentication issues.

Media Types: "image/png", "application/json"

404 Not Found

Not Found: the requested resource could not be found, but it may be available again in the future.

Media Types: "image/png", "application/json"

500 Internal Server Error

An error occurred while processing the request. Please try again later.

Media Types: "image/png", "application/json"

Examples

GetMapStaticImage

Sample Request

GET https://atlas.microsoft.com/map/static/png?subscription-key=[subscription-key]&api-version=1.0&layer=basic&style=main&zoom=2&bbox=1.355233,42.982261,24.980233,56.526017

Sample Response

"binary string image"
{
  "error": {
    "code": "400 BadRequest",
    "message": "Bad request: one or more parameters were incorrectly specified or are mutually exclusive."
  }
}
{
  "error": {
    "code": "401 Unauthorized",
    "message": "Access denied due to invalid subscription key. Make sure to provide a valid key for an active subscription."
  }
}
{
  "error": {
    "code": "403 Forbidden",
    "message": "Permission, capacity, or authentication issues."
  }
}
{
  "error": {
    "code": "404 NotFound",
    "message": "Not Found: the requested resource could not be found, but it may be available again in the future."
  }
}
{
  "error": {
    "code": "500 InternalServerError",
    "message": "An error occurred while processing the request. Please try again later."
  }
}

Definitions

Error

This object is returned when an error occurs in the Maps API

ErrorResponse

This response object is returned when an error occurs in the Maps API

RasterTileFormat

Desired format of the response. Possible value: png.

StaticMapLayer

Map layer requested. If layer is set to labels or hybrid, the format should be png.

Error

This object is returned when an error occurs in the Maps API

Name Type Description
code
  • string

The HTTP status code.

message
  • string

If available, a human readable description of the error.

ErrorResponse

This response object is returned when an error occurs in the Maps API

Name Type Description
error

This object is returned when an error occurs in the Maps API

RasterTileFormat

Desired format of the response. Possible value: png.

Name Type Description
png
  • string

An image in the png format. Supports zoom levels 0 through 18.

StaticMapLayer

Map layer requested. If layer is set to labels or hybrid, the format should be png.

Name Type Description
basic
  • string

Returns an image containing all map features including polygons, borders, roads and labels.

hybrid
  • string

Returns an image containing borders, roads, and labels, and can be overlaid on other tiles (such as satellite imagery) to produce hybrid tiles.

labels
  • string

Returns an image of just the map's label information.