Azure.Maps.Search 1.0.0-beta.1

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" --disable-local-auth true --account-name "myMapAccountName" --resource-group "<resource group>" --sku "G2" --accept-tos

Authenticate the client

There are 2 ways to authenticate the client: Shared key authentication and Azure AD.

Shared Key Authentication

• Go to Azure Maps account > Authentication tab
• Copy Primary Key or Secondary Key under Shared Key Authentication section

// Create a SearchClient that will authenticate through Subscription Key (Shared key)
var credential = new AzureKeyCredential("<My Subscription Key>");
MapsSearchClient client = new MapsSearchClient(credential);

Azure AD 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 AAD 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 AAD
var credential = new DefaultAzureCredential();
var clientId = "<My Map Account Client Id>";
MapsSearchClient client = new MapsSearchClient(credential, clientId);

Key concepts

MapsSearchClient is designed for:

• 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 about examples in 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 Samples.

Example Get Polygons

// Get Addresses
var searchResult = await client.SearchAddressAsync("Seattle");

// Extract geometry ids from addresses
var geometry0Id = searchResult.Value.Results.First().DataSources.Geometry.Id;
var geometry1Id = searchResult.Value.Results[1].DataSources.Geometry.Id;

// Extract position coordinates
var positionCoordinates = searchResult.Value.Results.First().Position;

// Get polygons from geometry ids
PolygonResult polygonResponse = await client.GetPolygonsAsync(new[] { geometry0Id, geometry1Id });

Example Fuzzy Search

var fuzzySearchResponse = await client.FuzzySearchAsync("coffee", new FuzzySearchOptions {
    Coordinates = new GeoPosition(121.56, 25.04),
    Language = "en"
});

Example Reverse Search Cross Street Address

var reverseResult = await client.ReverseSearchCrossStreetAddressAsync(new ReverseSearchCrossStreetOptions {
    coordinates = new GeoPosition(121.0, 24.0),
    Language = "en"
});

Example Search Structured Address

var address = new StructuredAddress {
    CountryCode = "US",
    StreetNumber = "15127",
    StreetName = "NE 24th Street",
    Municipality = "Redmond",
    CountrySubdivision = "WA",
    PostalCode = "98052"
};
var searchResult = await client.SearchStructuredAddressAsync(address);

Example Search Inside Geometry

var sfPolygon = new GeoPolygon(new[]
{
    new GeoPosition(-122.43576049804686, 37.752415234354402),
    new GeoPosition(-122.4330139160, 37.706604725423119),
    new GeoPosition(-122.36434936523438, 37.712059855877314),
    new GeoPosition(-122.43576049804686, 37.7524152343544)
});

var taipeiPolygon = new GeoPolygon(new[]
{
    new GeoPosition(121.56, 25.04),
    new GeoPosition(121.565, 25.04),
    new GeoPosition(121.565, 25.045),
    new GeoPosition(121.56, 25.045),
    new GeoPosition(121.56, 25.04)
});

var searchResponse = await client.SearchInsideGeometryAsync("coffee", new GeoCollection(new[] { sfPolygon, taipeiPolygon }), new SearchInsideGeometryOptions {
    Language = "en"
});

Example Search Address

var searchResult = await client.SearchAddressAsync("Seattle");

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

• More detailed samples

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.