atlas module

Package:

azure-maps-control

Classes

EventManager	A manager for the map control's events. Exposed through the events property of the atlas.Map class. Cannot be instantiated by the user.
HtmlMarker	This class wraps an HTML element that can be displayed on the map.
Map	The control for a visual and interactive web map.
Pixel	Represent a pixel coordinate or offset. Extends an array of [x, y].
Popup	An information window anchored at a specified position on a map.
PopupTemplate	A layout template for a popup.
Shape	A helper class that wraps a Geometry or Feature and makes it easy to update and maintain.

Interfaces

AggregateExpression	An aggregate expression defines a calculation that is processed over a set of data. Schema: [operator: string, initialValue?: boolean | number, mapExpression: Expression] operator: An expression function that is then applied to against all values calculated by the mapExpression for each point in the cluster. Supported operators: o For numbers: +, *, max, min o For Booleans: all, any initialValue: Optional, an initial value in which the first calculated value is aggregated against. mapExpression: An expression that is applied against each point in the data set.
AnimationOptions	The options for animating changes to the map control's camera.
AuthenticationManager	A manager for the map control's authentication. Exposed through the authentication property of the atlas.Map class. Cannot be instantiated by the user.
AuthenticationOptions	Options for specifying how the map control should authenticate with the Azure Maps services.
BubbleLayerOptions	Options used when rendering Point objects in a BubbleLayer.
CameraBoundsOptions	The options for setting the bounds of the map control's camera.
CameraOptions	The options for setting the map control's camera.
ClusteredProperties	The properties which will exist for ClusteredProperties
CompassControlOptions	The options for a CompassControl object.
Control	An interface for defining a control of the map.
ControlManager	A manager for the map control's controls. Exposed through the controls property of the atlas.Map class. Cannot be instantiated by the user.
ControlOptions	The options for adding a control to the map.
DataSourceOptions	A data source for managing shape data that will be displayed on the map. A data source must be added to a layer before it is visible on the map. Options for a DataSourceOptions.
ElevationTileSourceOptions
FullscreenControlOptions	The options for a FullscreenControl object.
HeatMapLayerOptions	Options used when rendering Point objects in a HeatMapLayer.
HtmlMarkerEvents
HtmlMarkerManager	A manager for the map control's HTML markers. Exposed through the markers property of the atlas.Map class. Cannot be instantiated by the user.
HtmlMarkerOptions	Options for rendering an HtmlMarker object
HyperLinkFormatOptions	Format option for hyperlink strings.
IconOptions	Options used to customize the icons in a SymbolLayer
ImageLayerOptions	Options used when rendering Point objects in a ImageLayer.
ImageSpriteManager	A manager for the map control's image sprite. Exposed through the imageSprite property of the atlas.Map class. Cannot be instantiated by the user.
LayerManager	A manager for the map control's layers. Exposed through the layers property of the atlas.Map class. Cannot be instantiated by the user.
LayerOptions	A base class which all other layer options inherit from.
LightOptions	The options for the map's lighting.
LineLayerOptions	Options used when rendering SimpleLine, SimplePolygon, CirclePolygon, LineString, MultiLineString, Polygon, and MultiPolygon objects in a line layer.
MapConfiguration	Represents the contents of map configuration holding a list of styles available to them.
MapConfigurationStyle	Represents the info for a single style.
MapDataEvent	Event object returned by the maps when a data event occurs.
MapErrorEvent	Event object returned by the maps when an error event occurs.
MapEvent	Event object returned by the maps when a basic event occurs.
MapMouseEvent	Event object returned by the maps when a mouse event occurs.
MapMouseWheelEvent	Event object returned by the maps when a wheel event occurs.
MapTouchEvent	Event object returned by the maps when a touch event occurs.
MediaLayerOptions	Options used when rendering canvas, image, raster tile, and video layers
Options
Padding	Represent the amount of padding in pixels to add to the side of a BoundingBox when setting the camera of a map.
PitchControlOptions	The options for a PitchControl object.
PolygonExtrusionLayerOptions	Options used when rendering Polygon and MultiPolygon objects in a PolygonExtrusionLayer.
PolygonLayerOptions	Options used when rendering Polygon and MultiPolygon objects in a PolygonLayer.
PopupEvents
PopupManager	A manager for the map control's popups. Exposed through the popups property of the atlas.Map class. Cannot be instantiated by the user.
PopupOptions	The options for a popup.
Properties	A set of properties that can be used with a PopupTemplate
PropertyInfo	Species details of how a property is to be displayed.
RasterTileSourceOptions
RequestParameters	This is the object type expected to be returned by the transformRequest callback.
ScaleControlOptions	The options for a ScaleControl object.
ServiceOptions	Global properties used in all atlas service requests.
ShapeEvents
SourceManager	A manager for the map control's sources. Exposed through the sources property of the atlas.Map class. Cannot be instantiated by the user.
StyleChangedEvent	Event object returned by the map after loading a new style.
StyleControlOptions	The options for a StyleControl object.
StyleOptions	The options for the map's style.
SymbolLayerOptions	Options used when rendering geometries in a SymbolLayer.
TargetedEvent
TextOptions	Options used to customize the text in a SymbolLayer
Tile	Tile object returned by the map when a source data event occurs.
TileId
TileLayerOptions	Options used when rendering raster tiled images in a TileLayer.
TrafficControlOptions
TrafficOptions	The options for setting traffic on the map.
UserInteractionOptions	The options for enabling/disabling user interaction with the map.
VectorTileSourceOptions	A data source for managing shape data that will be displayed on the map. A data source must be added to a layer before it is visible on the map. Options for a VectorTileSource.
WebGLLayerOptions	Options used to render graphics in a WebGLLayer.
WebGLRenderer	Interface for rendering WebGL graphics in a WebGLLayer.
ZoomControlOptions	The options for a ZoomControl object.

Type Aliases

Expression	Can be specified as the value of filter or certain layer options. An expression defines a formula for computing the value of the property. Expressions are represented as JSON arrays. The first element of an expression is a string naming the expression operator.
getAuthTokenCallback	The callback function used to acquire an authentication token in anonymous authentication mode. Resolve with the authentication token or reject with any errors.
ResourceType
StyleImageMetadata	Signature for the options parameter passed to ImageSpriteManager.add.

Enums

AuthenticationType	An enumeration used to specify the type of authentication mechanism to use.
ControlPosition	Positions where the control can be placed on the map.
ControlStyle	Available styles for a Control.

Functions

addImageTemplate(string, string, boolean)	Adds an image template to the atlas namespace.
addProtocol(string, (args: any[]) => Promise<any>)	Adds a custom load resource function that will be called when using a URL that starts with a custom url schema.
clearPrewarmedResources()	Clears up resources that have previously been created by atlas.prewarm(). Note that this is typically not necessary. You should only call this function if you expect the user of your app to not return to a Map view at any point in your application.
getAllImageTemplateNames()	Retrieves an array of names for all image templates that are available in the atlas namespace.
getAuthenticationOptions()	Gets the default authentication options that were provided. If not previously set all properties will be undefined.
getDomain()	Gets the default domain that was provided. If not previously set the default value is "atlas.microsoft.com".
getImageTemplate(string, number)	Retrieves an SVG template by name.
getLanguage()	Gets the default language that was provided. If not previously set the default value is "NGT".
getMaxParallelImageRequests()	Gets the Maximum number of images (raster tiles, sprites, icons) to load in parallel
getSessionId()	Gets the default session id that was provided. If not previously set the default value is a random UUID.
getSubscriptionKey()	Gets the default Azure Maps subscription key that was provided.
getUserRegion()
getVersion()	Current API version number based on build number.
getView()	Gets the default view setting of the map control. If not previously set the default value is undefined.
getWorkerCount()	Gets the worker count that will get created.
isSupported(boolean)	Checks to see if the user's browser is supported by the map control.
prewarm()	Initializes resources like WebWorkers that can be shared across maps to lower load times in some situations. atlas.setWorkerCount, if being used, must be set before prewarm() is called to have an effect. By default, the lifecycle of these resources is managed automatically, and they are lazily initialized when a Map is first created. By invoking prewarm(), these resources will be created ahead of time, and will not be cleared when the last Map is removed from the page. This allows them to be re-used by new Map instances that are created later. They can be manually cleared by calling atlas.clearPrewarmedResources(). This is only necessary if your web page remains active but stops using maps altogether. This is primarily useful when using GL-JS maps in a single page app, wherein a user would navigate between various views that can cause Map instances to constantly be created and destroyed.
removeProtocol(string)	Removes a previously added protocol in the main thread.
setAuthenticationOptions(AuthenticationOptions)	Sets your authentication options as the default options in the atlas namespace which is used by the map control and any modules that make requests to the Azure maps services. If a Map is initialized with the authentication options explicitly defined and setAuthenticationOptions hasn't previously been called it will automatically be called by the Map constructor.
setDomain(string)	Sets the default domain used by the map and service modules unless the domain is explicitly specified when using those parts of the API. If a Map is initialized with the domain explicitly defined and setDomain hasn't previously been called it will automatically be called by the Map constructor. If the protocol is not specified https is assumed.
setLanguage(string)	Sets the default language used by the map and service modules unless the language is explicitly specified when using those parts of the API. If a Map is initialized with the language explicitly defined and setLanguage hasn't previously been called it will automatically be called by the Map constructor.
setMaxParallelImageRequests(number)	Sets Maximum number of images (raster tiles, sprites, icons) to load in parallel, which affects performance in raster-heavy maps. 16 by default.
setSessionId(string)	Sets the default session id used by the map and service modules unless the session id is explicitly specified when using those parts of the API. If a Map is initialized with the session ID explicitly defined and setSessionId hasn't previously been called it will automatically be called by the Map constructor.
setSubscriptionKey(string)	Sets your Azure Maps subscription key as the default subscription key in the atlas namespace which is used by the map control and any modules that make requests to the Azure maps services. If a Map is initialized with the subscription key explicitly defined and setSubscriptionKey hasn't previously been called it will automatically be called by the Map constructor.
setUserRegion(string)
setView(string)	Specifies which set of geopolitically disputed borders and labels are displayed on the map. The View parameter (also referred to as “user region parameter”) is a 2-letter ISO-3166 Country Code that will show the correct maps for that country/region. Country/Regions that are not on the View list or if unspecified will default to the “Unified” View. Please see the supported [Views]{@link https://aka.ms/AzureMapsLocalizationViews }. It is your responsibility to determine the location of your users, and then set the View parameter correctly for that location. The View parameter in Azure Maps must be used in compliance with applicable laws, including those regarding mapping, of the country/region where maps, images and other data and third party content that You are authorized to access via Azure Maps is made available.
setWorkerCount(number)	Sets number of web workers instantiated on a page. By default, it is set to half the number of CPU cores (capped at 6).

Function Details

addImageTemplate(string, string, boolean)

Adds an image template to the atlas namespace.

function addImageTemplate(templateName: string, template: string, override: boolean)

Parameters

templateName

string

The name of the template.

template

string

The SVG template to add. Supports {color}, {secondaryColor}, {scale}, {text}.

override

boolean

Specifies if it should override existing templates if one with the same name already exists.

addProtocol(string, (args: any[]) => Promise<any>)

Adds a custom load resource function that will be called when using a URL that starts with a custom url schema.

function addProtocol(customProtocol: string, loadFn: (args: any[]) => Promise<any>)

Parameters

customProtocol

string

the protocol to hook, for example 'custom'

loadFn

(args: any[]) => Promise<any>

the function to use when trying to fetch a tile specified by the customProtocol

clearPrewarmedResources()

Clears up resources that have previously been created by atlas.prewarm(). Note that this is typically not necessary. You should only call this function if you expect the user of your app to not return to a Map view at any point in your application.

function clearPrewarmedResources()

getAllImageTemplateNames()

Retrieves an array of names for all image templates that are available in the atlas namespace.

function getAllImageTemplateNames(): string[]

Returns

string[]

getAuthenticationOptions()

Gets the default authentication options that were provided. If not previously set all properties will be undefined.

function getAuthenticationOptions(): AuthenticationOptions

Returns

AuthenticationOptions

getDomain()

Gets the default domain that was provided. If not previously set the default value is "atlas.microsoft.com".

function getDomain(): string

Returns

string

getImageTemplate(string, number)

Retrieves an SVG template by name.

function getImageTemplate(templateName: string, scale?: number): string

Parameters

templateName

string

The name of the template to retrieve.

scale

number

Specifies how much to scale the template. For best results, scale the icon to the maximum size you want to display it on the map, then use the symbol layers icon size option to scale down if needed. This will reduce blurriness due to scaling. Default: 1

Returns

string

getLanguage()

Gets the default language that was provided. If not previously set the default value is "NGT".

function getLanguage(): string

Returns

string

getMaxParallelImageRequests()

Gets the Maximum number of images (raster tiles, sprites, icons) to load in parallel

function getMaxParallelImageRequests(): number

Returns

number

getSessionId()

Gets the default session id that was provided. If not previously set the default value is a random UUID.

function getSessionId(): string

Returns

string

getSubscriptionKey()

Gets the default Azure Maps subscription key that was provided.

function getSubscriptionKey(): string

Returns

string

getUserRegion()

Warning

This API is now deprecated.

use atlas.getView() instead

function getUserRegion(): string

Returns

string

getVersion()

Current API version number based on build number.

function getVersion(): string

Returns

string

getView()

Gets the default view setting of the map control. If not previously set the default value is undefined.

function getView(): string

Returns

string

getWorkerCount()

Gets the worker count that will get created.

function getWorkerCount(): number

Returns

number

isSupported(boolean)

Checks to see if the user's browser is supported by the map control.

function isSupported(failIfMajorPerformanceCaveat?: boolean): boolean

Parameters

failIfMajorPerformanceCaveat

boolean

If true the function will return false if the performance of the map control would be dramatically worse than expected (e.g. a software WebGL renderer would be used).

Returns

boolean

prewarm()

Initializes resources like WebWorkers that can be shared across maps to lower load times in some situations. atlas.setWorkerCount, if being used, must be set before prewarm() is called to have an effect. By default, the lifecycle of these resources is managed automatically, and they are lazily initialized when a Map is first created. By invoking prewarm(), these resources will be created ahead of time, and will not be cleared when the last Map is removed from the page. This allows them to be re-used by new Map instances that are created later. They can be manually cleared by calling atlas.clearPrewarmedResources(). This is only necessary if your web page remains active but stops using maps altogether.

This is primarily useful when using GL-JS maps in a single page app, wherein a user would navigate between various views that can cause Map instances to constantly be created and destroyed.

function prewarm()

removeProtocol(string)

Removes a previously added protocol in the main thread.

function removeProtocol(customProtocol: string)

Parameters

customProtocol

string

the custom protocol to remove registration for

setAuthenticationOptions(AuthenticationOptions)

Sets your authentication options as the default options in the atlas namespace which is used by the map control and any modules that make requests to the Azure maps services. If a Map is initialized with the authentication options explicitly defined and setAuthenticationOptions hasn't previously been called it will automatically be called by the Map constructor.

function setAuthenticationOptions(options: AuthenticationOptions)

Parameters

options

AuthenticationOptions

The new default authentication options.

setDomain(string)

Sets the default domain used by the map and service modules unless the domain is explicitly specified when using those parts of the API. If a Map is initialized with the domain explicitly defined and setDomain hasn't previously been called it will automatically be called by the Map constructor. If the protocol is not specified https is assumed.

function setDomain(domain: string)

Parameters

domain

string

The new default domain.

setLanguage(string)

Sets the default language used by the map and service modules unless the language is explicitly specified when using those parts of the API. If a Map is initialized with the language explicitly defined and setLanguage hasn't previously been called it will automatically be called by the Map constructor.

function setLanguage(language: string)

Parameters

language

string

The new default language.

setMaxParallelImageRequests(number)

Sets Maximum number of images (raster tiles, sprites, icons) to load in parallel, which affects performance in raster-heavy maps. 16 by default.

function setMaxParallelImageRequests(maxParallelImageRequests: number)

Parameters

maxParallelImageRequests

number

Maximum number of images to load in parallel.

setSessionId(string)

Sets the default session id used by the map and service modules unless the session id is explicitly specified when using those parts of the API. If a Map is initialized with the session ID explicitly defined and setSessionId hasn't previously been called it will automatically be called by the Map constructor.

function setSessionId(id: string)

Parameters

id

string

The new default session id.

setSubscriptionKey(string)

Sets your Azure Maps subscription key as the default subscription key in the atlas namespace which is used by the map control and any modules that make requests to the Azure maps services. If a Map is initialized with the subscription key explicitly defined and setSubscriptionKey hasn't previously been called it will automatically be called by the Map constructor.

function setSubscriptionKey(key: string)

Parameters

key

string

The new default subscription key.

setUserRegion(string)

Warning

This API is now deprecated.

use atlas.setView(view: string) instead.

function setUserRegion(userRegion: string)

Parameters

userRegion

string

setView(string)

Specifies which set of geopolitically disputed borders and labels are displayed on the map. The View parameter (also referred to as “user region parameter”) is a 2-letter ISO-3166 Country Code that will show the correct maps for that country/region. Country/Regions that are not on the View list or if unspecified will default to the “Unified” View. Please see the supported [Views]{@link https://aka.ms/AzureMapsLocalizationViews }. It is your responsibility to determine the location of your users, and then set the View parameter correctly for that location. The View parameter in Azure Maps must be used in compliance with applicable laws, including those regarding mapping, of the country/region where maps, images and other data and third party content that You are authorized to access via Azure Maps is made available.

function setView(view: string)

Parameters

view

string

The new default view

setWorkerCount(number)

Sets number of web workers instantiated on a page. By default, it is set to half the number of CPU cores (capped at 6).

function setWorkerCount(workerCount: number)

Parameters

workerCount

number

worker count.