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. |