C# REST SDK Developers Guide

The Azure Maps C# SDK supports functionality available in the Azure Maps Rest API, like searching for an address, routing between different coordinates, and getting the geo-location of a specific IP address. This article introduces the C# REST SDK with examples to help you get started building location-aware applications in C# that incorporates the power of Azure Maps.

Note

Azure Maps C# SDK supports any .NET version that is compatible with .NET standard version 2.0 or higher. For an interactive table, see .NET Standard versions.

Prerequisites

• Azure Maps account.
• Subscription key or other form of Authentication with Azure Maps.
• .NET standard version 2.0 or higher.

Tip

You can create an Azure Maps account programmatically, Here's an example using the Azure CLI:

az maps account create --kind "Gen2" --account-name "myMapAccountName" --resource-group "<resource group>" --sku "G2"

Create a .NET project

The following PowerShell code snippet demonstrates how to use PowerShell to create a console program MapsDemo with .NET 7.0. You can use any .NET standard 2.0-compatible version as the framework.

dotnet new console -lang C# -n MapsDemo -f net7.0 
cd MapsDemo 

Install required packages

To use Azure Maps C# SDK, we need to install the required packages. Each of the Azure Maps services including search, routing, rendering and geolocation are each in their own package. Since the Azure Maps C# SDK is in public preview, you need to add the --prerelease flag:

dotnet add package Azure.Maps.Rendering --prerelease
dotnet add package Azure.Maps.Routing --prerelease
dotnet add package Azure.Maps.Search --prerelease
dotnet add package Azure.Maps.Geolocation --prerelease

Azure Maps services

Service name	NuGet package	Samples
Search	Azure.Maps.Search	search samples
Routing	Azure.Maps.Routing	routing samples
Rendering	Azure.Maps.Rendering	rendering sample
Geolocation	Azure.Maps.Geolocation	geolocation sample

Create and authenticate a MapsSearchClient

The client object used to access the Azure Maps Search APIs require either an AzureKeyCredential object to authenticate when using an Azure Maps subscription key or a TokenCredential object with the Azure Maps client ID when authenticating using Microsoft Entra ID. For more information on authentication, see Authentication with Azure Maps.

Using a Microsoft Entra credential

You can authenticate with Microsoft Entra ID using the Azure Identity library. To use the DefaultAzureCredential provider, you need to install the Azure Identity client library for .NET:

dotnet add package Azure.Identity 

You need to register the new Microsoft Entra application and grant access to Azure Maps by assigning the required role to your service principal. For more information, see Host a daemon on non-Azure resources. The Application (client) ID, a Directory (tenant) ID, and a client secret are returned. Copy these values and store them in a secure place. You need them in the following steps.

Set the values of the Application (client) ID, Directory (tenant) ID, and client secret of your Microsoft Entra application, and the map resource’s client ID as environment variables:

Environment Variable	Description
AZURE_CLIENT_ID	Application (client) ID in your registered application
AZURE_CLIENT_SECRET	The value of the client secret in your registered application
AZURE_TENANT_ID	Directory (tenant) ID in your registered application
MAPS_CLIENT_ID	The client ID in your Azure Map resource

Now you can create environment variables in PowerShell to store these values:

$Env:AZURE_CLIENT_ID="Application (client) ID"
$Env:AZURE_CLIENT_SECRET="your client secret"
$Env:AZURE_TENANT_ID="your Directory (tenant) ID"
$Env:MAPS_CLIENT_ID="your Azure Maps client ID"

After setting up the environment variables, you can use them in your program to instantiate the AzureMapsSearch client:

using System;
using Azure.Identity; 
using Azure.Maps.Search; 

var credential = new DefaultAzureCredential(); 
var clientId = Environment.GetEnvironmentVariable("MAPS_CLIENT_ID"); 
var client = new MapsSearchClient(credential, clientId); 

Important

The other environment variables created in the previous code snippet, while not used in the code sample, are required by DefaultAzureCredential(). If you do not set these environment variables correctly, using the same naming conventions, you will get run-time errors. For example, if your AZURE_CLIENT_ID is missing or invalid you will get an InvalidAuthenticationTokenTenant error.

Using a subscription key credential

You can authenticate with your Azure Maps subscription key. Your subscription key can be found in the Authentication section in the Azure Maps account as shown in the following screenshot:

Now you can create environment variables in PowerShell to store the subscription key:

$Env:SUBSCRIPTION_KEY="your subscription key"

Once your environment variable is created, you can access it in your code:

using System;
using Azure; 
using Azure.Maps.Search; 

// Use Azure Maps subscription key authentication 
var subscriptionKey = Environment.GetEnvironmentVariable("SUBSCRIPTION_KEY") ?? string.Empty;
var credential = new AzureKeyCredential(subscriptionKey);
var client = new MapsSearchClient(credential); 

Geocode an address

Call the GetGeocoding method to get the coordinate of an address.

using System;
using Azure; 
using Azure.Maps.Search; 
using Azure.Maps.Search.Models;

// Use Azure Maps subscription key authentication 
var subscriptionKey = Environment.GetEnvironmentVariable("SUBSCRIPTION_KEY") ?? string.Empty;
var credential = new AzureKeyCredential(subscriptionKey);
var client = new MapsSearchClient(credential); 

Response<GeocodingResponse> searchResult = client.GetGeocoding(
    "1 Microsoft Way, Redmond, WA 98052");

for (int i = 0; i < searchResult.Value.Features.Count; i++)
{
    Console.WriteLine("Coordinate:" + string.Join(",", searchResult.Value.Features[i].Geometry.Coordinates));
}

Batch geocode addresses

This sample demonstrates how to perform batch search address.

using System;
using Azure; 
using Azure.Maps.Search; 
using System.Collections.Generic;
using Azure.Maps.Search.Models;
using Azure.Maps.Search.Models.Queries;

// Use Azure Maps subscription key authentication 
var subscriptionKey = Environment.GetEnvironmentVariable("SUBSCRIPTION_KEY") ?? string.Empty;
var credential = new AzureKeyCredential(subscriptionKey);
var client = new MapsSearchClient(credential); 

List<GeocodingQuery> queries = new List<GeocodingQuery>
{
    new GeocodingQuery()
    {
        Query ="15171 NE 24th St, Redmond, WA 98052, United States"
    },
    new GeocodingQuery()
    {
        AddressLine = "400 Broad St"
    },
};
Response<GeocodingBatchResponse> results = client.GetGeocodingBatch(queries);

//Print coordinates
for (var i = 0; i < results.Value.BatchItems.Count; i++)
{
    for (var j = 0; j < results.Value.BatchItems[i].Features.Count; j++)
    {
        Console.WriteLine("Coordinates: " + string.Join(",", results.Value.BatchItems[i].Features[j].Geometry.Coordinates));
    }
}

Reverse geocode a coordinates

You can translate coordinates into human-readable street addresses. This process is also called reverse geocoding.

using System;
using Azure; 
using Azure.Maps.Search; 
using Azure.Core.GeoJson;
using Azure.Maps.Search.Models;

// Use Azure Maps subscription key authentication 
var subscriptionKey = Environment.GetEnvironmentVariable("SUBSCRIPTION_KEY") ?? string.Empty;
var credential = new AzureKeyCredential(subscriptionKey);
var client = new MapsSearchClient(credential); 

GeoPosition coordinates = new GeoPosition(-122.138685, 47.6305637);
Response<GeocodingResponse> result = client.GetReverseGeocoding(coordinates);

//Print addresses
for (int i = 0; i < result.Value.Features.Count; i++)
{
    Console.WriteLine(result.Value.Features[i].Properties.Address.FormattedAddress);
}

Batch reverse geocode a set of coordinates

Azure Maps Search also provides some batch query APIs. The Reverse Geocoding Batch API sends batches of queries to Reverse Geocoding API using just a single API call. The API allows caller to batch up to 100 queries.

using System;
using Azure; 
using Azure.Maps.Search; 
using System.Collections.Generic;
using Azure.Core.GeoJson;
using Azure.Maps.Search.Models;
using Azure.Maps.Search.Models.Queries;

// Use Azure Maps subscription key authentication 
var subscriptionKey = Environment.GetEnvironmentVariable("SUBSCRIPTION_KEY") ?? string.Empty;
var credential = new AzureKeyCredential(subscriptionKey);
var client = new MapsSearchClient(credential);

List<ReverseGeocodingQuery> items = new List<ReverseGeocodingQuery>
{
    new ReverseGeocodingQuery()
    {
        Coordinates = new GeoPosition(-122.349309, 47.620498)
    },
    new ReverseGeocodingQuery()
    {
        Coordinates = new GeoPosition(-122.138679, 47.630356),
        ResultTypes = new List<ReverseGeocodingResultTypeEnum>(){ ReverseGeocodingResultTypeEnum.Address, ReverseGeocodingResultTypeEnum.Neighborhood }
    },
};
Response<GeocodingBatchResponse> result = client.GetReverseGeocodingBatch(items);
//Print addresses
for (var i = 0; i < result.Value.BatchItems.Count; i++)
{
    Console.WriteLine(result.Value.BatchItems[i].Features[0].Properties.Address.AddressLine);
    Console.WriteLine(result.Value.BatchItems[i].Features[0].Properties.Address.Neighborhood);
}

Get polygons for a given location

This sample demonstrates how to search polygons.

using System;
using Azure; 
using Azure.Maps.Search; 
using Azure.Core.GeoJson;
using Azure.Maps.Search.Models;
using Azure.Maps.Search.Models.Options;

// Use Azure Maps subscription key authentication 
var subscriptionKey = Environment.GetEnvironmentVariable("SUBSCRIPTION_KEY") ?? string.Empty;
var credential = new AzureKeyCredential(subscriptionKey);
var client = new MapsSearchClient(credential);

GetPolygonOptions options = new GetPolygonOptions()
{
    Coordinates = new GeoPosition(-122.204141, 47.61256),
    ResultType = BoundaryResultTypeEnum.Locality,
    Resolution = ResolutionEnum.Small,
};
Response<Boundary> result = client.GetPolygon(options);

var count = ((GeoJsonPolygon)((GeoJsonGeometryCollection)result.Value.Geometry).Geometries[0]).Coordinates.Count;
for (var i = 0; i < count; i++)
{
    var coorCount = ((GeoJsonPolygon)((GeoJsonGeometryCollection)result.Value.Geometry).Geometries[0]).Coordinates[i].Count;
    for (var j = 0; j < coorCount; j++)
    {
        Console.WriteLine(string.Join(",",((GeoJsonPolygon)((GeoJsonGeometryCollection)result.Value.Geometry).Geometries[0]).Coordinates[i][j]));
    }
}

Using V1 SDKs for Search and Render

For more information on using Search v1, see Azure Maps Search client library for .NET. For more information on using Render v1, see Azure Maps Render client library for .NET.

Additional information

The Azure.Maps Namespace in the .NET documentation.