Map Class

Note

Bing Maps Web Control SDK retirement

Bing Maps Web Control SDK is deprecated and will be retired. Free (Basic) account customers can continue to use Bing Maps Web Control SDK until June 30th, 2025. Enterprise account customers can continue to use Bing Maps Web Control SDK until June 30th, 2028. To avoid service disruptions, all implementations using Bing Maps Web Control SDK will need to be updated to use Azure Maps Web SDK by the retirement date that applies to your Bing Maps for Enterprise account type. For detailed migration guidance, see Migrate from Bing Maps Web Control SDK and Migrate Bing Maps Enterprise applications to Azure Maps with GitHub Copilot.

Azure Maps is Microsoft's next-generation maps and geospatial services for developers. Azure Maps has many of the same features as Bing Maps for Enterprise, and more. To get started with Azure Maps, create a free Azure subscription and an Azure Maps account. For more information about azure Maps, see Azure Maps Documentation. For migration guidance, see Bing Maps Migration Overview.

The map object generates an interactive map within a specified DOM element. When loading the map you can reference the DOM element to render the map in by either referencing an element directly (i.e. document.getElementById), or by passing in a HTML ID selector (i.e. #myMap). This is normally a reference to an empty div.

You can customize the map by passing in number of different options. Some of these options can be specified when creating the map while others can be changed at any time. When loading the map, you can specify settings from the MapOptions and ViewOptions objects.

Constuctor

Map(containerElement: node or string, options?: MapOptions | ViewOptions)

Properties

Name Type Description
entities EntityCollection Use this property to add or remove individual shapes to the default layer in the map.
layers LayerCollection Use this property to add layers such as; data, tile, heat map and clustering layers to the map.

Static Methods

Method Return Type Description
getClosestPanorama(bounds: LocationRect, success: function(panoramaInfo: IPanoramaInfo), missingCoverage: function()) Gets the streetside panorama information closest to the specified bounding box and returns using a success callback function. This information can then be used to set the map view to that streetside panorama.
getVersion() string Returns the branch name; release or experimental.

Methods

Method Return Type Description
dispose() Deletes the Map object and releases any associated resources.
getBounds() LocationRect Returns the location rectangle that defines the boundaries of the current map view.
getCenter() Location Returns the location of the center of the current map view.
getCopyrights(callback: function(copyrights: string[])) Returns to the specified callback an array of strings representing the attributions of the imagery currently displayed on the map.
getCredentials(callback: function(sessionId:string)) Gets the session ID. This method takes in callback function and passes a session ID to it which can be used in place of a Bing Maps key when calling other Bing Maps services. For example:

map.getCredentials(function(sessionId)
{
//Use sessionId when calling REST services
});

getCulture() string Returns the users region setting.
getHeading() number Returns the heading of the current map view.
getHeight() number Returns the height of the map control.
getImageryId() string Returns a user friendly string that represents the imagery currently displayed on the map. For example; if the map is displaying aerial imagery, this function would return “Aerial”.
getMapTypeId() MapTypeId Returns a string that represents the current map type displayed on the map. Valid map types are listed in the MapTypeId Enumeration topic.
getMetersPerPixel() number Returns the current scale in meters per pixel of the center of the map.
getOptions() MapOptions Returns the map options that have been set. Note that if an option is not set, then the default value for that option is assumed and getOptions returns undefined for that option.
getPageX() number Returns the x coordinate of the top left corner of the map control, relative to the page.
getPageY() number Returns the y coordinate of the top left corner of the map control, relative to the page.
getPitch() number Returns the pitch of the current streetside map view.
getRootElement() HTMLElement Returns the map’s root node.
getUserRegion() string Returns the users region setting.
getWidth() number Returns the width of the map control.
getZoom() number Returns the zoom level of the current map view.
getZoomRange() Range Returns the range of valid zoom levels for the current map view.
isMercator() boolean Returns a boolean indicating whether the map is in a regular Mercator nadir mode.
isRotationEnabled() boolean Returns true if the current map type allows the heading to change; false if the display heading is fixed.
setMapType(mapTypeId: MapTypeId) Sets the current map type. Takes in MapTypeId enumeration.
setOptions(options: MapOptions) Sets map options that modify how the map control works.
setView(viewOptions: ViewOptions) Sets the map view based on the specified view options.
tryLocationToPixel(location: Location or Location[], reference?: PixelReference) null, Point, or Point[] Converts a specified Location to a Point on the map relative to the specified PixelReference. If reference is not specified, PixelReference.viewport is used. If the map is not able to convert the Location, null is returned.

Alternatively, it can also convert an array of Location objects and return an array of Points. If any of the conversions fail, null is returned.
tryPixelToLocation (point: Point or Point[], reference?: PixelReference) null, Location, or Location[] Converts a specified Point to a Location on the map relative to the specified PixelReference. If reference is not specified, PixelReference.viewport is used. If the map is not able to convert the Point, null is returned.

Alternatively, it can also convert an array of Point objects and return an array of Locations. If any of the conversions fail, null is returned.

Events

The following events are available on the map.

Name Arguments Description
click MouseEventArgs Occurs when the mouse is used to click the map or when a touch end event occurs over the map.
dblclick MouseEventArgs Occurs when the mouse is used to double click the map.
mapresize Occurs when the map has been resized. This will fire multiple times if dragging a window to resizie the map.
maptypechanged MapTypeEventArgs Occurs when the map type changes.
mousedown MouseEventArgs Occurs when the left mouse button is pressed or a touch start event occurs on the map.
mousemove MouseEventArgs Occurs when the mouse cursor moves or the touch move event occurs over the map.
mouseout MouseEventArgs Occurs when the mouse cursor moves out of the area covered by the map.
mouseover MouseEventArgs Occurs when the mouse cursor moves over of the area covered by the map.
mouseup MouseEventArgs Occurs when the left mouse button is lifted up or when the touch end event occurs over the map.
mousewheel MouseEventArgs Occurs when the mouse wheel is used when the mouse cursor is over the map.
rightclick MouseEventArgs Occurs when the right mouse button is used to click the map or when a long touch press occurs over the map.
viewchange Occurs for every frame of a map view change.
viewchangeend Occurs when the map view is done changing. This event occurs when a view is the same for one frame of a map view change. For example, if the mouse is used to drag the map to change the view, but pauses during the drag (without releasing the mouse button), viewchangeend occurs twice. You can use the addThrottledHandler method to customize the number of events that occur.
viewchangestart Occurs when the map view starts changing.