Azure.Maps.Search
2.0.0-beta.2
Prefix Reserved
See the version list below for details.
dotnet add package Azure.Maps.Search --version 2.0.0-beta.2
NuGet\Install-Package Azure.Maps.Search -Version 2.0.0-beta.2
<PackageReference Include="Azure.Maps.Search" Version="2.0.0-beta.2" />
paket add Azure.Maps.Search --version 2.0.0-beta.2
#r "nuget: Azure.Maps.Search, 2.0.0-beta.2"
// Install Azure.Maps.Search as a Cake Addin #addin nuget:?package=Azure.Maps.Search&version=2.0.0-beta.2&prerelease // Install Azure.Maps.Search as a Cake Tool #tool nuget:?package=Azure.Maps.Search&version=2.0.0-beta.2&prerelease
Azure Maps Search client library for .NET
Azure Maps Search is a library that can query for locations, points of interests or search within a geometric area.
Source code | API reference documentation | REST API reference documentation | Product documentation
Getting started
Install the package
Install the client library for .NET with NuGet:
dotnet add package Azure.Maps.Search --prerelease
Prerequisites
You must have an Azure subscription and Azure Maps account.
To create a new Azure Maps account, you can use the Azure Portal, Azure PowerShell, or the Azure CLI. Here's an example using the Azure CLI:
az maps account create --kind "Gen2" --account-name "myMapAccountName" --resource-group "<resource group>" --sku "G2"
Authenticate the client
There are 3 ways to authenticate the client: Shared key authentication, Microsoft Entra authentication and shared access signature (SAS) authentication.
Shared Key Authentication
- Go to Azure Maps account > Authentication tab
- Copy
Primary Key
orSecondary Key
under Shared Key Authentication section
// Create a SearchClient that will authenticate through Subscription Key (Shared key)
AzureKeyCredential credential = new AzureKeyCredential("<My Subscription Key>");
MapsSearchClient client = new MapsSearchClient(credential);
Microsoft Entra Authentication
In order to interact with the Azure Maps service, you'll need to create an instance of the MapsSearchClient class. The Azure Identity library makes it easy to add Azure Active Directory support for authenticating Azure SDK clients with their corresponding Azure services.
To use Microsoft Entra authentication, set TENANT_ID
, CLIENT_ID
, and CLIENT_SECRET
to environment variable and call DefaultAzureCredential()
method to get credential. CLIENT_ID
and CLIENT_SECRET
are the service principal ID and secret that can access Azure Maps account.
We also need Azure Maps Client ID which can get from Azure Maps page > Authentication tab > "Client ID" in Azure Active Directory Authentication section.
// Create a MapsSearchClient that will authenticate through Microsoft Entra
DefaultAzureCredential credential = new DefaultAzureCredential();
string clientId = "<My Map Account Client Id>";
MapsSearchClient client = new MapsSearchClient(credential, clientId);
Shared Access Signature (SAS) Authentication
Shared access signature (SAS) tokens are authentication tokens created using the JSON Web token (JWT) format and are cryptographically signed to prove authentication for an application to the Azure Maps REST API.
Before integrating SAS token authentication, we need to install Azure.ResourceManager
and Azure.ResourceManager.Maps
(version 1.1.0-beta.2
or higher):
dotnet add package Azure.ResourceManager
dotnet add package Azure.ResourceManager.Maps --prerelease
In the code, we need to import the following lines for both Azure Maps SDK and ResourceManager:
using Azure.Maps.Search.Models;
using Azure.Core;
using Azure.ResourceManager;
using Azure.ResourceManager.Maps;
using Azure.ResourceManager.Maps.Models;
And then we can get SAS token via List Sas API and assign it to MapsSearchClient
. In the follow code sample, we fetch a specific maps account resource, and create a SAS token for 1 day expiry time when the code is executed.
// Get your azure access token, for more details of how Azure SDK get your access token, please refer to https://learn.microsoft.com/en-us/dotnet/azure/sdk/authentication?tabs=command-line
TokenCredential cred = new DefaultAzureCredential();
// Authenticate your client
ArmClient armClient = new ArmClient(cred);
string subscriptionId = "MyMapsSubscriptionId";
string resourceGroupName = "MyMapsResourceGroupName";
string accountName = "MyMapsAccountName";
// Get maps account resource
ResourceIdentifier mapsAccountResourceId = MapsAccountResource.CreateResourceIdentifier(subscriptionId, resourceGroupName, accountName);
MapsAccountResource mapsAccount = armClient.GetMapsAccountResource(mapsAccountResourceId);
// Assign SAS token information
// Every time you want to SAS token, update the principal ID, max rate, start and expiry time
string principalId = "MyManagedIdentityObjectId";
int maxRatePerSecond = 500;
// Set start and expiry time for the SAS token in round-trip date/time format
DateTime now = DateTime.Now;
string start = now.ToString("O");
string expiry = now.AddDays(1).ToString("O");
MapsAccountSasContent sasContent = new MapsAccountSasContent(MapsSigningKey.PrimaryKey, principalId, maxRatePerSecond, start, expiry);
Response<MapsAccountSasToken> sas = mapsAccount.GetSas(sasContent);
// Create a SearchClient that will authenticate via SAS token
AzureSasCredential sasCredential = new AzureSasCredential(sas.Value.AccountSasToken);
MapsSearchClient client = new MapsSearchClient(sasCredential);
Key concepts
MapsSearchClient
is designed to:
- Communicate with Azure Maps endpoint to query addresses or points of locations
- Communicate with Azure Maps endpoint to request the geometry data such as a city or country outline for a set of entities
- Communicate with Azure Maps endpoint to perform a free form search inside a single geometry or many of them
Learn more by viewing our samples
Thread safety
We guarantee that all client instance methods are thread-safe and independent of each other (guideline). This ensures that the recommendation of reusing client instances is always safe, even across threads.
Additional concepts
Client options | Accessing the response | Long-running operations | Handling failures | Diagnostics | Mocking | Client lifetime
Examples
You can familiarize yourself with different APIs using our samples.
Example Get Geocoding
var query = "15171 NE 24th St, Redmond, WA 98052, United States";
Response <GeocodingResponse> result = client.GetGeocoding(query);
Console.WriteLine("Result for query: \"{0}\"", query);
Console.WriteLine(result);
Example Get Geocoding Batch
List<GeocodingQuery> queries = new List<GeocodingQuery>
{
new GeocodingQuery()
{
Query ="15171 NE 24th St, Redmond, WA 98052, United States"
},
new GeocodingQuery()
{
Coordinates = new GeoPosition(121.5, 25.0)
},
};
Response<GeocodingBatchResponse> results = client.GetGeocodingBatch(queries);
Console.WriteLine(results);
Example Get Polygon
GetPolygonOptions options = new GetPolygonOptions()
{
Coordinates = new GeoPosition(121.5, 25.0)
};
Response<Boundary> result = client.GetPolygon(options);
Console.WriteLine(result);
Example Get Reverse Geocoding
GeoPosition coordinates = new GeoPosition(-122.138685, 47.6305637);
Response<GeocodingResponse> result = client.GetReverseGeocoding(coordinates);
Example Get Reverse Geocoding Batch
List<ReverseGeocodingQuery> items = new List<ReverseGeocodingQuery>
{
new ReverseGeocodingQuery()
{
Coordinates = new GeoPosition(121.53, 25.0)
},
new ReverseGeocodingQuery()
{
Coordinates = new GeoPosition(121.5, 25.0)
},
};
Response<GeocodingBatchResponse> result = client.GetReverseGeocodingBatch(items);
Troubleshooting
General
When you interact with the Azure Maps Services, errors returned by the Language service correspond to the same HTTP status codes returned for REST API requests.
For example, if you try to search with invalid coordinates, a error is returned, indicating "Bad Request".400
Next steps
Contributing
See the CONTRIBUTING.md for details on building, testing, and contributing to this library.
This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit <cla.microsoft.com>.
When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net5.0 was computed. net5.0-windows was computed. net6.0 was computed. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 was computed. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 was computed. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
.NET Core | netcoreapp2.0 was computed. netcoreapp2.1 was computed. netcoreapp2.2 was computed. netcoreapp3.0 was computed. netcoreapp3.1 was computed. |
.NET Standard | netstandard2.0 is compatible. netstandard2.1 was computed. |
.NET Framework | net461 was computed. net462 was computed. net463 was computed. net47 was computed. net471 was computed. net472 was computed. net48 was computed. net481 was computed. |
MonoAndroid | monoandroid was computed. |
MonoMac | monomac was computed. |
MonoTouch | monotouch was computed. |
Tizen | tizen40 was computed. tizen60 was computed. |
Xamarin.iOS | xamarinios was computed. |
Xamarin.Mac | xamarinmac was computed. |
Xamarin.TVOS | xamarintvos was computed. |
Xamarin.WatchOS | xamarinwatchos was computed. |
-
.NETStandard 2.0
- Azure.Core (>= 1.42.0)
- Azure.Maps.Common (>= 1.0.0-beta.4)
- System.Text.Json (>= 4.7.2)
NuGet packages (2)
Showing the top 2 NuGet packages that depend on Azure.Maps.Search:
Package | Downloads |
---|---|
AzureAI.Community.Microsoft.Semantic.Kernel.PlugIn.Web.BingMap
AzureAI.Community Microsoft Semantic Kernel.PlugIn.Bing |
|
AzureMapVisualizer
AzureLocationMapVisualizer is a .NET class library that enables developers to generate location-based images using Azure Maps. With this library, you can create beautiful and informative maps that are customized to fit your application's needs. |
GitHub repositories
This package is not used by any popular GitHub repositories.
Version | Downloads | Last updated |
---|---|---|
2.0.0-beta.4 | 170 | 9/30/2024 |
2.0.0-beta.3 | 201 | 9/23/2024 |
2.0.0-beta.2 | 2,766 | 8/13/2024 |
2.0.0-beta.1 | 89 | 8/12/2024 |
1.0.0-beta.5 | 20,571 | 5/10/2024 |
1.0.0-beta.4 | 139,012 | 7/13/2023 |
1.0.0-beta.3 | 42,236 | 11/11/2022 |
1.0.0-beta.2 | 12,017 | 10/13/2022 |
1.0.0-beta.1 | 15,737 | 9/9/2022 |