Skip to content

docs: azure maps providers #1722

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Jul 10, 2025
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion report-items/map/get-started.md
Original file line number Diff line number Diff line change
Expand Up @@ -84,7 +84,7 @@ SELECT

## Defining the Location Provider

1. On the __Choose a location provider__ page, select the location provider that will be used to geocode the __State__ field that was dragged in the **Categories (location)** box on the previous page. Currently, the supported providers are [`MapQuestOpenAPILocationProvider`](/reporting/api/Telerik.Reporting.MapQuestOpenAPILocationProvider), [`MapQuestLocationProvider`](/reporting/api/Telerik.Reporting.MapQuestLocationProvider), and [`BingLocationProvider`](/reporting/api/Telerik.Reporting.BingLocationProvider). They both require a valid client token (key) to authenticate the geocoding requests that will be sent from the Map item.
1. On the __Choose a location provider__ page, select the location provider that will be used to geocode the __State__ field that was dragged in the **Categories (location)** box on the previous page. Currently, the supported providers are [`MapQuestOpenAPILocationProvider`](/reporting/api/Telerik.Reporting.MapQuestOpenAPILocationProvider), [`MapQuestLocationProvider`](/reporting/api/Telerik.Reporting.MapQuestLocationProvider), [`BingLocationProvider`](/reporting/api/Telerik.Reporting.BingLocationProvider), and [`AzureLocationProvider`](/reporting/api/Telerik.Reporting.AzureLocationProvider). They all require a valid client token (key) to authenticate the geocoding requests that will be sent from the Map item.

Once you obtain the key, paste it in the **Client token** box:

Expand Down
2 changes: 1 addition & 1 deletion report-items/map/map-types/barchart-map.md
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,7 @@ In the **Available data sources** list, you will see the data source you've alre

1. On the __Choose a location provider__ page, select the location provider that will be used to geocode the __State__ field that was dragged in the **Categories (location)** box on the previous page.

Currently, the supported providers are [`MapQuestOpenAPILocationProvider`](/reporting/api/Telerik.Reporting.MapQuestOpenAPILocationProvider), [`MapQuestLocationProvider`](/reporting/api/Telerik.Reporting.MapQuestLocationProvider) and [`BingLocationProvider`](/reporting/api/Telerik.Reporting.BingLocationProvider). They both require a valid client token (key) to authenticate the geocoding requests that will be sent from the Map item. Once you have obtained the key, paste it in the **Client token** box:
Currently, the supported providers are [`MapQuestOpenAPILocationProvider`](/reporting/api/Telerik.Reporting.MapQuestOpenAPILocationProvider), [`MapQuestLocationProvider`](/reporting/api/Telerik.Reporting.MapQuestLocationProvider), [`BingLocationProvider`](/reporting/api/Telerik.Reporting.BingLocationProvider), and [`AzureLocationProvider`](/reporting/api/Telerik.Reporting.AzureLocationProvider). They all require a valid client token (key) to authenticate the geocoding requests that will be sent from the Map item. Once you have obtained the key, paste it in the **Client token** box:

![Choose A Location Provider page of the Standalone Report Designer Map Wizard](images/ChooseALocationProvider.png)

Expand Down
2 changes: 2 additions & 0 deletions report-items/map/structure/location-providers.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,8 @@ The map supports the following location providers:

* [`BingLocationProvider`](/api/Telerik.Reporting.BingLocationProvider)—Uses the [Bing™ Maps Locations API](https://learn.microsoft.com/en-us/bingmaps/rest-services/locations/) to get location information about the requested address.

* [`AzureLocationProvider`](/api/Telerik.Reporting.AzureLocationProvider)—Uses the [Azure Maps Get Geocoding Request](https://learn.microsoft.com/en-us/rest/api/maps/search/get-geocoding) to get location information about the requested address. This provider was introduced in Q2 2025 as part of the transition from Bing Maps to Azure Maps.

## See Also

* [Demo Page for Telerik Reporting](https://demos.telerik.com/reporting)
Expand Down
42 changes: 35 additions & 7 deletions report-items/map/structure/tile-providers.md
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry for the delayed comment, but I just noticed that line 17 hasn't been updated to reflect all supported tile providers.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No worries; the delay is mutual 😄

Now that I think about it, is this listing truly necessary? I considered adding an unordered list, but it would require mentioning that some of these providers are obsolete or deprecated, which could lead to repetition. In the end, I removed that sentence entirely, but if you have any alternative suggestions, I would be happy to hear about them.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Removing it is also fine.

Original file line number Diff line number Diff line change
Expand Up @@ -14,13 +14,29 @@ The [`TileProvider`](/api/Telerik.Reporting.TileProvider) class requests and dow

The tile provider requires you to configure a valid set of URLs to request the tiles, defined directly or through a URL template.

The [Map](/api/Telerik.Reporting.Map) supports the [`BingMapsTileProvider`](/api/Telerik.Reporting.BingMapsTileProvider) and [`GenericTileProvider`](/api/Telerik.Reporting.GenericTileProvider) types of tile providers.

## Bing Maps Tile Provider

The [`BingMapsTileProvider`](/api/Telerik.Reporting.BingMapsTileProvider) uses the [Bing Maps REST Services](https://learn.microsoft.com/en-us/bingmaps/rest-services/) to request metadata information that is needed to resolve the tile requests URLs, zoom levels, tile sizes and attribution information such as the text or logo that will be displayed on the map. The user doesn't need to provide any server URL, subdomains, or another tiles-related information because it is retrieved automatically from the imagery metadata according to the desired imagery set.

The `BingMapsTileProvider` provides the **Aerial**, **Road**, and **Aerial with Labels** (an Aerial imagery with a road overlay) types of imagery sets that are mapped to the predefined values of the [`ImagerySet`](/api/Telerik.Reporting.ImagerySet) property (`Aerial`, `Road`, `Hybrid`). Changing the imagery set causes the `BingTileProvider` to request images from a different tile set, thus changing the look of the map. The tile server requires a Bing Maps Key client token for authentication which you can obtain from the [Bing Maps website](https://www.microsoft.com/en-us/maps/create-a-bing-maps-key).
## Azure Maps Tile Provider

The [`AzureMapsTileProvider`](/api/Telerik.Reporting.AzureMapsTileProvider) uses the [Azure Maps Get Map Tiles Request](https://learn.microsoft.com/en-us/rest/api/maps/render/get-map-tile) to get map imagery tiles based on the specified map extent. The provider automatically sets tile request URL, zoom level, tile sizes, and coordinates.

The `AzureMapsTileProvider` supports a variety of tilesets that let you customize the appearance and data shown on your map. The available tilesets include:

* **BaseRoad**—Basic road map (default style)
* **BaseHybridRoad**—Road map overlaid on satellite imagery
* **BaseLabelsDarkGray**—Labels styled for dark gray base maps
* **BaseLabelsRoad**—Adds road labels to the base map
* **BaseDarkGrey**—Dark-themed base map, ideal for night mode or data overlays
* **BaseHybridDarkGrey**—Hybrid of satellite imagery with dark gray overlays and labels
* **Imagery**—Raw satellite imagery without overlays
* **TerraMain**—Terrain-focused map with elevation and natural features
* **TrafficAbsoluteMain**—Shows absolute traffic speeds
* **TrafficDelayMain**—Highlights delays compared to normal traffic
* **TrafficReducedMain**—Indicates reduced traffic flow
* **TrafficRelativeDark**—Relative congestion styled for dark maps
* **TrafficRelativeMain**—Relative congestion levels on standard maps
* **WeatherInfraredMain**—Infrared satellite imagery for weather monitoring
* **WeatherRadarMain**—Real-time radar data showing precipitation and storms

To use this provider, an Azure Maps subscription key is required. You can obtain a key by [creating an Azure Maps account through the Azure Portal](https://learn.microsoft.com/en-us/azure/azure-maps/quick-demo-map-app#create-an-azure-maps-account). For more information on how to access the key, refer to [Get the subscription key for your account](https://learn.microsoft.com/en-us/azure/azure-maps/quick-demo-map-app#get-the-subscription-key-for-your-account).

## Generic Tile Provider

Expand All @@ -40,6 +56,18 @@ The [`GenericTileProvider`](/api/Telerik.Reporting.GenericTileProvider) requires
* In some scenarios it's required to set a value of the `UserAgent` web request header, which is sent to the tile providing web services. In this case, the [`UserAgent`](/api/Telerik.Reporting.GenericTileProvider#Telerik_Reporting_GenericTileProvider_UserAgent) property must be populated with a constant string or an expression that will be evaluated during the report processing. The value of this property will be set as a value of the `UserAgent` web request header. Initially, the value of the `UserAgent` property will be set to a newly generated GUID, but it has to be replaced with a correct value according to the usage policy of the tile provider.
* The users also have to provide [`Attribution`](/api/Telerik.Reporting.GenericTileProvider#Telerik_Reporting_GenericTileProvider_Attribution) text and a [`LogoUrl`](/api/Telerik.Reporting.GenericTileProvider#Telerik_Reporting_GenericTileProvider_LogoUrl) that will be used to display an attribution information on the map. The [`Attribution`](/api/Telerik.Reporting.GenericTileProvider#Telerik_Reporting_GenericTileProvider_Attribution) property must be manually set according to the [usage policy](https://wiki.openstreetmap.org/wiki/Legal_FAQ) of the tile provider. This text will be displayed in the lower right corner of the map area. The [`LogoUrl`](/api/Telerik.Reporting.GenericTileProvider#Telerik_Reporting_GenericTileProvider_LogoUrl) property denotes the URL used to download the tile provider [logo](https://wiki.openstreetmap.org/w/images/thumb/7/79/Public-images-osm_logo.svg/32px-Public-images-osm_logo.svg.png), if required by the usage policy of the provider. If the URL points to a valid image, it will be displayed in the lower left corner of the map area.

## (Deprecated) Bing Maps Tile Provider

The [`BingMapsTileProvider`](/api/Telerik.Reporting.BingMapsTileProvider) uses the [Bing Maps REST Services](https://learn.microsoft.com/en-us/bingmaps/rest-services/) to request metadata information that is needed to resolve the tile requests URLs, zoom levels, tile sizes and attribution information such as the text or logo that will be displayed on the map. The user doesn't need to provide any server URL, subdomains, or another tiles-related information because it is retrieved automatically from the imagery metadata according to the desired imagery set.

The `BingMapsTileProvider` provides the **Aerial**, **Road**, and **Aerial with Labels** (an Aerial imagery with a road overlay) types of imagery sets that are mapped to the predefined values of the [`ImagerySet`](/api/Telerik.Reporting.ImagerySet) property (`Aerial`, `Road`, `Hybrid`). Changing the imagery set causes the `BingTileProvider` to request images from a different tile set, thus changing the look of the map. The tile server requires a Bing Maps Key client token for authentication which you can obtain from the [Bing Maps website](https://www.microsoft.com/en-us/maps/create-a-bing-maps-key).

>caution Microsoft has announced the deprecation of **Bing Maps for Enterprise**:
> * `Free (Basic)` accounts can use Bing Maps services until June 30, 2025.
> * `Enterprise` accounts can continue until June 30, 2028.
> The official Microsoft recommendation is for users to migrate to [Azure Maps](https://learn.microsoft.com/en-us/azure/azure-maps/) prior to these periods to avoid service distruptions.
> Telerik Reporting introduced support for Azure Maps through dedicated providers in Q2 2025 to address the deprecation of Bing Maps for Enterprise.

## (Obsolete) Map Quest Tile Provider

The obsolete [`MapQuestTileProvider`](/api/Telerik.Reporting.MapQuestTileProvider) uses the [`MapQuest`](https://www.mapquest.com/) tile servers that provides the tiles in the **OpenStreetMap Tiles** and the **MapQuest Open Aerial Tiles** imagery sets.
Expand Down