How to Fix Azure Maps: Setup, Auth & API Errors
Why This Is Happening
I've seen this exact situation play out dozens of times: a developer spins up an Azure Maps account, drops the subscription key into their web app, opens the browser , and nothing loads. Just a gray box where the map should be, or worse, a silent 401 buried in the browser console. It's maddening, especially when your deadline is today.
Azure Maps is Microsoft's collection of geospatial services and SDKs, covering everything from address geocoding and turn-by-turn routing to real-time traffic overlays, weather data, time zone lookups, and satellite tile rendering. It's a genuinely powerful platform. But the sheer breadth of services , the Search API, Route API, Render API, Geolocation service, and Time Zone service all live under the same roof, means there are a lot of moving pieces that can go wrong during initial setup and ongoing use.
The most common culprits I see fall into a few clear buckets:
- Authentication misconfiguration. Azure Maps supports both subscription key auth and Azure Active Directory (Azure AD) token-based auth. Mixing them up, using an expired key, or forgetting to scope the key to the right geography trips up most first-timers.
- Pricing tier mismatches. Certain Azure Maps services, especially batch processing routes or matrix travel-time calculations, are only available on specific pricing tiers (S0 vs S1 vs Gen2). You'll hit a 403 with no helpful explanation if your tier doesn't include the feature you're calling.
- Using the deprecated Render v1 API. Microsoft officially deprecated Azure Maps Render v1 and it retires on September 17, 2026. Apps still calling the old endpoint will start breaking before then during staged deprecation rollouts.
- Web SDK not rendering due to WebGL issues. The Azure Maps Web SDK uses WebGL for high-performance map rendering. If the browser doesn't support WebGL, or a corporate proxy is blocking the tile CDN, the map silently fails to draw.
- CORS errors on REST API calls. Calling Azure Maps REST endpoints directly from frontend JavaScript without configuring allowed origins or using the services module correctly causes cross-origin request blocks that look deceptively like network failures.
Microsoft's error messages in this space are notoriously unhelpful, a raw 401 doesn't tell you whether your key is wrong, your account is suspended, or your IP is blocked. That's exactly why I'm writing this guide. I want to walk you through every layer, from account setup all the way to enterprise-level Group Policy issues, so you can actually get your Azure Maps application running.
The Quick Fix, Try This First
Before you go down any rabbit holes, run through this 60-second checklist. In my experience, at least 40% of Azure Maps issues are resolved right here.
1. Confirm your subscription key is active and correctly copied. Go to the Azure portal, open your Azure Maps account resource, and click Authentication in the left-hand menu under Settings. You'll see Primary Key and Secondary Key. Copy the Primary Key fresh, don't rely on a key that's been sitting in a config file for months. Keys can be regenerated, which silently invalidates the old one.
2. Check the Azure Maps account status. In the Azure portal, navigate to your Maps account and look at the Overview blade. Make sure the Status shows Active, not Suspended or Disabled. A suspended Maps account returns 401 on every call, and the error body gives you nothing useful.
3. Verify you're calling the right API version. If you're using the Render service specifically, make sure you are NOT calling the v1 endpoint (/map/tile/v1/). The Render v1 API is deprecated as of now and rolling toward full retirement on 9/17/2026. Switch to the latest Render v2 endpoint format immediately.
4. Open your browser's developer console (F12) and check the Network tab. Filter by "maps.azure.com" and look at the actual HTTP status codes coming back. A 401 means auth. A 403 means tier/permission. A 404 typically means a wrong endpoint URL or API version. Don't guess, read the raw response.
5. Test with a direct REST call. Open a new browser tab and paste this URL, replacing YOUR_KEY with your actual subscription key:
https://atlas.microsoft.com/search/address/json?api-version=1.0&subscription-key=YOUR_KEY&query=SeattleIf you get a JSON response with location results, your account and key are fine and the problem is in your application code or SDK setup. If you get a 401 or 403, the problem is with your Azure Maps account configuration.
This sounds obvious, but I've seen misconfigured accounts cause hours of debugging. Here's how to do it right the first time.
Sign into the Azure portal at portal.azure.com. In the search bar at the top, type Azure Maps Accounts and select it from the results. Click + Create. On the creation blade, pay close attention to:
- Subscription: Make sure you're deploying into the correct subscription, this affects billing and IAM permissions.
- Resource Group: Use a dedicated resource group for your location-based services so you can manage them independently.
- Name: This becomes part of your resource identifier. Choose something descriptive and permanent, renaming requires recreation.
- Pricing Tier: Select Gen2 for new accounts. Gen2 includes all services (Search, Route, Render v2, Weather, Time Zone, Geolocation) under a single pay-as-you-go model. The old S0 and S1 tiers had feature caps and are being phased out.
After creation, go to your new Maps account → Settings → Authentication. Here you'll find your subscription keys. You'll also see the option to configure Azure Active Directory authentication, if you're building an enterprise app, you should use AAD token auth rather than subscription keys, because subscription keys give full account access to anyone who holds them.
To verify setup worked: navigate to Monitoring → Metrics in your Maps account. After you make your first API call, you should see a data point appear under API Total Requests. If that metric never populates, your calls are hitting the wrong endpoint or the wrong account entirely.
Authentication is the single biggest source of Azure Maps errors. Let me break down what each HTTP error actually means so you stop guessing.
HTTP 401, Unauthorized. Your subscription key is missing, invalid, or the key has been regenerated and you're using the old one. Go back to the Azure portal, grab a fresh key, and try again. Also check that you're passing the key correctly, it must go as a query parameter named subscription-key or as the header Ocp-Apim-Subscription-Key.
# Correct query parameter format:
GET https://atlas.microsoft.com/search/address/json
?api-version=1.0
&subscription-key=<your_key>
&query=1 Microsoft Way, Redmond WA
# Correct header format (preferred for server-side calls):
GET https://atlas.microsoft.com/search/address/json?api-version=1.0&query=Seattle
Ocp-Apim-Subscription-Key: <your_key>HTTP 403, Forbidden. Your key is valid but the operation you're trying to perform isn't allowed. This usually means one of three things: your pricing tier doesn't include the feature (for example, batch geocoding isn't available on all tiers), your AAD service principal doesn't have the Azure Maps Data Reader or Azure Maps Data Contributor role assigned, or you're calling a region-specific endpoint your account isn't provisioned for.
To check AAD role assignments: Azure portal → your Maps account → Access Control (IAM) → Role Assignments. Your app's service principal or managed identity should appear here with either Azure Maps Data Reader (read-only) or Azure Maps Data Contributor (read/write including geofencing data uploads).
Once you fix the auth error, your next API call should return a 200 with a JSON body. That's your confirmation that authentication is properly resolved.
You've got a valid key, your REST API calls work fine, but the actual map control renders as a blank or gray box in the browser. Here's what's going wrong and how to fix it.
Check WebGL support first. The Azure Maps Web SDK uses WebGL for rendering large geospatial datasets efficiently. Not every browser configuration supports it. Open your browser console and run:
const canvas = document.createElement('canvas');
const gl = canvas.getContext('webgl') || canvas.getContext('experimental-webgl');
console.log(gl ? 'WebGL supported' : 'WebGL NOT supported');If WebGL is not supported, your map will not render. This happens most often on headless CI environments, virtual machines with software rendering, and some corporate desktops with locked-down GPU drivers. The Azure Maps supported browsers list (documented under Web SDK in the official docs) requires a browser with WebGL 1.0 support at minimum.
Check that the CSS is loaded. The map control absolutely requires its CSS file. A very common mistake is loading the JavaScript but forgetting the stylesheet:
<link rel="stylesheet" href="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.css" type="text/css" />
<script src="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.js"></script>Without the CSS, the map container has no height and renders invisible even though the JavaScript loaded successfully.
Set an explicit height on the map container div. The map control won't render if its container has zero height. Always set a height explicitly in CSS:
#map-container {
width: 100%;
height: 600px; /* Must be explicit, 100% won't work unless parent has a defined height */
}After these fixes, a map tile should appear within 2-3 seconds of page load. If tiles load but show no roads or labels, that's a tile style configuration issue, check your style parameter in the map initialization options.
This one is urgent if you have any existing Azure Maps applications. Microsoft has officially deprecated the Render v1 service and it will be fully retired on September 17, 2026. If your application is still calling Render v1 endpoints, you need to migrate now, not a week before the deadline.
Here's how to identify if you're using Render v1. Search your codebase for these patterns:
# Render v1 endpoint patterns (DEPRECATED, must migrate):
https://atlas.microsoft.com/map/tile/v1/
https://atlas.microsoft.com/map/static/png?api-version=1.0
# Also check for:
atlas.microsoft.com/map/imagery/pngThe new Render v2 API uses a different endpoint structure and TilesetID system. The updated Get Map Tile API supports both raster and vector tile formats, 256x256 and 512x512 pixel sizes, and a much broader range of map types including road, weather, contour, and satellite imagery tiles.
# Render v2 endpoint pattern (current, use this):
GET https://atlas.microsoft.com/map/tile?api-version=2.1
&tilesetId=microsoft.base
&zoom={z}
&x={x}
&y={y}
&subscription-key=YOUR_KEYWhen you switch to Render v2, you must also display the correct copyright attribution on your map anytime you use Azure Maps tiles, either as a basemap or as layers in any third-party map control. Use the Get Map Attribution API to retrieve the required attribution text dynamically. Hardcoding attribution strings is not compliant because they change as map data is updated.
After migrating, monitor your Azure Maps usage metrics in the portal for a week to confirm no Render v1 calls are still appearing. The Metrics blade under your Maps account will break down API calls by endpoint type.
The Azure Maps Search service and Route service are the two most heavily used APIs, and they have their own distinct failure modes beyond authentication.
Search Service: "No results found" for valid addresses. The Azure Maps Search service covers global addresses, points of interest, business listings, and reverse geocoding. If you're getting empty results for addresses that definitely exist, first check the countrySet parameter. If you've hardcoded a country code filter that doesn't match your query address, you'll get zero results silently:
# Wrong, countrySet excludes the address you're searching:
GET /search/address/json?query=10 Downing Street&countrySet=US
# Right, match countrySet to your actual data:
GET /search/address/json?query=10 Downing Street&countrySet=GBRoute Service: ETAs returning unexpected results. The Route service calculates ETAs using real-time traffic, historic traffic patterns, and road speed data. If your ETAs look wrong, check your departAt parameter. If you're not passing a departure time, the route defaults to an average, you may be getting weekend night traffic patterns for a Monday morning route. Always pass an explicit ISO 8601 departure timestamp in production.
Route Service: 400 errors on truck or hazmat routing. Commercial vehicle routing and hazardous material routing require specific parameters, vehicleWidth, vehicleHeight, vehicleLoadType, etc. Missing required commercial vehicle parameters returns a 400 with a message like "One or more required parameters are missing". Check the Route service reference docs for the exact required fields for your travel mode.
Batch routing returning 202 but never completing. Batch route requests are asynchronous. You POST the batch, get a 202 Accepted with a Location header pointing to a status URL, then poll that URL. If you're not polling correctly, you'll never get your results. Poll every 5-10 seconds with a GET request to the Location URL until you receive a 200 response with the batch results.
Advanced Troubleshooting
If the step-by-step fixes above didn't resolve your issue, you're likely dealing with a more complex environment, enterprise networks, domain-joined machines, or Azure subscription-level policy constraints. Here's how to go deeper.
Azure Policy and Resource Locks
In enterprise Azure environments, Azure Policy definitions can prevent certain Azure Maps operations. For example, a policy denying creation of resources without specific tags will silently block Azure Maps account creation even if you have Contributor access. Go to your subscription → Policies → Compliance and look for any non-compliant policies that include Microsoft.Maps in scope. If you see policy violations, talk to your Azure administrator before trying to work around them.
Managed Identity Authentication for Production Apps
Subscription keys in production are a security liability, anyone who gets your key gets full access to your Maps account and its billing. For any Azure-hosted application (App Service, Azure Functions, AKS), switch to Managed Identity auth. Enable the system-assigned managed identity on your compute resource, then grant it the Azure Maps Data Reader role on your Maps account. Your application then requests tokens from the Azure Instance Metadata Service at 169.254.169.254, no credentials in code, no key rotation, no secret sprawl.
CORS Errors on Direct REST Calls from the Browser
If you're calling Azure Maps REST APIs directly from browser-side JavaScript (not through the Web SDK), you will hit CORS errors because the Azure Maps REST endpoints don't allow arbitrary browser origins. The correct pattern is to use the Azure Maps services module within the Web SDK, which handles CORS internally, or to proxy REST calls through your backend. Never expose your subscription key in frontend JavaScript, use the Web SDK's token authentication callback pattern with short-lived AAD tokens instead.
Azure Maps in Microsoft Fabric (Preview)
If you're working within Microsoft Fabric's Real-Time Intelligence workspace and trying to use the Maps preview feature, note that this is a separate surface from the standard Azure Maps REST APIs. The Fabric Maps integration is powered by Azure Maps services but surfaced through the Fabric UI for geospatial visualization of IoT data, asset tracking, and regional trend analysis. Configuration issues in Fabric Maps are usually workspace permission problems, not Azure Maps account problems, check your Fabric workspace admin settings first before chasing Azure Maps auth errors.
Network-Level Diagnostics
Corporate proxies and firewall rules frequently block the Azure Maps tile CDN hostnames. Run a quick connectivity test from your server or client machine:
# Test DNS resolution and connectivity to Azure Maps:
curl -v "https://atlas.microsoft.com/search/address/json?api-version=1.0&subscription-key=TEST&query=Seattle"
# Check if atlas.microsoft.com resolves:
nslookup atlas.microsoft.com
# On Windows, check if port 443 is reachable:
Test-NetConnection -ComputerName atlas.microsoft.com -Port 443If atlas.microsoft.com doesn't resolve or port 443 is blocked, you need your network team to whitelist the Azure Maps hostname ranges. File a firewall exception request with your IT team and reference the Azure IP ranges document in the Azure documentation for the specific IP ranges associated with Azure Maps in your target region.
If you've confirmed your account is active, your keys are valid, you're using current API versions, your network is clear, and you're still getting consistent failures, it's time to escalate. Azure Maps service outages are tracked on the Azure Status page (status.azure.com), so check there first. If there's no active incident and your issue persists, open a support ticket with your Maps account resource ID, the exact API endpoint you're calling, the full request including headers (minus the key), and the full response body. Without these specifics, support will just send you back to the documentation. Contact Microsoft Support with all of this detail pre-assembled to get a faster resolution.
Prevention & Best Practices
Getting Azure Maps working is one thing. Keeping it working, especially as your application scales, your team grows, and Microsoft updates its APIs, requires some intentional practices baked in from the start.
Monitor your API usage metrics proactively. Azure Maps exposes an API Total Requests metric in Azure Monitor. Set up an alert rule so you get notified if your request volume drops to zero (indicating a broken integration) or spikes unexpectedly (indicating a misuse or cost runaway). Go to your Maps account → Monitoring → Alerts → + New Alert Rule to configure this in about five minutes.
Pin your API versions in all API calls. Always include an explicit api-version parameter. Never rely on the default version behavior. Microsoft may update the default over time in ways that break your integration without any warning. Pinned versions mean your code only changes when you choose to update it.
Use the Azure Maps Web SDK version that matches your test environment. Referencing the latest SDK version from the CDN means your app automatically gets new features, but also automatically gets breaking changes. For production, pin to a specific SDK version number in your script tags and test before upgrading.
Build key rotation into your deployment pipeline. Azure Maps subscription keys should be rotated regularly. Store them in Azure Key Vault and reference them via Key Vault references in your App Service configuration, that way rotating a key is a single Key Vault update with zero code changes and zero redeployments.
Use the services module for server-side operations. The Azure Maps services module for the Web SDK handles authentication, request signing, and response parsing correctly. Building raw fetch calls against the REST API in the browser is error-prone and exposes your credentials. The services module also abstracts over the differences between subscription key auth and AAD token auth, making it easier to switch auth methods later.
- Immediately migrate any Render v1 API calls to Render v2, the retirement deadline is September 17, 2026, and migrating now prevents emergency work later
- Store your Azure Maps subscription key in Azure Key Vault, not in environment variables or config files committed to source control
- Set up an Azure Monitor alert on your Maps account for zero-request anomalies so silent integration breaks get caught immediately
- Switch production apps to Managed Identity or AAD token auth, subscription keys in production are a credential leak waiting to happen
Frequently Asked Questions
What exactly is Azure Maps and what does it actually do?
Azure Maps is Microsoft's platform of geospatial REST APIs and SDKs that you embed into web and mobile applications to add location intelligence. In practical terms, it gives you a map you can render in a browser, a geocoding service to convert addresses to coordinates (and back), a routing engine that calculates optimal paths accounting for real-time traffic and truck restrictions, a search service for finding businesses and points of interest, weather data, time zone lookups, and geofencing capabilities hosted in Azure. You access these through REST APIs, the Web SDK for JavaScript/TypeScript applications, or through Microsoft Fabric's Real-Time Intelligence workspace for data visualization scenarios.
How do I watch the official Azure Maps introduction video?
Microsoft published an in-depth video introduction to Azure Maps through the Internet of Things Show series, available on the Microsoft Learn video platform. The video walks through the core services, architecture, and practical use cases. You can find it at the Microsoft Learn Azure Maps documentation hub under the "Get Started" section, the video is titled "Introduction to Azure Maps" in the IoT Show series. It's about 20 minutes and gives you a solid mental model of how the pieces fit together before you start coding.
Is Azure Maps free? How much does it cost?
Azure Maps is not free for production use, but Microsoft offers a free Azure Maps account tier that lets you sign up and start developing with a meaningful monthly transaction allowance, good enough for building and testing an application. For production, Azure Maps Gen2 pricing is transaction-based: you pay per 1,000 API calls, and the rate varies by service (Search, Route, Render, Weather, etc.). There is no flat monthly fee on Gen2, you only pay for what you call. For high-volume applications, review the pricing calculator on the Azure portal to estimate costs, and set up Azure Cost Management alerts on your subscription to catch unexpected spikes before they hit your bill.
My Azure Maps geocoding search returns wrong results or nothing, what's wrong?
The most common cause is a restrictive countrySet parameter that filters out your intended result, double-check that the two-letter country code you're passing actually matches the country of the address you're searching. Beyond that, try the Geocode Autocomplete (preview) endpoint which is better at handling partial or ambiguous input because it suggests completions as you type based on partial input and optional location context. If you're doing reverse geocoding (coordinates to address), verify your latitude and longitude are in the correct order, the Azure Maps REST API expects latitude first, then longitude, which is the opposite of some other mapping platforms and a very easy mistake to make.
How do I get real-time traffic data in Azure Maps?
Azure Maps provides two distinct traffic feeds: a traffic flow view showing current vehicle speeds compared to free-flow speeds, and a traffic incidents view showing accidents, road closures, and hazards. In the Web SDK, you add traffic to your map by enabling the traffic layer in your map initialization options using map.setTraffic({ incidents: true, flow: 'relative' }). For the REST API, the Traffic service endpoints let you request flow segment data or incident details for specific geographic areas. Route service calls automatically factor in real-time traffic when you include the traffic=true parameter and a valid departAt timestamp, this is what drives the ETA calculations the routing engine returns.
How do I convert a Windows time zone ID to an IANA time zone in Azure Maps?
This is one of Azure Maps' genuinely useful but underused features. The Azure Maps Time Zone service can convert Microsoft Windows time-zone IDs (like "Pacific Standard Time") to their IANA equivalents (like "America/Los_Angeles") through its time zone ID conversion endpoint. You can also go the other direction. The service additionally returns the current UTC offset for any time zone, gives you current local time for a chosen time zone, and provides full historical and future time zone information accounting for daylight saving transitions, all via a simple REST call using either coordinates or an IANA ID as input. This saves you from maintaining your own time zone mapping tables in application code.