Azure Maps Search Dotnet

1---
2name: azure-maps-search-dotnet
3description: |
4  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".
5package: Azure.Maps.Search
6---
7 
8# Azure Maps (.NET)
9 
10Azure Maps SDK for .NET providing location-based services: geocoding, routing, rendering, geolocation, and weather.
11 
12## Installation
13 
14```bash
15# Search (geocoding, reverse geocoding)
16dotnet add package Azure.Maps.Search --prerelease
17 
18# Routing (directions, route matrix)
19dotnet add package Azure.Maps.Routing --prerelease
20 
21# Rendering (map tiles, static images)
22dotnet add package Azure.Maps.Rendering --prerelease
23 
24# Geolocation (IP to location)
25dotnet add package Azure.Maps.Geolocation --prerelease
26 
27# Weather
28dotnet add package Azure.Maps.Weather --prerelease
29 
30# Resource Management (account management, SAS tokens)
31dotnet add package Azure.ResourceManager.Maps --prerelease
32 
33# Required for authentication
34dotnet add package Azure.Identity
35```
36 
37**Current Versions**:
38- `Azure.Maps.Search`: v2.0.0-beta.5
39- `Azure.Maps.Routing`: v1.0.0-beta.4
40- `Azure.Maps.Rendering`: v2.0.0-beta.1
41- `Azure.Maps.Geolocation`: v1.0.0-beta.3
42- `Azure.ResourceManager.Maps`: v1.1.0-beta.2
43 
44## Environment Variables
45 
46```bash
47AZURE_MAPS_SUBSCRIPTION_KEY=<your-subscription-key>
48AZURE_MAPS_CLIENT_ID=<your-client-id>  # For Entra ID auth
49```
50 
51## Authentication
52 
53### Subscription Key (Shared Key)
54 
55```csharp
56using Azure;
57using Azure.Maps.Search;
58 
59var subscriptionKey = Environment.GetEnvironmentVariable("AZURE_MAPS_SUBSCRIPTION_KEY");
60var credential = new AzureKeyCredential(subscriptionKey);
61 
62var client = new MapsSearchClient(credential);
63```
64 
65### Microsoft Entra ID (Recommended for Production)
66 
67```csharp
68using Azure.Identity;
69using Azure.Maps.Search;
70 
71var credential = new DefaultAzureCredential();
72var clientId = Environment.GetEnvironmentVariable("AZURE_MAPS_CLIENT_ID");
73 
74var client = new MapsSearchClient(credential, clientId);
75```
76 
77### Shared Access Signature (SAS)
78 
79```csharp
80using Azure;
81using Azure.Core;
82using Azure.Identity;
83using Azure.ResourceManager;
84using Azure.ResourceManager.Maps;
85using Azure.ResourceManager.Maps.Models;
86using Azure.Maps.Search;
87 
88// Authenticate with Azure Resource Manager
89ArmClient armClient = new ArmClient(new DefaultAzureCredential());
90 
91// Get Maps account resource
92ResourceIdentifier mapsAccountResourceId = MapsAccountResource.CreateResourceIdentifier(
93    subscriptionId, resourceGroupName, accountName);
94MapsAccountResource mapsAccount = armClient.GetMapsAccountResource(mapsAccountResourceId);
95 
96// Generate SAS token
97MapsAccountSasContent sasContent = new MapsAccountSasContent(
98    MapsSigningKey.PrimaryKey, 
99    principalId, 
100    maxRatePerSecond: 500, 
101    start: DateTime.UtcNow.ToString("O"), 
102    expiry: DateTime.UtcNow.AddDays(1).ToString("O"));
103 
104Response<MapsAccountSasToken> sas = mapsAccount.GetSas(sasContent);
105 
106// Create client with SAS token
107var sasCredential = new AzureSasCredential(sas.Value.AccountSasToken);
108var client = new MapsSearchClient(sasCredential);
109```
110 
111## Client Hierarchy
112 
113```
114Azure.Maps.Search
115└── MapsSearchClient
116    ├── GetGeocoding()                    → Geocode addresses
117    ├── GetGeocodingBatch()               → Batch geocoding
118    ├── GetReverseGeocoding()             → Coordinates to address
119    ├── GetReverseGeocodingBatch()        → Batch reverse geocoding
120    └── GetPolygon()                      → Get boundary polygons
121 
122Azure.Maps.Routing
123└── MapsRoutingClient
124    ├── GetDirections()                   → Route directions
125    ├── GetImmediateRouteMatrix()         → Route matrix (sync, ≤100)
126    ├── GetRouteMatrix()                  → Route matrix (async, ≤700)
127    └── GetRouteRange()                   → Isochrone/reachable range
128 
129Azure.Maps.Rendering
130└── MapsRenderingClient
131    ├── GetMapTile()                      → Map tiles
132    ├── GetMapStaticImage()               → Static map images
133    └── GetCopyrightCaption()             → Copyright info
134 
135Azure.Maps.Geolocation
136└── MapsGeolocationClient
137    └── GetCountryCode()                  → IP to country/region
138 
139Azure.Maps.Weather
140└── MapsWeatherClient
141    ├── GetCurrentWeatherConditions()     → Current weather
142    ├── GetDailyForecast()                → Daily forecast
143    ├── GetHourlyForecast()               → Hourly forecast
144    └── GetSevereWeatherAlerts()          → Weather alerts
145```
146 
147## Core Workflows
148 
149### 1. Geocoding (Address to Coordinates)
150 
151```csharp
152using Azure;
153using Azure.Maps.Search;
154 
155var credential = new AzureKeyCredential(subscriptionKey);
156var client = new MapsSearchClient(credential);
157 
158Response<GeocodingResponse> result = client.GetGeocoding("1 Microsoft Way, Redmond, WA 98052");
159 
160foreach (var feature in result.Value.Features)
161{
162    Console.WriteLine($"Coordinates: {string.Join(",", feature.Geometry.Coordinates)}");
163    Console.WriteLine($"Address: {feature.Properties.Address.FormattedAddress}");
164    Console.WriteLine($"Confidence: {feature.Properties.Confidence}");
165}
166```
167 
168### 2. Batch Geocoding
169 
170```csharp
171using Azure.Maps.Search.Models.Queries;
172 
173List<GeocodingQuery> queries = new List<GeocodingQuery>
174{
175    new GeocodingQuery() { Query = "400 Broad St, Seattle, WA" },
176    new GeocodingQuery() { Query = "1 Microsoft Way, Redmond, WA" },
177    new GeocodingQuery() { AddressLine = "Space Needle", Top = 1 },
178};
179 
180Response<GeocodingBatchResponse> results = client.GetGeocodingBatch(queries);
181 
182foreach (var batchItem in results.Value.BatchItems)
183{
184    foreach (var feature in batchItem.Features)
185    {
186        Console.WriteLine($"Coordinates: {string.Join(",", feature.Geometry.Coordinates)}");
187    }
188}
189```
190 
191### 3. Reverse Geocoding (Coordinates to Address)
192 
193```csharp
194using Azure.Core.GeoJson;
195 
196GeoPosition coordinates = new GeoPosition(-122.138685, 47.6305637);
197Response<GeocodingResponse> result = client.GetReverseGeocoding(coordinates);
198 
199foreach (var feature in result.Value.Features)
200{
201    Console.WriteLine($"Address: {feature.Properties.Address.FormattedAddress}");
202    Console.WriteLine($"Locality: {feature.Properties.Address.Locality}");
203}
204```
205 
206### 4. Get Boundary Polygon
207 
208```csharp
209using Azure.Maps.Search.Models;
210 
211GetPolygonOptions options = new GetPolygonOptions()
212{
213    Coordinates = new GeoPosition(-122.204141, 47.61256),
214    ResultType = BoundaryResultTypeEnum.Locality,
215    Resolution = ResolutionEnum.Small,
216};
217 
218Response<Boundary> result = client.GetPolygon(options);
219 
220Console.WriteLine($"Boundary copyright: {result.Value.Properties?.Copyright}");
221Console.WriteLine($"Polygon count: {result.Value.Geometry.Count}");
222```
223 
224### 5. Route Directions
225 
226```csharp
227using Azure;
228using Azure.Core.GeoJson;
229using Azure.Maps.Routing;
230using Azure.Maps.Routing.Models;
231 
232var client = new MapsRoutingClient(new AzureKeyCredential(subscriptionKey));
233 
234List<GeoPosition> routePoints = new List<GeoPosition>()
235{
236    new GeoPosition(-122.34, 47.61),  // Seattle
237    new GeoPosition(-122.13, 47.64)   // Redmond
238};
239 
240RouteDirectionQuery query = new RouteDirectionQuery(routePoints);
241Response<RouteDirections> result = client.GetDirections(query);
242 
243foreach (var route in result.Value.Routes)
244{
245    Console.WriteLine($"Distance: {route.Summary.LengthInMeters} meters");
246    Console.WriteLine($"Duration: {route.Summary.TravelTimeDuration}");
247    
248    foreach (RouteLeg leg in route.Legs)
249    {
250        Console.WriteLine($"Leg points: {leg.Points.Count}");
251    }
252}
253```
254 
255### 6. Route Directions with Options
256 
257```csharp
258RouteDirectionOptions options = new RouteDirectionOptions()
259{
260    RouteType = RouteType.Fastest,
261    UseTrafficData = true,
262    TravelMode = TravelMode.Bicycle,
263    Language = RoutingLanguage.EnglishUsa,
264    InstructionsType = RouteInstructionsType.Text,
265};
266 
267RouteDirectionQuery query = new RouteDirectionQuery(routePoints)
268{
269    RouteDirectionOptions = options
270};
271 
272Response<RouteDirections> result = client.GetDirections(query);
273```
274 
275### 7. Route Matrix
276 
277```csharp
278RouteMatrixQuery routeMatrixQuery = new RouteMatrixQuery
279{
280    Origins = new List<GeoPosition>()
281    {
282        new GeoPosition(-122.34, 47.61),
283        new GeoPosition(-122.13, 47.64)
284    },
285    Destinations = new List<GeoPosition>() 
286    { 
287        new GeoPosition(-122.20, 47.62),
288        new GeoPosition(-122.40, 47.65)
289    },
290};
291 
292// Synchronous (up to 100 route combinations)
293Response<RouteMatrixResult> result = client.GetImmediateRouteMatrix(routeMatrixQuery);
294 
295foreach (var cell in result.Value.Matrix.SelectMany(row => row))
296{
297    Console.WriteLine($"Distance: {cell.Response?.RouteSummary?.LengthInMeters}");
298    Console.WriteLine($"Duration: {cell.Response?.RouteSummary?.TravelTimeDuration}");
299}
300 
301// Asynchronous (up to 700 route combinations)
302RouteMatrixOptions routeMatrixOptions = new RouteMatrixOptions(routeMatrixQuery)
303{
304    TravelTimeType = TravelTimeType.All,
305};
306GetRouteMatrixOperation asyncResult = client.GetRouteMatrix(WaitUntil.Completed, routeMatrixOptions);
307```
308 
309### 8. Route Range (Isochrone)
310 
311```csharp
312RouteRangeOptions options = new RouteRangeOptions(-122.34, 47.61)
313{
314    TimeBudget = new TimeSpan(0, 20, 0)  // 20 minutes
315};
316 
317Response<RouteRangeResult> result = client.GetRouteRange(options);
318 
319// result.Value.ReachableRange contains the polygon
320Console.WriteLine($"Boundary points: {result.Value.ReachableRange.Boundary.Count}");
321```
322 
323### 9. Get Map Tiles
324 
325```csharp
326using Azure;
327using Azure.Maps.Rendering;
328 
329var client = new MapsRenderingClient(new AzureKeyCredential(subscriptionKey));
330 
331int zoom = 10;
332int tileSize = 256;
333 
334// Convert coordinates to tile index
335MapTileIndex tileIndex = MapsRenderingClient.PositionToTileXY(
336    new GeoPosition(13.3854, 52.517), zoom, tileSize);
337 
338// Fetch map tile
339GetMapTileOptions options = new GetMapTileOptions(
340    MapTileSetId.MicrosoftImagery,
341    new MapTileIndex(tileIndex.X, tileIndex.Y, zoom)
342);
343 
344Response<Stream> mapTile = client.GetMapTile(options);
345 
346// Save to file
347using (FileStream fileStream = File.Create("./MapTile.png"))
348{
349    mapTile.Value.CopyTo(fileStream);
350}
351```
352 
353### 10. IP Geolocation
354 
355```csharp
356using System.Net;
357using Azure;
358using Azure.Maps.Geolocation;
359 
360var client = new MapsGeolocationClient(new AzureKeyCredential(subscriptionKey));
361 
362IPAddress ipAddress = IPAddress.Parse("2001:4898:80e8:b::189");
363Response<CountryRegionResult> result = client.GetCountryCode(ipAddress);
364 
365Console.WriteLine($"Country ISO Code: {result.Value.IsoCode}");
366```
367 
368### 11. Current Weather
369 
370```csharp
371using Azure;
372using Azure.Core.GeoJson;
373using Azure.Maps.Weather;
374 
375var client = new MapsWeatherClient(new AzureKeyCredential(subscriptionKey));
376 
377var position = new GeoPosition(-122.13071, 47.64011);
378var options = new GetCurrentWeatherConditionsOptions(position);
379 
380Response<CurrentConditionsResult> result = client.GetCurrentWeatherConditions(options);
381 
382foreach (var condition in result.Value.Results)
383{
384    Console.WriteLine($"Temperature: {condition.Temperature.Value} {condition.Temperature.Unit}");
385    Console.WriteLine($"Weather: {condition.Phrase}");
386    Console.WriteLine($"Humidity: {condition.RelativeHumidity}%");
387}
388```
389 
390## Key Types Reference
391 
392### Search Package
393 
394| Type | Purpose |
395|------|---------|
396| `MapsSearchClient` | Main client for search operations |
397| `GeocodingResponse` | Geocoding result |
398| `GeocodingBatchResponse` | Batch geocoding result |
399| `GeocodingQuery` | Query for batch geocoding |
400| `ReverseGeocodingQuery` | Query for batch reverse geocoding |
401| `GetPolygonOptions` | Options for polygon retrieval |
402| `Boundary` | Boundary polygon result |
403| `BoundaryResultTypeEnum` | Boundary type (Locality, AdminDistrict, etc.) |
404| `ResolutionEnum` | Polygon resolution (Small, Medium, Large) |
405 
406### Routing Package
407 
408| Type | Purpose |
409|------|---------|
410| `MapsRoutingClient` | Main client for routing operations |
411| `RouteDirectionQuery` | Query for route directions |
412| `RouteDirectionOptions` | Route calculation options |
413| `RouteDirections` | Route directions result |
414| `RouteLeg` | Segment of a route |
415| `RouteMatrixQuery` | Query for route matrix |
416| `RouteMatrixResult` | Route matrix result |
417| `RouteRangeOptions` | Options for isochrone |
418| `RouteRangeResult` | Isochrone result |
419| `RouteType` | Route type (Fastest, Shortest, Eco, Thrilling) |
420| `TravelMode` | Travel mode (Car, Truck, Bicycle, Pedestrian) |
421 
422### Rendering Package
423 
424| Type | Purpose |
425|------|---------|
426| `MapsRenderingClient` | Main client for rendering |
427| `GetMapTileOptions` | Map tile options |
428| `MapTileIndex` | Tile coordinates (X, Y, Zoom) |
429| `MapTileSetId` | Tile set identifier |
430 
431### Common Types
432 
433| Type | Purpose |
434|------|---------|
435| `GeoPosition` | Geographic position (longitude, latitude) |
436| `GeoBoundingBox` | Bounding box for geographic area |
437 
438## Best Practices
439 
4401. **Use Entra ID for production** — Prefer over subscription keys
4412. **Batch operations** — Use batch geocoding for multiple addresses
4423. **Cache results** — Geocoding results don't change frequently
4434. **Use appropriate tile sizes** — 256 or 512 pixels based on display
4445. **Handle rate limits** — Implement exponential backoff
4456. **Use async route matrix** — For large matrix calculations (>100)
4467. **Consider traffic data** — Set `UseTrafficData = true` for accurate ETAs
447 
448## Error Handling
449 
450```csharp
451try
452{
453    Response<GeocodingResponse> result = client.GetGeocoding(address);
454}
455catch (RequestFailedException ex)
456{
457    Console.WriteLine($"Status: {ex.Status}");
458    Console.WriteLine($"Error: {ex.Message}");
459    
460    switch (ex.Status)
461    {
462        case 400:
463            // Invalid request parameters
464            break;
465        case 401:
466            // Authentication failed
467            break;
468        case 429:
469            // Rate limited - implement backoff
470            break;
471    }
472}
473```
474 
475## Related SDKs
476 
477| SDK | Purpose | Install |
478|-----|---------|---------|
479| `Azure.Maps.Search` | Geocoding, search | `dotnet add package Azure.Maps.Search --prerelease` |
480| `Azure.Maps.Routing` | Directions, matrix | `dotnet add package Azure.Maps.Routing --prerelease` |
481| `Azure.Maps.Rendering` | Map tiles, images | `dotnet add package Azure.Maps.Rendering --prerelease` |
482| `Azure.Maps.Geolocation` | IP geolocation | `dotnet add package Azure.Maps.Geolocation --prerelease` |
483| `Azure.Maps.Weather` | Weather data | `dotnet add package Azure.Maps.Weather --prerelease` |
484| `Azure.ResourceManager.Maps` | Account management | `dotnet add package Azure.ResourceManager.Maps --prerelease` |
485 
486## Reference Links
487 
488| Resource | URL |
489|----------|-----|
490| Azure Maps Documentation | https://learn.microsoft.com/azure/azure-maps/ |
491| Search API Reference | https://learn.microsoft.com/dotnet/api/azure.maps.search |
492| Routing API Reference | https://learn.microsoft.com/dotnet/api/azure.maps.routing |
493| GitHub Source | https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/maps |
494| Pricing | https://azure.microsoft.com/pricing/details/azure-maps/ |
495