swagger: '2.0'
info:
title: Microsoft Azure Azure Maps Render Service
version: '2.1'
description: Azure Maps Render REST APIs
host: atlas.microsoft.com
schemes:
- https
consumes: []
produces:
- application/json
- application/xml
securityDefinitions:
AADToken:
type: oauth2
authorizationUrl: https://login.microsoftonline.com/common/oauth2/authorize
flow: implicit
description: >-
These are the [Azure Active Directory
OAuth2](https://docs.microsoft.com/azure/active-directory/develop/v1-overview)
Flows. When paired with [Azure role-based
access](https://docs.microsoft.com/azure/role-based-access-control/overview)
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](https://aka.ms/amauth). In summary, this security definition
provides a solution for modeling application(s) via objects capable of
access control on specific APIs and scopes.
#### Notes
* 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](https://aka.ms/amauthdetails).
*
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](https://aka.ms/amrbac) via Azure portal, PowerShell,
CLI, Azure SDKs, or REST APIs.
*
Usage of the [Azure Maps Web SDK](https://aka.ms/amaadmc) allows for
configuration based setup of an application for multiple use cases.
* Currently, Azure Active Directory [v1.0 or
v2.0](https://docs.microsoft.com/azure/active-directory/develop/azure-ad-endpoint-comparison)
supports Work, School, and Guests but does not support Personal accounts.
scopes:
https://atlas.microsoft.com/.default: https://atlas.microsoft.com/.default
SharedKey:
type: apiKey
description: >-
This is a shared key that is provisioned when you [Create an Azure Maps
account](https://docs.microsoft.com/azure/azure-maps/quick-demo-map-app#create-an-azure-maps-account)
in the Azure portal or using PowerShell, CLI, Azure SDKs, or REST API.
With this key, any application can access all REST API. In other words, this key can be used as a master key in the account that they are issued in.
For publicly exposed applications, our recommendation is to use the [confidential client applications](https://docs.microsoft.com/azure/azure-maps/authentication-best-practices#confidential-client-applications) approach to access Azure Maps REST APIs so your key can be securely stored.
name: subscription-key
in: query
SasToken:
type: apiKey
description: >-
This is a shared access signature token is created from the List SAS
operation on the [Azure Maps resource](https://aka.ms/amauth) through the
Azure management plane via Azure portal, PowerShell, CLI, Azure SDKs, or
REST APIs.
With this token, any application is authorized to access with Azure role-based access controls and fine-grain control to the expiration, rate, and region(s) of use for the particular token. In other words, the SAS Token can be used to allow applications to control access in a more secured way than the shared key.
For publicly exposed applications, our recommendation is to configure a specific list of allowed origins on the [Map account resource](https://aka.ms/amauth) to limit rendering abuse and regularly renew the SAS Token.
name: SAS Token
in: header
security:
- AADToken:
- https://atlas.microsoft.com/.default
- SharedKey: []
- SasToken: []
responses:
'400':
description: >-
Bad request: one or more parameters were incorrectly specified or are
mutually exclusive.
schema:
$ref: '#/definitions/ODataErrorResponse'
'401':
description: >-
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](https://tools.ietf.org/html/rfc6750#section-3.1) header
for error code and description of the provided AAD bearer token.
schema:
$ref: '#/definitions/ODataErrorResponse'
headers:
WWW-Authenticate:
type: string
description: >-
Bearer realm="https://atlas.microsoft.com/", error="invalid_token",
error_description="The access token expired"
'403':
description: Permission, capacity, or authentication issues.
schema:
$ref: '#/definitions/ODataErrorResponse'
'404':
description: >-
Not Found: the requested resource could not be found, but it may be
available again in the future.
schema:
$ref: '#/definitions/ODataErrorResponse'
'500':
description: An error occurred while processing the request. Please try again later.
schema:
$ref: '#/definitions/ODataErrorResponse'
parameters:
ClientId:
name: x-ms-client-id
description: >-
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](https://aka.ms/amauthdetails) for guidance.
type: string
in: header
required: false
x-ms-parameter-location: client
SubscriptionKey:
name: subscription-key
description: >-
One of the Azure Maps keys provided from an Azure Map Account. Please
refer to this
[article](https://docs.microsoft.com/azure/azure-maps/how-to-manage-authentication)
for details on how to manage authentication.
type: string
in: query
required: false
x-ms-parameter-location: client
ApiVersion:
name: api-version
description: Version number of Azure Maps API. Current version is 2.1
type: string
in: query
required: true
default: '2.0'
x-ms-parameter-location: client
TilesetId_rv2:
name: tilesetId
description: >-
A tileset is a collection of raster or vector data broken up into a
uniform grid of square tiles at preset zoom levels. Every tileset has a
**tilesetId** to use when making requests. The **tilesetId** for tilesets
created using [Azure Maps Creator](https://aka.ms/amcreator) are generated
through the [Tileset Create
API](https://docs.microsoft.com/rest/api/maps-creator/tileset). The
ready-to-use tilesets supplied by Azure Maps are listed below. For
example, microsoft.base.
type: string
in: query
required: true
enum:
- microsoft.base
- microsoft.base.labels
- microsoft.base.hybrid
- microsoft.terra.main
- microsoft.base.road
- microsoft.base.darkgrey
- microsoft.base.labels.road
- microsoft.base.hybrid.road
- microsoft.imagery
- microsoft.weather.radar.main
- microsoft.weather.infrared.main
- microsoft.dem
- microsoft.dem.contours
x-ms-enum:
name: TilesetID
modelAsString: true
values:
- value: microsoft.base
description: >-
A base map is a standard map that displays roads, natural and
artificial features along with the labels for those features in a
vector tile.<br>
Supports zoom levels 0 through 22. Format: vector (pbf).
- value: microsoft.base.labels
description: >-
Displays labels for roads, natural and artificial features in a
vector tile.<br>
Supports zoom levels 0 through 22. Format: vector (pbf).
- value: microsoft.base.hybrid
description: |-
Displays road, boundary and label data in a vector tile.<br>
Supports zoom levels 0 through 22. Format: vector (pbf).
- value: microsoft.terra.main
description: |-
Shaded relief and terra layers.<br>
Supports zoom levels 0 through 6. Format: raster (png).
- value: microsoft.base.road
description: |-
All layers with our main style.<br>
Supports zoom levels 0 through 22. Format: raster (png).
- value: microsoft.base.darkgrey
description: |-
All layers with our dark grey style.<br>
Supports zoom levels 0 through 22. Format: raster (png).
- value: microsoft.base.labels.road
description: |-
Label data in our main style.<br>
Supports zoom levels 0 through 22. Format: raster (png).
- value: microsoft.base.hybrid.road
description: |-
Road, boundary and label data in our main style.<br>
Supports zoom levels 0 through 22. Format: raster (png).
- value: microsoft.imagery
description: >-
A combination of satellite and aerial imagery. Only available in S1
pricing SKU.<br>
Supports zoom levels 1 through 19. Format: raster (jpeg).
- value: microsoft.weather.radar.main
description: >-
Weather radar tiles. Latest weather radar images including areas of
rain, snow, ice and mixed conditions. Please see [coverage
information](https://aka.ms/AzureMapsWeatherCoverage) for Azure Maps
Weather service. To learn more about the Radar data, please see
[Weather concepts](https://aka.ms/AzureMapsWeatherConcepts).<br>
Supports zoom levels 0 through 15. Format: raster (png).
- value: microsoft.weather.infrared.main
description: >-
Weather infrared tiles. Latest Infrared Satellite images shows
clouds by their temperature. Please see [coverage
information](https://aka.ms/AzureMapsWeatherCoverage) for Azure Maps
Weather service. To learn more about the returned Satellite data,
please see [Weather
concepts](https://aka.ms/AzureMapsWeatherConcepts).<br>
Supports zoom levels 0 through 15. Format: raster (png).
- value: microsoft.dem
description: >-
Digital Elevation Model tiles. The tiles are in the GeoTIFF format
with a single 32-bit floating point band. The tiles cover the whole
landmass of Earth. Some small islands (e.g., atolls) might not be
represented accurately.<br>
* The vertical unit for measurement of elevation height is meters.
An elevation value of -32767.0 is used for points that have no data
value, most often returned where there isn't landmass (i.e.
water).<br>
* The horizontal reference datum is the World Geodetic System 1984
(WGS84-G1150) and the vertical reference datum is the Earth
Gravitational Model 2008 (EGM2008).<br>
* Tiles are 258x258 pixel squares rather than the standard 256 x
256. This is done to allow for accurate interpolation of values at
the tile edges. As such adjacent tiles overlap by 1 pixel along all
edges.<br>
* Tile data comes from the [Airbus WorldDEM4Ortho
product](https://www.intelligence-airbusds.com/worlddem-streaming/).
Urban areas are approximately leveled down to ground level. All
other areas are represented by the object surface level (e.g.,
trees). <br>
Supports zoom level 13 only. Format: raster (tiff).
- value: microsoft.dem.contours
description: >-
Digital elevation contour line tiles. Compared to the microsoft.dem
option, these tiles are in vector format and intended for
visualization purpose. The tiles cover the whole landmass of Earth.
Some small islands (e.g., atolls) might not be represented
accurately.<br>
* The vertical unit for measurement of elevation height is
meters.<br>
* The horizontal reference datum is the World Geodetic System 1984
(WGS84-G1150) and the vertical reference datum is the Earth
Gravitational Model 2008 (EGM2008).<br>
* Tile data comes from the [Airbus WorldDEM4Ortho
product](https://www.intelligence-airbusds.com/worlddem-streaming/).
Urban areas are approximately leveled down to ground level. All
other areas are represented by the object surface level (e.g.,
trees).<br>
Supports zoom levels 9 through 14. Format: vector (pbf).
x-ms-parameter-location: method
xTileIndex:
name: x
x-ms-client-name: xTileIndex
in: query
description: >-
X coordinate of the tile on zoom grid. Value must be in the range [0,
2<sup>`zoom`</sup> -1].
Please see [Zoom Levels and Tile
Grid](https://docs.microsoft.com/en-us/azure/location-based-services/zoom-levels-and-tile-grid)
for details.
required: true
type: integer
format: int32
x-ms-parameter-location: method
yTileIndex:
name: 'y'
x-ms-client-name: yTileIndex
in: query
description: >-
Y coordinate of the tile on zoom grid. Value must be in the range [0,
2<sup>`zoom`</sup> -1].
Please see [Zoom Levels and Tile
Grid](https://docs.microsoft.com/en-us/azure/location-based-services/zoom-levels-and-tile-grid)
for details.
required: true
type: integer
format: int32
x-ms-parameter-location: method
MapTileV2Zoom:
name: zoom
in: query
description: >-
Zoom level for the desired tile. Please find TilesetID list below for more
details on supported zoom level for each tilesetId.<br>
Please see [Zoom Levels and Tile
Grid](https://docs.microsoft.com/en-us/azure/location-based-services/zoom-levels-and-tile-grid)
for details.
required: true
type: integer
format: int32
x-ms-parameter-location: method
Language:
name: language
in: query
description: >-
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](https://docs.microsoft.com/en-us/azure/azure-maps/supported-languages)
for details.
required: false
type: string
x-ms-parameter-location: method
Text:
name: text
in: query
description: >-
Yes/no value to exclude textual data from response. Only images and
country names will be in response.
required: false
type: string
enum:
- 'yes'
- 'no'
default: 'yes'
x-ms-parameter-location: method
View:
name: view
in: query
description: >-
The View parameter specifies which set of geopolitically disputed content
is returned via Azure Maps services, including borders and labels
displayed on the map. The View parameter (also referred to as “user region
parameter”) will show the correct maps for that country/region. By
default, the View parameter is set to “Unified” even if you haven’t
defined it in the request. It is your responsibility to determine the
location of your users, and then set the View parameter correctly for
that location. Alternatively, you have the option to set ‘View=Auto’,
which will return the map data based on the IP address of the request.
The View parameter in Azure Maps must be used in compliance with
applicable laws, including those regarding mapping, of the country where
maps, images and other data and third party content that you are
authorized to access via Azure Maps is made available. Example: view=IN.
Please refer to [Supported
Views](https://aka.ms/AzureMapsLocalizationViews) for details and to see
the available Views.
required: false
type: string
x-ms-parameter-location: method
paths:
/map/tile:
get:
description: >-
**Applies to**: S0 and S1 pricing tiers.<br><br>The Get Map Tiles API
allows users to request map tiles in vector or raster formats typically
to be integrated into a map control or SDK. Some example tiles that can
be requested are Azure Maps road tiles, real-time Weather Radar tiles
or the map tiles created using [Azure Maps
Creator](https://aka.ms/amcreator). By default, Azure Maps uses vector
tiles for its web map control (Web SDK) and Android SDK.
operationId: microsoftAzureRenderv2Getmaptile
x-ms-examples:
GetMapTile:
$ref: ./examples/GetMapTileV2.json
parameters:
- $ref: '#/parameters/ClientId'
- $ref: '#/parameters/SubscriptionKey'
- $ref: '#/parameters/ApiVersion'
- $ref: '#/parameters/TilesetId_rv2'
- $ref: '#/parameters/MapTileV2Zoom'
- $ref: '#/parameters/xTileIndex'
- $ref: '#/parameters/yTileIndex'
- name: timeStamp
in: query
description: >-
The desired date and time of the requested tile. This parameter must
be specified in the standard date-time format (e.g.
2019-11-14T16:03:00-08:00), as defined by [ISO
8601](https://en.wikipedia.org/wiki/ISO_8601). This parameter is
only supported when tilesetId parameter is set to one of the values
below.
* microsoft.weather.infrared.main: We provide tiles up to 3 hours in
the past. Tiles are available in 10-minute intervals. We round the
timeStamp value to the nearest 10-minute time frame.
* microsoft.weather.radar.main: We provide tiles up to 1.5 hours in
the past and up to 2 hours in the future. Tiles are available in
5-minute intervals. We round the timeStamp value to the nearest
5-minute time frame.
required: false
type: string
- name: tileSize
in: query
description: The size of the returned map tile in pixels.
required: false
type: string
default: '256'
enum:
- '256'
- '512'
x-ms-enum:
name: TileSize
modelAsString: true
values:
- value: '256'
description: >-
Return a 256 by 256 pixel tile. Available for all tilesetIds
except for
* microsoft.terra.main
- value: '512'
description: >-
Return a 512 by 512 pixel tile. Available for all tilesetIds
except for
* microsoft.weather.radar.main
* microsoft.weather.infrared.main
* microsoft.base.hybrid
* microsoft.dem
* microsoft.imagery
- $ref: '#/parameters/Language'
- $ref: '#/parameters/View'
produces:
- application/json
responses:
'200':
description: OK
schema:
$ref: '#/definitions/MapTileResultv2'
'400':
$ref: '#/responses/400'
'401':
$ref: '#/responses/401'
'403':
$ref: '#/responses/403'
'404':
$ref: '#/responses/404'
'500':
$ref: '#/responses/500'
summary: Microsoft Azure Get Map Tile
tags:
- Map
/map/tileset:
get:
description: >-
**Applies to**: S0 and S1 pricing tiers.<br><br>The Get Map Tileset API
allows users to request metadata for a tileset.
operationId: microsoftAzureRenderv2Getmaptileset
x-ms-examples:
GetMapTile:
$ref: ./examples/GetMapTilesetV2.json
parameters:
- $ref: '#/parameters/ClientId'
- $ref: '#/parameters/SubscriptionKey'
- $ref: '#/parameters/ApiVersion'
- $ref: '#/parameters/TilesetId_rv2'
produces:
- application/json
responses:
'200':
description: OK
schema:
$ref: '#/definitions/MapTilesetResultV2'
'400':
$ref: '#/responses/400'
'401':
$ref: '#/responses/401'
'403':
$ref: '#/responses/403'
'404':
$ref: '#/responses/404'
'500':
$ref: '#/responses/500'
summary: Microsoft Azure Get Map Tileset
tags:
- Map
/map/attribution:
get:
description: >-
**Applies to**: S0 and S1 pricing tiers.<br><br>The Get Map Attribution
API allows users to request map copyright attribution information for a
section of a tileset.
operationId: microsoftAzureRenderv2Getmapattribution
x-ms-examples:
GetMapTile:
$ref: ./examples/GetMapAttributionV2.json
parameters:
- $ref: '#/parameters/ClientId'
- $ref: '#/parameters/SubscriptionKey'
- $ref: '#/parameters/ApiVersion'
- $ref: '#/parameters/TilesetId_rv2'
- $ref: '#/parameters/MapTileV2Zoom'
- name: bounds
in: query
description: >-
The string that represents the rectangular area of a bounding box.
The bounds parameter is defined by the 4 bounding box coordinates,
with WGS84 longitude and latitude of the southwest corner followed
by WGS84 longitude and latitude of the northeast corner. The string
is presented in the following format: `[SouthwestCorner_Longitude,
SouthwestCorner_Latitude, NortheastCorner_Longitude, NortheastCorner_Latitude]`.
required: true
type: array
collectionFormat: csv
items:
type: string
produces:
- application/json
responses:
'200':
description: OK
schema:
$ref: '#/definitions/MapAttributionResultV2'
'400':
$ref: '#/responses/400'
'401':
$ref: '#/responses/401'
'403':
$ref: '#/responses/403'
'404':
$ref: '#/responses/404'
'500':
$ref: '#/responses/500'
summary: Microsoft Azure Get Map Attribution
tags:
- Map
definitions:
ODataErrorResponse:
type: object
description: This response object is returned when an error occurs in the Maps API.
properties:
error:
$ref: '#/definitions/ODataError'
ODataError:
type: object
description: This object is returned when an error occurs in the Maps API.
properties:
code:
type: string
readOnly: true
description: The ODataError code.
message:
type: string
readOnly: true
description: If available, a human readable description of the error.
details:
type: array
items:
$ref: '#/definitions/ODataError'
target:
type: string
readOnly: true
description: If available, the target causing the error.
MapTileResultv2:
description: The tile returned from a successful API call.
type: string
format: binary
readOnly: true
MapTilesetResultV2:
description: Metadata for a tileset in the TileJSON format.
type: object
readOnly: true
properties:
tilejson:
type: string
pattern: \d+\.\d+\.\d+\w?[\w\d]*
description: Version of the TileJSON spec.
name:
type: string
description: Name of the tileset.
description:
type: string
description: Text description of the tileset.
version:
type: string
pattern: \d+\.\d+\.\d+\w?[\w\d]*
description: >-
A semver.org style version number for the tiles contained within the
tileset.
attribution:
type: string
description: Copyright attribution to be displayed on the map.
template:
type: string
description: >-
A mustache template to be used to format data from grids for
interaction.
legend:
type: string
description: A legend to be displayed with the map.
scheme:
type: string
description: >-
Default: "xyz". Either "xyz" or "tms". Influences the y direction of
the tile coordinates.
tiles:
type: array
items:
type: string
description: An array of tile endpoints.
grids:
type: array
items:
type: string
description: An array of interactivity endpoints.
data:
type: array
items:
type: string
description: An array of data files in GeoJSON format.
minzoom:
minimum: 0
maximum: 30
type: integer
description: The minimum zoom level.
maxzoom:
minimum: 0
maximum: 30
type: integer
description: The maximum zoom level.
bounds:
type: array
items:
type: number
description: The WGS84 bounds of the tileset.
center:
type: array
items:
type: number
description: >-
The default location of the tileset in the form [longitude, latitude,
zoom].
MapAttributionResultV2:
description: Copyright attribution for the requested section of a tileset.
type: object
readOnly: true
properties:
copyrights:
type: array
items:
type: string
description: A list of copyright strings.
tags:
- name: Map