Render - Get Map Image

Applies to: S0 and S1 pricing tiers.

The static image service renders a user-defined, rectangular image containing a map section using a zoom level from 0 to 20. 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.

Service also provides Image Composition functionality to get a static image back with additional data like; pushpins and geometry overlays with following S0 and S1 capabilities.

In S0 you can:

  • Render up to 5 pushpins specified in the request
  • Provide one custom image for the pins referenced in the request
  • Add labels to the pushpins

In S1 you can:

Please see How-to-Guide for detailed examples.

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?api-version=1.0
GET https://atlas.microsoft.com/map/static/png?subscription-key={subscription-key}&api-version=1.0&pins={pins}&path={path}&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
  • string

One of the Azure Maps keys provided from an Azure Map Account. Refer to the subscription-key security definition.

api-version
query True
  • string

Version number of Azure Maps API. Current version is 1.0

pins
query
  • array

Pushpin style and instances. Use this parameter to optionally add pushpins to the image. The pushpin style describes the appearance of the pushpins, and the instances specify the coordinates of the pushpins and optional labels for each pin. (Be sure to properly URL-encode values of this parameter since it will contain reserved characters such as pipes and punctuation.)

The Azure Maps account S0 SKU only supports a single instance of the pins parameter. Other SKUs allow multiple instances of the pins parameter to specify multiple pin styles.

To render a pushpin at latitude 45°N and longitude 122°W using the default built-in pushpin style, add the querystring parameter

pins=default||-122 45

Note that the longitude comes before the latitude. After URL encoding this will look like

pins=default%7C%7C45+-122

All of the examples here show the pins parameter without URL encoding, for clarity.

To render a pin at multiple locations, separate each location with a pipe character. For example, use

pins=default||-122 45|-119.5 43.2|-121.67 47.12

The S0 Azure Maps account SKU only allows five pushpins. Other account SKUs do not have this limitation.

Style Modifiers

You can modify the appearance of the pins by adding style modifiers. These are added after the style but before the locations and labels. Style modifiers each have a two-letter name. These abbreviated names are used to help reduce the length of the URL.

To change the color of the pushpin, use the 'co' style modifier and specify the color using the HTML/CSS RGB color format which is a six-digit hexadecimal number (the three-digit form is not supported). For example, to use a deep pink color which you would specify as #FF1493 in CSS, use

pins=default|coFF1493||-122 45

Pushpin Labels

To add a label to the pins, put the label in single quotes just before the coordinates. For example, to label three pins with the values '1', '2', and '3', use

pins=default||'1'-122 45|'2'-119.5 43.2|'3'-121.67 47.12

There is a built in pushpin style called 'none' that does not display a pushpin image. You can use this if you want to display labels without any pin image. For example,

pins=none||'A'-122 45|'B'-119.5 43.2

To change the color of the pushpin labels, use the 'lc' label color style modifier. For example, to use pink pushpins with black labels, use

pins=default|coFF1493|lc000000||-122 45

To change the size of the labels, use the 'ls' label size style modifier. The label size represents the approximate height of the label text in pixels. For example, to increase the label size to 12, use

pins=default|ls12||'A'-122 45|'B'-119 43

The labels are centered at the pushpin 'label anchor.' The anchor location is predefined for built-in pushpins and is at the top center of custom pushpins (see below). To override the label anchor, using the 'la' style modifier and provide X and Y pixel coordinates for the anchor. These coordinates are relative to the top left corner of the pushpin image. Positive X values move the anchor to the right, and positive Y values move the anchor down. For example, to position the label anchor 10 pixels right and 4 pixels above the top left corner of the pushpin image, use

pins=default|la10 -4||'A'-122 45|'B'-119 43

Custom Pushpins

To use a custom pushpin image, use the word 'custom' as the pin style name, and then specify a URL after the location and label information. Use two pipe characters to indicate that you're done specifying locations and are starting the URL. For example,

pins=custom||-122 45||http://contoso.com/pushpins/red.png

After URL encoding, this would look like

pins=custom%7C%7C-122+45%7C%7Chttp%3A%2F%2Fcontoso.com%2Fpushpins%2Fred.png

By default, custom pushpin images are drawn centered at the pin coordinates. This usually isn't ideal as it obscures the location that you're trying to highlight. To override the anchor location of the pin image, use the 'an' style modifier. This uses the same format as the 'la' label anchor style modifier. For example, if your custom pin image has the tip of the pin at the top left corner of the image, you can set the anchor to that spot by using

pins=custom|an0 0||-122 45||http://contoso.com/pushpins/red.png

Note: If you use the 'co' color modifier with a custom pushpin image, the specified color will replace the RGB channels of the pixels in the image but will leave the alpha (opacity) channel unchanged. This would usually only be done with a solid-color custom image.

Getting Pushpins from Azure Maps Data Storage

For all Azure Maps account SKUs other than S0, the pushpin image and location information can be obtained from Azure Maps Data Storage. After uploading a pushpin image or a GeoJSON document containing pin locations, the Data Storage service returns a Unique Data ID (UDID) that you can use to reference the data in the pins parameter.

To use a custom pushpin image from Azure Maps Data Storage, specify the UDID prefixed by 'udid-' as the name of the pushpin style. For example,

pins=udid-fe22c504-3a81-4fcd-adc6-a3507ce866c1||-122 45

To use the point geometry from an uploaded GeoJSON document as the pin locations, specify the UDID in the locations section of the pins parameter. For example,

pins=default||udid-29dc105a-dee7-409f-a3f9-22b066ae4713

Note that only point and multipoint geometry, points and multipoints from geometry collections, and point geometry from features will be used. Linestring and polygon geometry will be ignored. If the point comes from a feature and the feature has a string property called "label", the value of that property will be used as the label for the pin.

You can mix pin locations from Data Storage and pin locations specified in the pins parameter. Any of the pipe-delimited pin locations can be a longitude and latitude or a UDID. For example,

pins=default||-122 45|udid-29dc105a-dee7-409f-a3f9-22b066ae4713|-119 43

Scale, Rotation, and Opacity

You can make pushpins and their labels larger or smaller by using the 'sc' scale style modifier. This is a value greater than zero. A value of 1 is the standard scale. Values larger than 1 will make the pins larger, and values smaller than 1 will make them smaller. For example, to draw the pushpins 50% larger than normal, use

pins=default|sc1.5||-122 45

You can rotate pushpins and their labels by using the 'ro' rotation style modifier. This is a number of degrees of clockwise rotation. Use a negative number to rotate counter-clockwise. For example, to rotate the pushpins 90 degrees clockwise and double their size, use

pins=default|ro90|sc2||-122 45

You can make pushpins and their labels partially transparent by specifying the 'al' alpha style modifier. This is a number between 0 and 1 indicating the opacity of the pushpins. Zero makes them completely transparent (and not visible) and 1 makes them completely opaque (which is the default). For example, to make pushpins and their labels only 67% opaque, use

pins=default|al.67||-122 45

Style Modifier Summary

Modifier Description Range
al Alpha (opacity) 0 to 1
an Pin anchor *
co Pin color 000000 to FFFFFF
la Label anchor *
lc Label color 000000 to FFFFFF
ls Label size Greater than 0
ro Rotation -360 to 360
sc Scale Greater than 0
  • X and Y coordinates can be anywhere within pin image or a margin around it. The margin size is the minimum of the pin width and height.
path
query
  • array

Path style and locations. Use this parameter to optionally add lines, polygons or circles to the image. The path style describes the appearance of the line and fill. (Be sure to properly URL-encode values of this parameter since it will contain reserved characters such as pipes and punctuation.)

Path parameter is supported in Azure Maps account SKU starting with S1. Multiple instances of the path parameter allow to specify multiple geometries with their styles. Nuber of parameters per request is limited to 10 and number of locations is limited to 100 per path.

To render a circle with radius 100 meters and center point at latitude 45°N and longitude 122°W using the default style, add the querystring parameter

path=ra100||-122 45

Note that the longitude comes before the latitude. After URL encoding this will look like

path=ra100%7C%7C45+-122

All of the examples here show the path parameter without URL encoding, for clarity.

To render a line, separate each location with a pipe character. For example, use

path=||-122 45|-119.5 43.2|-121.67 47.12

To render a polygon, last location must be equal to the start location. For example, use

path=||-122 45|-119.5 43.2|-121.67 47.12|-122 45

Longitude and latitude values for locations of lines and polygons can be in the range from -360 to 360 to allow for rendering of geometries crossing the anti-meridian.

Style Modifiers

You can modify the appearance of the path by adding style modifiers. These are added before the locations. Style modifiers each have a two-letter name. These abbreviated names are used to help reduce the length of the URL.

To change the color of the outline, use the 'lc' style modifier and specify the color using the HTML/CSS RGB color format which is a six-digit hexadecimal number (the three-digit form is not supported). For example, to use a deep pink color which you would specify as #FF1493 in CSS, use

path=lcFF1493||-122 45|-119.5 43.2

Multiple style modifiers may be combined together to create a more complex visual style.

lc0000FF|lw3|la0.60|fa0.50||-122.2 47.6|-122.2 47.7|-122.3 47.7|-122.3 47.6|-122.2 47.6

Getting Path locations from Azure Maps Data Storage

For all Azure Maps account SKUs other than S0, the path location information can be obtained from Azure Maps Data Storage. After uploading a GeoJSON document containing path locations, the Data Storage service returns a Unique Data ID (UDID) that you can use to reference the data in the path parameter.

To use the point geometry from an uploaded GeoJSON document as the path locations, specify the UDID in the locations section of the path parameter. For example,

path=||udid-29dc105a-dee7-409f-a3f9-22b066ae4713

Note the it is not allowed to mix path locations from Data Storage with locations specified in the path parameter.

Style Modifier Summary

Modifier Description Range
lc Line color 000000 to FFFFFF
fc Fill color 000000 to FFFFFF
la Line alpha (opacity) 0 to 1
fa Fill alpha (opacity) 0 to 1
lw Line width Greater than 0
ra Circle radius (meters) Greater than 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
  • 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.

Request Header

Name Required Type Description
x-ms-client-id
  • string

Specifies which account is intended for usage in conjunction with the Azure AD security model. It represents a unique ID for the Azure Maps account and can be retrieved from Azure Maps management plane Account API. To use Azure AD security in Azure Maps see the following articles for guidance.

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 or invalid Azure Active Directory bearer token. Make sure to provide a valid key for an active Azure subscription and Maps resource. Otherwise, verify the WWW-Authenticate header for error code and description of the provided AAD bearer token.

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

Headers

  • WWW-Authenticate: string
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"

Security

azure_auth

These are the Azure Active Directory OAuth2 Flows. When paired with Azure Role Based Access control it can be used to control access to Azure Maps REST APIs. Azure Role based access controls are used to designate access to one or more Azure Maps resource account or sub-resources. Any user, group, or service principal can be granted access via a built in role or a custom role composed of one or more permissions to Azure Maps REST APIs.

To implement scenarios we recommend viewing authentication concepts. In summary, this security definition provides a solution for modeling application(s) via objects capable of access control on specific APIs and scopes.

Note

  • This security definition requires the use of the x-ms-client-id header to indicate which Azure Maps resource the application is requesting access to. This can be acquired from the Maps management API.
  • The Authorization URL is specific to the Azure public cloud instance. Sovereign clouds have unique Authorization URLs and Azure Active directory configurations.
  • The Azure role based access control is configured from the Azure management plane via Azure portal, Powershell, CLI, Azure SDKs, or REST APIs.
  • Usage of the Azure Maps Web SDK allows for configuration based setup of an application for multiple use cases.
  • Currently Azure Active Directory v1.0 tokens are supported.

Type: oauth2
Flow: implicit
Authorization URL: https://login.microsoftonline.com/common/oauth2/authorize

subscription-key

This is a shared key which is provisioned when creating an Azure Maps resource through the Azure management plane via Azure portal, Powershell, CLI, Azure SDKs, or REST APIs. With this key, any application is authorized to access all REST APIs. In other words, these can currently be treated as master keys to the account which they are issued for. For publicly exposed applications our recommendation is to use server to server access of Azure Maps REST APIs where this key can be securely stored.

Type: apiKey
In: query

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.