{"id":47122,"library":"azure-maps-rest","title":"Azure Maps Services Module","description":"A client library for accessing Azure Maps REST services (geolocation, search, routing, traffic, weather, timezone, etc.). Current stable version: 2.1.1 (released 2023). Released quarterly with bug fixes and API updates. Supports both Node.js (>=18) and browser environments. Ships TypeScript definitions. Key differentiators: fully typed, works with Azure Maps Web Control, supports both subscription key and Azure AD authentication. v2.x is ESM-only; CJS not supported. Be aware of breaking changes from v1.x: major async patterns and auth changes.","status":"active","version":"2.1.1","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","azure","maps","rest","services","lbs","microsoft","typescript"],"install":[{"cmd":"npm install azure-maps-rest","lang":"bash","label":"npm"},{"cmd":"yarn add azure-maps-rest","lang":"bash","label":"yarn"},{"cmd":"pnpm add azure-maps-rest","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for Azure Active Directory (AAD) token authentication","package":"@azure/identity","optional":true},{"reason":"Peer dependency for HTTP pipeline","package":"@azure/core-http","optional":true}],"imports":[{"note":"ESM-only import; CommonJS require() fails in Node.js >=18. Works in bundlers with interop.","wrong":"const atlas = require('azure-maps-rest')","symbol":"Atlas","correct":"import * as atlas from 'azure-maps-rest'"},{"note":"DataSource is a named export, not default.","wrong":"import DataSource from 'azure-maps-rest'","symbol":"DataSource","correct":"import { DataSource } from 'azure-maps-rest'"},{"note":"Class is MapsSearch, not Search. Also note: constructor expects a credential object.","wrong":"import { Search } from 'azure-maps-rest'","symbol":"MapsSearch","correct":"import { MapsSearch } from 'azure-maps-rest'"}],"quickstart":{"code":"import * as atlas from 'azure-maps-rest';\nimport { DefaultAzureCredential } from '@azure/identity';\n\n// Option 1: Subscription key\nconst subscriptionKeyCredential = new atlas.SubscriptionKeyCredential(process.env.AZURE_MAPS_KEY ?? '');\nconst searchURL = new atlas.SearchURL(subscriptionKeyCredential);\n\n// Option 2: Azure AD token\n// const credential = new DefaultAzureCredential();\n// const pipeline = atlas.MapsURL.newPipeline(credential, { retryOptions: { maxTries: 3 } });\n// const searchURL = new atlas.SearchURL(pipeline);\n\nasync function main() {\n  const response = await searchURL.searchAddress('1 Microsoft Way, Redmond, WA', { limit: 5 });\n  console.log('Results:', response.results);\n}\nmain().catch(console.error);","lang":"typescript","description":"Demonstrates ESM import, subscription key and AAD auth options, and basic address search using MapsSearch."},"warnings":[{"fix":"Switch to ESM import syntax. Use bundler or Node.js >=18 with type: 'module' in package.json.","message":"v2.x drops CommonJS support. require('azure-maps-rest') throws error.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Use `new atlas.SubscriptionKeyCredential(key)` or import from '@azure/identity' for AAD tokens.","message":"v2.x changes how authentication tokens are passed. The old `new atlas.ServiceClient({ key })` no longer works.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Pass a credential (SubscriptionKeyCredential or Pipeline) to SearchURL constructor.","message":"v2.x removes the old `SearchURL` constructor that accepted a single key string. Must use credential object.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Check updated types: `response.results` directly (no `response.parsedBody` wrapper).","message":"Method `searchAddress` returns `SearchAddressResponse` but some fields like `summary`, `results` moved from v1 flatten","severity":"deprecated","affected_versions":">=2.0.0"},{"fix":"Use script tag CDN for quick browser test. For prod, bundle with webpack/rollup.","message":"Browser usage requires `atlas-service.min.js` script for UMD. The npm package is ESM-only and may need bundling.","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"search_vec":"'18':38 '2.1.1':24 '2023':26 'access':9 'ad':61 'api':33 'async':79 'auth':82 'authent':62 'awar':72 'azur':1,10,51,60,85 'break':74 'browser':40 'bug':30 'chang':75,83 'cjs':68 'client':6 'control':54 'current':21 'definit':44 'differenti':46 'environ':41 'esm':66 'esm-on':65 'etc':20 'fix':31 'fulli':47 'geoloc':14 'javascript':84 'key':45,58 'lbs':89 'librari':7 'major':78 'map':2,11,52,86 'microsoft':90 'modul':4 'node.js':37 'pattern':80 'quarter':28 'releas':25,27 'rest':12,87 'rout':16 'search':15 'servic':3,13,88 'ship':42 'stabl':22 'subscript':57 'support':35,55,70 'timezon':19 'traffic':17 'type':48 'typescript':43,91 'updat':34 'v1.x':77 'v2.x':63 'version':23 'weather':18 'web':53 'work':49","created_at":"2026-06-07T16:49:54.332947+00:00","updated_at":"2026-06-07T16:49:54.332947+00:00","problems":[{"fix":"Update Node.js to >=18 or ensure bundler resolves 'module' field. Add to webpack resolve.mainFields: ['module', 'main'].","cause":"Missing Node.js ESM support or bundler not configured for package.json 'exports'","error":"Module not found: Can't resolve 'azure-maps-rest'"},{"fix":"Use ESM import: `import { SubscriptionKeyCredential } from 'azure-maps-rest'`.","cause":"CommonJS require() returns module object, not the namespace; SubscriptionKeyCredential is not a constructor in that context","error":"TypeError: atlas.SubscriptionKeyCredential is not a constructor"},{"fix":"Ensure you have internet connectivity and are using the correct endpoint. For cross-cloud (gov, China), set baseUrl in pipeline options.","cause":"Network issue or incorrect URL endpoint (v1 used different hostname?)","error":"Error: getaddrinfo ENOTFOUND atlas.microsoft.com"},{"fix":"Check `response.error` before destructuring. Use try-catch and inspect full response.","cause":"API call failed (e.g., auth error) but error not handled; response object may have error property instead.","error":"TypeError: Cannot destructure property 'results' of 'response' as it is undefined"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":null,"github":null,"docs":null,"changelog":null,"pypi":null,"npm":"azure-maps-rest","openapi_spec":null,"status_page":null,"smithery":null,"categories":["maps"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-07","next_check":"2026-09-05","install_tag":null}}