Registry / maps / azure-maps-rest

azure-maps-rest

library2.1.1jsnpmunverified

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.

maps

npm install azure-maps-rest

package ↗

INSTALL

IMPORT

SIG · AZURE-MAPS-REST

azure-maps-rest

mapsjavascriptv2.1.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Atlas

✓ import * as atlas from 'azure-maps-rest'

✗ const atlas = require('azure-maps-rest')

ESM-only import; CommonJS require() fails in Node.js >=18. Works in bundlers with interop.

DataSource

✓ import { DataSource } from 'azure-maps-rest'

✗ import DataSource from 'azure-maps-rest'

DataSource is a named export, not default.

MapsSearch

✓ import { MapsSearch } from 'azure-maps-rest'

✗ import { Search } from 'azure-maps-rest'

Class is MapsSearch, not Search. Also note: constructor expects a credential object.

Demonstrates ESM import, subscription key and AAD auth options, and basic address search using MapsSearch.

import * as atlas from 'azure-maps-rest'; import { DefaultAzureCredential } from '@azure/identity'; // Option 1: Subscription key const subscriptionKeyCredential = new atlas.SubscriptionKeyCredential(process.env.AZURE_MAPS_KEY ?? ''); const searchURL = new atlas.SearchURL(subscriptionKeyCredential); // Option 2: Azure AD token // const credential = new DefaultAzureCredential(); // const pipeline = atlas.MapsURL.newPipeline(credential, { retryOptions: { maxTries: 3 } }); // const searchURL = new atlas.SearchURL(pipeline); async function main() { const response = await searchURL.searchAddress('1 Microsoft Way, Redmond, WA', { limit: 5 }); console.log('Results:', response.results); } main().catch(console.error);

Debug

Known issues

breakingv2.x drops CommonJS support. require('azure-maps-rest') throws error.

fix

Switch to ESM import syntax. Use bundler or Node.js >=18 with type: 'module' in package.json.

affects: >=2.0.0

breakingv2.x changes how authentication tokens are passed. The old `new atlas.ServiceClient({ key })` no longer works.

fix

Use `new atlas.SubscriptionKeyCredential(key)` or import from '@azure/identity' for AAD tokens.

affects: >=2.0.0

breakingv2.x removes the old `SearchURL` constructor that accepted a single key string. Must use credential object.

fix

Pass a credential (SubscriptionKeyCredential or Pipeline) to SearchURL constructor.

affects: >=2.0.0

deprecatedMethod `searchAddress` returns `SearchAddressResponse` but some fields like `summary`, `results` moved from v1 flatten

fix

Check updated types: `response.results` directly (no `response.parsedBody` wrapper).

affects: >=2.0.0

gotchaBrowser usage requires `atlas-service.min.js` script for UMD. The npm package is ESM-only and may need bundling.

fix

Use script tag CDN for quick browser test. For prod, bundle with webpack/rollup.

affects: >=2.0.0

Errors

Common errors & fixes

Module not found: Can't resolve 'azure-maps-rest'

Missing Node.js ESM support or bundler not configured for package.json 'exports'

fix

Update Node.js to >=18 or ensure bundler resolves 'module' field. Add to webpack resolve.mainFields: ['module', 'main'].

TypeError: atlas.SubscriptionKeyCredential is not a constructor

CommonJS require() returns module object, not the namespace; SubscriptionKeyCredential is not a constructor in that context

fix

Use ESM import: `import { SubscriptionKeyCredential } from 'azure-maps-rest'`.

Error: getaddrinfo ENOTFOUND atlas.microsoft.com

Network issue or incorrect URL endpoint (v1 used different hostname?)

fix

Ensure you have internet connectivity and are using the correct endpoint. For cross-cloud (gov, China), set baseUrl in pipeline options.

TypeError: Cannot destructure property 'results' of 'response' as it is undefined

API call failed (e.g., auth error) but error not handled; response object may have error property instead.

fix

Check `response.error` before destructuring. Use try-catch and inspect full response.

Upgrade

Version history

2.1.1latest on npm

Audit

Dependencies

@azure/identityoptionalRequired for Azure Active Directory (AAD) token authentication

@azure/core-httpoptionalPeer dependency for HTTP pipeline

Agent activity

47 hits · last 30 days

node

Resources

packageazure-maps-rest ↗