Azure Maps Search Dotnet

by microsoft354361d83247MITListed Oct 8, 2026Updated Oct 8, 2026

Azure Maps SDK for .NET. Location-based services including geocoding, routing, rendering, geolocation, and weather. Use for address search, directions, map tiles, IP geolocation, and weather data. Triggers: "Azure Maps", "MapsSearchClient", "MapsRoutingClient", "MapsRenderingClient", "geocoding .NET", "route directions", "map tiles", "geolocation".

FeaturedInstructions onlySoftware Development
AI-generated overview

Reference guide for using the Azure Maps SDK for .NET for geocoding, routing, map tiles, geolocation and weather.

What it does
This skill documents the Azure Maps SDK for .NET, covering installation of the Search, Routing, Rendering, Geolocation, Weather and Resource Management packages. It shows authentication options (subscription key, Microsoft Entra token credential, and SAS token) and lists the client hierarchy for each package. It provides C# code samples for geocoding, batch and reverse geocoding, boundary polygons, route directions, route matrices, isochrones, map tiles, IP geolocation and weather lookups, plus error handling and best practices.
When to use it
Use it when writing .NET code that calls Azure Maps location services, such as address search, directions, map tiles, IP geolocation or weather data. It is suited to developers who need concrete client, option and result type examples for these APIs.
Requirements
Requires the .NET SDK and the Azure Maps NuGet packages (Azure.Maps.Search, Azure.Maps.Routing, Azure.Maps.Rendering, Azure.Maps.Geolocation, Azure.Maps.Weather, Azure.ResourceManager.Maps, Azure.Identity). Needs an Azure Maps account with credentials: a subscription key, a Microsoft Entra identity, or a SAS token, plus network access to the Azure Maps service. Ships no scripts; it is instructions and code samples only.

Azure Maps (.NET)

Azure Maps SDK for .NET providing location-based services: geocoding, routing, rendering, geolocation, and weather.

Installation

bash
# Search (geocoding, reverse geocoding)dotnet add package Azure.Maps.Search --prerelease
# Routing (directions, route matrix)dotnet add package Azure.Maps.Routing --prerelease
# Rendering (map tiles, static images)dotnet add package Azure.Maps.Rendering --prerelease
# Geolocation (IP to location)dotnet add package Azure.Maps.Geolocation --prerelease
# Weatherdotnet add package Azure.Maps.Weather --prerelease
# Resource Management (account management, SAS tokens)dotnet add package Azure.ResourceManager.Maps --prerelease
# Required for authenticationdotnet add package Azure.Identity

Current Versions:

  • Azure.Maps.Search: v2.0.0-beta.5
  • Azure.Maps.Routing: v1.0.0-beta.4
  • Azure.Maps.Rendering: v2.0.0-beta.1
  • Azure.Maps.Geolocation: v1.0.0-beta.3
  • Azure.ResourceManager.Maps: v1.1.0-beta.2

Environment Variables

bash
AZURE_MAPS_SUBSCRIPTION_KEY=<your-subscription-key>  # Only required for AzureKeyCredential authAZURE_MAPS_CLIENT_ID=<your-client-id>  # Required: Azure Maps client IDAZURE_TOKEN_CREDENTIALS=prod  # Required only if DefaultAzureCredential is used in production

Authentication

Subscription Key (Shared Key)

csharp
using Azure;using Azure.Maps.Search;
var subscriptionKey = Environment.GetEnvironmentVariable("AZURE_MAPS_SUBSCRIPTION_KEY");var credential = new AzureKeyCredential(subscriptionKey);
var client = new MapsSearchClient(credential);

Microsoft Entra Token Credential

csharp
using Azure.Identity;using Azure.Maps.Search;
// Local dev: DefaultAzureCredential. Production: set AZURE_TOKEN_CREDENTIALS=prod or AZURE_TOKEN_CREDENTIALS=<specific_credential>var credential = new DefaultAzureCredential(    DefaultAzureCredential.DefaultEnvironmentVariableName);// Or use a specific credential directly in production:// See https://learn.microsoft.com/dotnet/api/overview/azure/identity-readme?view=azure-dotnet#credential-classes// var credential = new ManagedIdentityCredential();var clientId = Environment.GetEnvironmentVariable("AZURE_MAPS_CLIENT_ID");
var client = new MapsSearchClient(credential, clientId);

Shared Access Signature (SAS)

csharp
using Azure;using Azure.Core;using Azure.Identity;using Azure.ResourceManager;using Azure.ResourceManager.Maps;using Azure.ResourceManager.Maps.Models;using Azure.Maps.Search;
// Authenticate with Azure Resource ManagerArmClient armClient = new ArmClient(new DefaultAzureCredential());
// Get Maps account resourceResourceIdentifier mapsAccountResourceId = MapsAccountResource.CreateResourceIdentifier(    subscriptionId, resourceGroupName, accountName);MapsAccountResource mapsAccount = armClient.GetMapsAccountResource(mapsAccountResourceId);
// Generate SAS tokenMapsAccountSasContent sasContent = new MapsAccountSasContent(    MapsSigningKey.PrimaryKey,     principalId,     maxRatePerSecond: 500,     start: DateTime.UtcNow.ToString("O"),     expiry: DateTime.UtcNow.AddDays(1).ToString("O"));
Response<MapsAccountSasToken> sas = mapsAccount.GetSas(sasContent);
// Create client with SAS tokenvar sasCredential = new AzureSasCredential(sas.Value.AccountSasToken);var client = new MapsSearchClient(sasCredential);

Client Hierarchy

Azure.Maps.Search└── MapsSearchClient    ├── GetGeocoding()                    → Geocode addresses    ├── GetGeocodingBatch()               → Batch geocoding    ├── GetReverseGeocoding()             → Coordinates to address    ├── GetReverseGeocodingBatch()        → Batch reverse geocoding    └── GetPolygon()                      → Get boundary polygons
Azure.Maps.Routing└── MapsRoutingClient    ├── GetDirections()                   → Route directions    ├── GetImmediateRouteMatrix()         → Route matrix (sync, ≤100)    ├── GetRouteMatrix()                  → Route matrix (async, ≤700)    └── GetRouteRange()                   → Isochrone/reachable range
Azure.Maps.Rendering└── MapsRenderingClient    ├── GetMapTile()                      → Map tiles    ├── GetMapStaticImage()               → Static map images    └── GetCopyrightCaption()             → Copyright info
Azure.Maps.Geolocation└── MapsGeolocationClient    └── GetCountryCode()                  → IP to country/region
Azure.Maps.Weather└── MapsWeatherClient    ├── GetCurrentWeatherConditions()     → Current weather    ├── GetDailyForecast()                → Daily forecast    ├── GetHourlyForecast()               → Hourly forecast    └── GetSevereWeatherAlerts()          → Weather alerts

Core Workflows

1. Geocoding (Address to Coordinates)

csharp
using Azure;using Azure.Maps.Search;
var credential = new AzureKeyCredential(subscriptionKey);var client = new MapsSearchClient(credential);
Response<GeocodingResponse> result = client.GetGeocoding("1 Microsoft Way, Redmond, WA 98052");
foreach (var feature in result.Value.Features){    Console.WriteLine($"Coordinates: {string.Join(",", feature.Geometry.Coordinates)}");    Console.WriteLine($"Address: {feature.Properties.Address.FormattedAddress}");    Console.WriteLine($"Confidence: {feature.Properties.Confidence}");}

2. Batch Geocoding

csharp
using Azure.Maps.Search.Models.Queries;
List<GeocodingQuery> queries = new List<GeocodingQuery>{    new GeocodingQuery() { Query = "400 Broad St, Seattle, WA" },    new GeocodingQuery() { Query = "1 Microsoft Way, Redmond, WA" },    new GeocodingQuery() { AddressLine = "Space Needle", Top = 1 },};
Response<GeocodingBatchResponse> results = client.GetGeocodingBatch(queries);
foreach (var batchItem in results.Value.BatchItems){    foreach (var feature in batchItem.Features)    {        Console.WriteLine($"Coordinates: {string.Join(",", feature.Geometry.Coordinates)}");    }}

3. Reverse Geocoding (Coordinates to Address)

csharp
using Azure.Core.GeoJson;
GeoPosition coordinates = new GeoPosition(-122.138685, 47.6305637);Response<GeocodingResponse> result = client.GetReverseGeocoding(coordinates);
foreach (var feature in result.Value.Features){    Console.WriteLine($"Address: {feature.Properties.Address.FormattedAddress}");    Console.WriteLine($"Locality: {feature.Properties.Address.Locality}");}

4. Get Boundary Polygon

csharp
using Azure.Maps.Search.Models;
GetPolygonOptions options = new GetPolygonOptions(){    Coordinates = new GeoPosition(-122.204141, 47.61256),    ResultType = BoundaryResultTypeEnum.Locality,    Resolution = ResolutionEnum.Small,};
Response<Boundary> result = client.GetPolygon(options);
Console.WriteLine($"Boundary copyright: {result.Value.Properties?.Copyright}");Console.WriteLine($"Polygon count: {result.Value.Geometry.Count}");

5. Route Directions

csharp
using Azure;using Azure.Core.GeoJson;using Azure.Maps.Routing;using Azure.Maps.Routing.Models;
var client = new MapsRoutingClient(new AzureKeyCredential(subscriptionKey));
List<GeoPosition> routePoints = new List<GeoPosition>(){    new GeoPosition(-122.34, 47.61),  // Seattle    new GeoPosition(-122.13, 47.64)   // Redmond};
RouteDirectionQuery query = new RouteDirectionQuery(routePoints);Response<RouteDirections> result = client.GetDirections(query);
foreach (var route in result.Value.Routes){    Console.WriteLine($"Distance: {route.Summary.LengthInMeters} meters");    Console.WriteLine($"Duration: {route.Summary.TravelTimeDuration}");        foreach (RouteLeg leg in route.Legs)    {        Console.WriteLine($"Leg points: {leg.Points.Count}");    }}

6. Route Directions with Options

csharp
RouteDirectionOptions options = new RouteDirectionOptions(){    RouteType = RouteType.Fastest,    UseTrafficData = true,    TravelMode = TravelMode.Bicycle,    Language = RoutingLanguage.EnglishUsa,    InstructionsType = RouteInstructionsType.Text,};
RouteDirectionQuery query = new RouteDirectionQuery(routePoints){    RouteDirectionOptions = options};
Response<RouteDirections> result = client.GetDirections(query);

7. Route Matrix

csharp
RouteMatrixQuery routeMatrixQuery = new RouteMatrixQuery{    Origins = new List<GeoPosition>()    {        new GeoPosition(-122.34, 47.61),        new GeoPosition(-122.13, 47.64)    },    Destinations = new List<GeoPosition>()     {         new GeoPosition(-122.20, 47.62),        new GeoPosition(-122.40, 47.65)    },};
// Synchronous (up to 100 route combinations)Response<RouteMatrixResult> result = client.GetImmediateRouteMatrix(routeMatrixQuery);
foreach (var cell in result.Value.Matrix.SelectMany(row => row)){    Console.WriteLine($"Distance: {cell.Response?.RouteSummary?.LengthInMeters}");    Console.WriteLine($"Duration: {cell.Response?.RouteSummary?.TravelTimeDuration}");}
// Asynchronous (up to 700 route combinations)RouteMatrixOptions routeMatrixOptions = new RouteMatrixOptions(routeMatrixQuery){    TravelTimeType = TravelTimeType.All,};GetRouteMatrixOperation asyncResult = client.GetRouteMatrix(WaitUntil.Completed, routeMatrixOptions);

8. Route Range (Isochrone)

csharp
RouteRangeOptions options = new RouteRangeOptions(-122.34, 47.61){    TimeBudget = new TimeSpan(0, 20, 0)  // 20 minutes};
Response<RouteRangeResult> result = client.GetRouteRange(options);
// result.Value.ReachableRange contains the polygonConsole.WriteLine($"Boundary points: {result.Value.ReachableRange.Boundary.Count}");

9. Get Map Tiles

csharp
using Azure;using Azure.Maps.Rendering;
var client = new MapsRenderingClient(new AzureKeyCredential(subscriptionKey));
int zoom = 10;int tileSize = 256;
// Convert coordinates to tile indexMapTileIndex tileIndex = MapsRenderingClient.PositionToTileXY(    new GeoPosition(13.3854, 52.517), zoom, tileSize);
// Fetch map tileGetMapTileOptions options = new GetMapTileOptions(    MapTileSetId.MicrosoftImagery,    new MapTileIndex(tileIndex.X, tileIndex.Y, zoom));
Response<Stream> mapTile = client.GetMapTile(options);
// Save to fileusing (FileStream fileStream = File.Create("./MapTile.png")){    mapTile.Value.CopyTo(fileStream);}

10. IP Geolocation

csharp
using System.Net;using Azure;using Azure.Maps.Geolocation;
var client = new MapsGeolocationClient(new AzureKeyCredential(subscriptionKey));
IPAddress ipAddress = IPAddress.Parse("2001:4898:80e8:b::189");Response<CountryRegionResult> result = client.GetCountryCode(ipAddress);
Console.WriteLine($"Country ISO Code: {result.Value.IsoCode}");

11. Current Weather

csharp
using Azure;using Azure.Core.GeoJson;using Azure.Maps.Weather;
var client = new MapsWeatherClient(new AzureKeyCredential(subscriptionKey));
var position = new GeoPosition(-122.13071, 47.64011);var options = new GetCurrentWeatherConditionsOptions(position);
Response<CurrentConditionsResult> result = client.GetCurrentWeatherConditions(options);
foreach (var condition in result.Value.Results){    Console.WriteLine($"Temperature: {condition.Temperature.Value} {condition.Temperature.Unit}");    Console.WriteLine($"Weather: {condition.Phrase}");    Console.WriteLine($"Humidity: {condition.RelativeHumidity}%");}

Key Types Reference

Search Package

TypePurpose
MapsSearchClientMain client for search operations
GeocodingResponseGeocoding result
GeocodingBatchResponseBatch geocoding result
GeocodingQueryQuery for batch geocoding
ReverseGeocodingQueryQuery for batch reverse geocoding
GetPolygonOptionsOptions for polygon retrieval
BoundaryBoundary polygon result
BoundaryResultTypeEnumBoundary type (Locality, AdminDistrict, etc.)
ResolutionEnumPolygon resolution (Small, Medium, Large)

Routing Package

TypePurpose
MapsRoutingClientMain client for routing operations
RouteDirectionQueryQuery for route directions
RouteDirectionOptionsRoute calculation options
RouteDirectionsRoute directions result
RouteLegSegment of a route
RouteMatrixQueryQuery for route matrix
RouteMatrixResultRoute matrix result
RouteRangeOptionsOptions for isochrone
RouteRangeResultIsochrone result
RouteTypeRoute type (Fastest, Shortest, Eco, Thrilling)
TravelModeTravel mode (Car, Truck, Bicycle, Pedestrian)

Rendering Package

TypePurpose
MapsRenderingClientMain client for rendering
GetMapTileOptionsMap tile options
MapTileIndexTile coordinates (X, Y, Zoom)
MapTileSetIdTile set identifier

Common Types

TypePurpose
GeoPositionGeographic position (longitude, latitude)
GeoBoundingBoxBounding box for geographic area

Best Practices

  1. Use Entra ID for production — Prefer over subscription keys
  2. Batch operations — Use batch geocoding for multiple addresses
  3. Cache results — Geocoding results don't change frequently
  4. Use appropriate tile sizes — 256 or 512 pixels based on display
  5. Handle rate limits — Implement exponential backoff
  6. Use async route matrix — For large matrix calculations (>100)
  7. Consider traffic data — Set UseTrafficData = true for accurate ETAs

Error Handling

csharp
try{    Response<GeocodingResponse> result = client.GetGeocoding(address);}catch (RequestFailedException ex){    Console.WriteLine($"Status: {ex.Status}");    Console.WriteLine($"Error: {ex.Message}");        switch (ex.Status)    {        case 400:            // Invalid request parameters            break;        case 401:            // Authentication failed            break;        case 429:            // Rate limited - implement backoff            break;    }}

Related SDKs

SDKPurposeInstall
Azure.Maps.SearchGeocoding, searchdotnet add package Azure.Maps.Search --prerelease
Azure.Maps.RoutingDirections, matrixdotnet add package Azure.Maps.Routing --prerelease
Azure.Maps.RenderingMap tiles, imagesdotnet add package Azure.Maps.Rendering --prerelease
Azure.Maps.GeolocationIP geolocationdotnet add package Azure.Maps.Geolocation --prerelease
Azure.Maps.WeatherWeather datadotnet add package Azure.Maps.Weather --prerelease
Azure.ResourceManager.MapsAccount managementdotnet add package Azure.ResourceManager.Maps --prerelease

Reference Links

Source and attribution

Source:microsoft/skillsin.github/plugins/azure-sdk-dotnet/skills/azure-maps-search-dotnetat commit354361d

License: MIT

Content belongs to its original authors. SourceWeft indexes it from a public repository.

Report or request removal