Professional Documents
Culture Documents
Bing Maps V7 To V8 Migration Guide
Bing Maps V7 To V8 Migration Guide
Guide
Bing Maps V7 to V8
Bing Maps V7 to V8 Migration Guide
Contents
1.0 Introduction ............................................................................................................................................ 4
1.1 Why Bing Maps v8?............................................................................................................................. 4
1.2 Suggested Migration Plan ................................................................................................................... 5
1.3 Technical Resources ............................................................................................................................ 5
2.0 What’s New in Bing Maps V8 .................................................................................................................. 6
2.1 Map Script URL.................................................................................................................................... 6
2.2 Asynchronous load the Map ............................................................................................................... 7
2.3 Release Branches ................................................................................................................................ 7
2.4 Localization ......................................................................................................................................... 8
2.5 Key New Features ............................................................................................................................... 8
3.0 Breaking Changes from Bing Maps V7 .................................................................................................. 12
3.1 Deprecated Modules......................................................................................................................... 12
3.2 Deprecated Classes ........................................................................................................................... 12
3.3 Deprecated Class Function, Properties or Events ............................................................................. 14
3.4 Breaking Class Function or Property Changes .................................................................................. 18
3.5 Custom HTML Pushpins .................................................................................................................... 18
3.6 EntityCollection deprecation ............................................................................................................ 20
3.7 Infobox Breaking Change .................................................................................................................. 21
3.8 Map Center Offset Workaround ....................................................................................................... 22
4. 0 Code Optimizations in V8 ..................................................................................................................... 23
4.1 Loading the Map ............................................................................................................................... 23
4.2 Adding an array of shapes to the map .............................................................................................. 23
4.3 Changing the Color of the Pushpins .................................................................................................. 24
4.4 Setting the Color of a Polygon or Polyline ........................................................................................ 25
4.5 Getting the Location of a Mouse Event ............................................................................................ 25
4.6 Adding Events to an Array of Shapes ................................................................................................ 26
4.7 Polygons with holes .......................................................................................................................... 26
4.8 Loading Multiple Modules ................................................................................................................ 28
4.9 Adding Tile Layers to the Map .......................................................................................................... 28
4.10 Bing Maps REST Services ................................................................................................................. 30
Bing Maps V7 to V8 Migration Guide
1.0 Introduction
This guide is designed to support you in your Bing Maps migration from version 7 to version 8. This
resource provides detailed comparisons between the JavaScript API of these two versions of Bing Maps
as well as comparative code samples, migration suggestions and best practices for migrating your code
to the newest version of Bing Maps. As you read this document you should gain an understanding of the
benefits of Bing Maps v8 and how to leverage it in your existing mapping applications.
The Bing Maps V8 control contains several new innovative features and functionalities and there is a
well laid out roadmap for bring new features to V8 on a regular basis.
When it comes to performance the v8 is miles ahead of v7. Version 8 is capable of rendering data much
faster than versions 7, and can also render a lot more data too. When dealing with small data sets on a
standard browser this might not be that noticeable but if you need to display a large data set or are
using a mobile browser this increased performance makes a big difference.
Version 7 supported 22 different culture codes (languages). Version 8 supports significantly more culture
codes and uses the Bing Maps REST services to perform geocode and route requests which has support
for 117 languages.
Over the years Bing Maps customers and developers have requested number of new features and
functionalities. Many of these are now available in v8. Some of the most notable one’s being;
Bing Maps V7 to V8 Migration Guide
1) Review existing application and identify where Bing Maps v7 code is being used.
2) As an option, before touching any code test your existing app against version 8 as it is by using
the steps outlined in Appendix A: Fiddler Redirect test
3) Identify which features of Bing Maps v7 are being used and review the migration information in
this document.
4) Migrate code to version v8 of Bing Maps and update script reference to point to the new v8 map
control URL.
5) Test your migrated application.
6) Deploy your application to your production environment.
Over 5 years of customer and developer feedback was used to understand the types of apps developers
were creating with Bing maps. From this knowledge several improvements were made in the V8 SDK
which better aligns with the type with these types of apps.
http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0
If you wanted to use the V7 map control on a secure HTTPS site not only did you have to use an HTTPS
domain for the URL, but you also had to add a query URL parameter.
https://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0&s=1
This URL has been a source of confusion for developers new to Bing Maps for the following reasons:
The name Virtual Earth is the legacy name that was used for the Bing Maps platform before it
was rebranded as Bing Maps in 2009. Developers who are new to Bing Maps are often unaware
of the name change.
The dev subdomain was meant to indicate that this URL was for the Bing Maps developer API.
However, to some this was interpreted as development environment which lead to developers
asking where the production environment is. Bing Maps lets developers build their apps against
the production service using a basic key during their development cycle.
Having to add the extra query parameter when using HTTPS has been a common step many
developers missed.
With the release of Bing Maps V8, this was the perfect time to update the map script URL to address
these issues.
http://www.bing.com/api/maps/mapcontrol
https://www.bing.com/api/maps/mapcontrol
Alternatively, if your app is hosted on a server, you can drop http:/https: from the URL and the browser
will automatically retrieve the correct version of the map control.
Bing Maps V7 to V8 Migration Guide
//www.bing.com/api/maps/mapcontrol
<script>
function GetMap() {
//Load the map.
}
</script>
Branch Description
release The main branch of the SDK that is used in most applications. New features have
been fully tested and known bugs found while in the experimental branch have been
fixed.
experimental New features are made available as soon as they have been developed. These
features are still being tested and may have bugs in them. This branch is
recommended for developers who want to try out the latest and greatest features as
soon as they are available.
frozen New features are added only after they have been in the release branch for a period
of time and all known bugs have been fixed. This branch is recommended for mission
critical apps that are willing to wait longer for new features in exchange for the extra
stability.
To point your application to a specific branch simply add “&branch=[branch_version]” to the map script
URL. If a branch is not specified, the release branch is automatically loaded. For example, the following
URL can be used to load the experimental branch.
<script type='text/javascript'
src='http//www.bing.com/api/maps/mapcontrol?callback=GetMap&branch=experimental' async
defer></script>
<script>
function GetMap() {
//Load the map.
}
</script>
Tip: Before releasing your application into production, ensure that the branch isn’t set to experimental
and test against the branch you plan to use.
Bing Maps V7 to V8 Migration Guide
2.4 Localization
Localization of maps is the process of rendering maps in a specific language other than the default. Both
v7 and v8 support localization. Version 7 required that you pass in a culture code to set the language of
the map, however version 8 automatically tries to detect the appropriate culture code for a user based
on their browser settings and location. This saves a lot of work in trying to manage the culture of the
map yourself. However, like v7 it is possible to specify a culture code, which will override the default
behavior. This is useful when testing, or if you only want the map to support a single language. If you do
wish limit the map to a single language, the following is an example of how this was done in v7 and how
it can be done in v8.
Before: v7
To get a localized map using v7, add an mkt parameter to the API script reference.
<script type="text/javascript"
src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0&mkt=[culture_code]"></
script>
After: v8
The Bing Maps v8 web control no longer requires the use of a mkt parameter to localize the map. If one
is not provided the map will automatically attempt to set the language of the map based on the user’s
browser settings and/or location.
Of the key features listed between V7 and V8, only one feature was deprecated, Venue Maps. See the
3.1 Deprecated Modules section of this document for more details.
Want to draw a pushpin, polygon or some other shape on the map? The drawing tools module lets you
do this easily. This is can be used in many different types of scenarios such as providing the user the
ability to draw a search area, or providing tools for managing sales territories.
Visualize large sets of pushpins, by having overlapping pushpins group together as clusters and break
apart as you zoom in automatically.
GeoJSON is one of the most common file format used for sharing and storing spatial data. With Bing
Maps v8 you can easily import and export GeoJSON data.
Some of the Bing Maps services compress arrays of locations using a compression algorithm. These tools
make it easy to encode and decode this data when using these services. Additional, this algorithm can
also be used with your own data if sending it between a client app and a server.
The Bing Spatial Data Services provides two key features; the ability to upload, host and expose location
data as a spatial REST service, and the ability to retrieve administrative boundaries data such as zip
codes, cities, states and more from Bing Maps. The Bing Maps v8 SDK exposes a set of useful tools for
accessing this data and integrating it with the map seamlessly.
When analyzing business data on a map it is often useful to be able to perform a spatial formula or two.
One of the most common being the ability to calculate the distance (as the crow flies) between two
locations.
When developing your app, you may find that you need some data to test parts of your application.
Version 8 includes a test data generator that can create random locations, pushpin, polylines, polygons
and colors.
The map labels in the Bing Maps v8 SDK are separate from the base map and sit above the data on the
map. This helps ensures that the labels can be clearly visible no matter what data is added to the map.
When pushpins overlap labels the labels can detect this and move out of the way. If it is a road label it
will move along the road. If it is a city name it may move up a bit. If there a lot of pushpins in an area the
label may be hidden entirely.
This is a standard way of representing spatial objects as a string and use supported by all OGC systems
and databases. Easily import and export spatial data with a spatial database and Bing Maps.
A list of features comparing Bing Maps V8 with other controls and services in the Bing Maps platform
can be found here.
Bing Maps V7 to V8 Migration Guide
Important Note: There may be some features that where in V7 which are not yet in V8. If a feature is
missing in V8 and does not appear in the lists it is highly likely that the feature in question is planned but
has been a lower priority and thus, not yet added. Check the experimental branch of V8 to see if the
feature may be in testing. If it is not there, check the forums or contact the support team if you would
like a status update on a feature.
BusinessDetails These were part of the Directions module and are no longer
BusinessDisambiguationSuggestion needed in V8.
Coordinate Part of the deprecated GeoLocationProvider class.
DirectionsStep Was part of the Directions module in v7, was rarely used and is
DirectionsStepEventArgs no longer needed in V8.
DirectionsStepRenderEventArgs
DirectionsStepWarning
Disambiguation
DisambiguationRenderEventArgs
EntityCollection This class is used to group shapes as a layer. However, it also
allowed adding child entity collections to an EntityColleciton.
This is very different from how all of the other Bing Maps SDK’s
have worked and not a common scenario. As such this class has
been deprecated in V8 and replaced with the new Layer class.
However, for backwards compatibility, a wrapper around the
Layer class called EntityCollection has been included in the V8
control to help minimize migration efforts. This wrapper flattens
all child entity collections of an EntityCollection into a single
layer. This may result in some rendering differences when
compared to V7. This EntityCollection class should only be used
if migrating an app from V7 that requires minimal code changes.
EntityState Part of the deprecated BingTheme module
GeoLocationProvider This class provided functionality to retrieve the user’s location.
When V7 was released, some browsers didn’t have any way to
retrieve the user’s location, while others exposed this
information in different ways. This class wrapped them into a
single, easy to use class. In recent years a standard geolocation
API is available in all browsers that support HTML5. It makes
more sense to use this API directly.
IconType Was part of the Directions module in v7, was rarely used and is
no longer needed in V8.
InfoboxType Part of the deprecated BingTheme module.
KeyEventArgs Key events not exposed in V8, use standard HTML key events.
LocationDisambiguationSuggestion Was part of the Directions module in v7, was rarely used and is
Maneuver no longer needed in V8.
MapMode Most of the functionality in this class is not needed in the Bing
Maps V8 SDK.
MapModeOptions These options are no longer needed in the Bing Maps V8 SDK.
Position Part of the deprecated GeoLocationProvider Class.
PositionCircleOptions
PositionError
PositionOptions
ResetDirectionsOptions Was part of the Directions module in v7, was rarely used and is
Route no longer needed in V8.
RouteLeg
RoutePath
RouteSelectorEventArgs
Bing Maps V7 to V8 Migration Guide
RouteSelectorRenderEventArgs
RouteSubLeg
RouteSummary
RouteSummaryRenderEventArgs
SearchRegion Part of the business search function. In V8, Bing Spatial Data
SearchRequestOptions Service data sources can be used instead.
SearchResponse
SearchResponseSummary
SearchResult
StepWarningStyle Was part of the Directions module in v7, was rarely used and is
no longer needed in V8.
TrafficLayer This class was deprecated in V7 many years ago and replaced
with the TrafficManager class which is also available in V8.
TransitLine Was part of the Directions module in v7, was rarely used and is
TransitOptions no longer needed in V8.
WaypointEventArgs
WaypointRenderEventArgs
waypointRemoved
DirectionsRenderOptions autoDisplayDisambiguation Rarely used.
disambiguationPushpinOptions
displayTrafficAvoidanceOption
DirectionsRenderOptions middleWaypointIcon waypointPushpinOptions property will
be used instead.
DirectionsRequestOptions transitOptions time & timeType properties now
exposed in DirectionsRequestOptions
directly since time property is also
supported for driving directions now.
Infobox getId Rarely used.
getTitleAction
getTitleClickHandler
Infobox Events click Rarely used in V7 apps and not needed
entitychanged in V8.
mouseenter
mouseleave
Infobox Options height Infobox in V8 grows to fit content.
width Plans to add maxWidth/maxHeight
options.
Infobox Options id Rarely used.
pushpin
titleAction
titleClickHandler
typeName
Map blur Rarely used.
focus
getImageryId
getModeLayer
getTargetBounds
getTargetCenter
getTargetHeading
getTargetMetersPerPixel
getTargetZoom
getUserLayer
getViewportX
getViewportY
isDownloadingTiles
Map Events imagerychanged Rarely used.
keydown
keypress
keyup
optionschanged
targetviewchanged
tiledownloadcomplete
Map Options customizeOverlays Rarely used.
disableKeyboardInput
Bing Maps V7 to V8 Migration Guide
disableMouseInput
disableTouchInput
disableUserInput
enableSearchLogo
fixedMapPosition
inertiaIntensity
theme
tileBuffer
useInertia
viewChangeEndDelay
Map Options height V8 automatically fills the area of its div
width or of its parent area.
Map Options enableHighDpi V8 now automatically detects screen
resolution and loads high DPI map
images when needed.
MapTypeId auto This map type would switch between
the different map types based on zoom
level automatically. This is being
deprecated as it has been pain point for
a lot of users.
MapTypeId collinsBart When the map culture was set to en-
GB, this map type could be used to
change the map style over London, UK
to a Collins Bartholomew map style.
Very few users use this map style.
Given its limited usage and coverage
area, this map style has been
deprecated.
MapTypeId mercator Most devs who used this wanted to
hide the base tile layer so they could
display their own tile layer. V8 will be
exposing the ability to create custom
map types which would be a much
more seamless way to achieve this.
MouseEventArgs handled Not needed in V8.
isPrimary
isSecondary
isTouchEvent
originalEvent
wheelDelta
Polygon toString Rarely used.
Polygon Events dblclick Rarely used.
entitychanged
Polygon Events rightclick In V8, add polygon to a Layer and add
right click event to the layer.
Polygon Options infobox Rarely used.
Polyline toString Rarely used.
Bing Maps V7 to V8 Migration Guide
getShortAddress
isExactLocation
Waypoint Events changed Rarely used and not needed in V8.
geocoded
reverseGeocoded
Waypoint Options businessDetails Rarely used and not needed in V8.
disambiguationContainer
exactLocation
shortAddress
When using a callback function with a TileSource object, the callback function used to return a
levelOfDetail property. This property has been renamed to zoom.
Infoboxes are no longer added to the map using map.entities.push, instead they have a setMap
function where you pass in the map instance you want to attach the infobox to.
The mkt URL parameter that is used in V7 to set the culture/language of the map is no longer
supported in V8. Instead V8 automatically detects the users culture/language settings from their
browser.
Many examples are provided in the documentation and in the interactive SDK for V8.
That said it is possible to render some HTML content on a Canvas by embedding the HTML inside of an
SVG using the foreignObject tag. However, there are a number of limitations to this approach;
Interactive content such as links, inputs, and iframes are not supported.
Some interactive content may render, however it’s interactive features will no longer work as
the HTML is now simply an image of the element and not the interactive element itself.
The XHTML namespace is also required in the HTML.
Bing Maps V7 to V8 Migration Guide
In terms of browser support the SVG foreignObject tag is fully supported in Edge and Firefox
and partially supported in Chrome. It is meant to be partially supported in IE11 however testing
shows otherwise.
Not all browsers that support the SVG foreignObject tag may render the HTML content the
same way.
Due to these limitations, in most applications it is likely best to use one of the many other ways of
creating custom pushpins in V8. However, if your application has a limited audience who use a specific
browser that does support the foreignObject tag, then this maybe an option.
The following code sample creates an SVG template string that contains the foreignObject tag and a DIV
with the XHTML namespace on it. It then inserts custom HTML into the template and passes it in as the
icon property of the pushpin.
<!DOCTYPE html>
<html>
<head>
<title></title>
<meta charset="utf-8" />
<script type='text/javascript'
src='http://www.bing.com/api/maps/mapcontrol?callback=GetMap'
async defer></script>
<script type='text/javascript'>
var map;
var svgTemplate = '<svg xmlns="http://www.w3.org/2000/svg" width="100"
height="25"><foreignObject width="100%" height="100%"><div
xmlns="http://www.w3.org/1999/xhtml">{htmlContent}</div></foreignObject></svg>';
function GetMap() {
map = new Microsoft.Maps.Map('#myMap', {
credentials: 'Your Bing Maps Key'
});
Running this sample in a browser that supports the SVG foreignObject tag will display a blue box with
the text “Custom Pushpin” inside it.
Bing Maps V7 to V8 Migration Guide
Additional Resources:
The Layer class is very different from the entity class. It only accepts IPrimitive shapes (pushpins,
polylines, polygons). One key feature of the Layer class in V8 is that it provides the ability to attach
mouse events to the layer. These events will fire if any of the mouse events occur on any of the data in
the layer. Since there is only one event handler needed, development is simplified and there is also a
performance benefit as well.
One key different between EntityCollections and Layer is how you add them to the map. You add an
EntityCollection by using the map.entities.push function. In V8, Layers are added using the
map.layers.insert function.
The following table shows links the main V7 EntityCollection functions to the V8 layer equivalents.
clear clear
get getPrimitives() returns an array you can
iterate over
getLength getPrimitives().length
getVisible getVisible
getZIndex getZIndex
indexOf getPrimitives().indexOf
insert add
push add or setPrimitives
remove remove
removeAt removeAt
setOptions Use setVisible and setZIndex
To minimize effort when migrating basic applications, an EntityCollection class is available in the VV8
control which wraps the Layer class. This wrapper flattens all child entity collections of an
EntityCollection into a single layer. This may result in some rendering differences when compared to V7.
There may also be some other unexpected behaviors when compared to V7. This class is still deprecated
and migrating over the Layer class is recommended.
Additional Resources:
Layer Class
LayerCollection Class
Additional Resources:
Bing Maps V7 to V8 Migration Guide
Before: V7
map.setView({ centerOffset: new Microsoft.Maps.Point(dx, dy) });
After: V8
var cp = map.tryLocationToPixel(map.getCenter());
cp.x += dx;
cp.y -= dy;
4. 0 Code Optimizations in V8
One common piece of feedback the Bing Maps team has received from developers over the years about
Bing Maps v7 is that the API is well structured, and easy to use. The development team for Bing Maps V8
really took this to heart and made an effort to not only maintain this when creating new features but to
also ensure these features are easy to use with other features in Bing Maps. In addition to this the team
spent some time investigating common tasks developers were doing with Bing Maps V7 and looked at
ways to reduce the amount of code required to accomplish these tasks. Many of these also provide a
small performance improvement as well. The following is a list of some of these common tasks and the
code optimizations that have been made available in V8. It is very important to note that in all of these
cases, the v7 code for accomplishing these tasks is still fully supported by V8. If you are migrating a V7
app to V8, you do not need to implement any of these code optimizations, however, you may find these
useful if adding additional features to your app, are looking to make performance improvements, or if
you want to clean up your code.
Before: V7
map = new Microsoft.Maps.Map(document.getElementById("myMap"), {
credentials: "YOUR BING MAPS KEY"
});
After: V8
map = new Microsoft.Maps.Map('#myMap', {
credentials: "YOUR BING MAPS KEY"
});
Before: V7
var shapes = [];
for(var i=0;i<shapes.length;i++){
map.entities.push(shapes);
}
Bing Maps V7 to V8 Migration Guide
After: V8
var shapes = [];
map.entities.push(shapes);
Not including the code to create the array of shapes, V8 requires 60% less code than V7.
Create a custom pushpin image in an image editor and then pass a URL to this image to the
pushpin. However, if you wanted several different colors, this meant creating several different
images.
Create a custom pushpin image in an image editor and make the color area transparent. In code,
use SVG or the HTML canvas to draw the area that you want to control the color of and then
draw the image overtop. This provided a programmatic way to change the color but required a
decent amount of code to maintain. The canvas solution was also known to be a bit buggy.
In Bing Maps V8 we simply added a color property to the PushpinOptions object. Not only can this be
used to change the color of the default pushpin, but you can also add “{color}” as a placeholder in inline
SVG and the pushpin will replace this placeholder with the value of the color property. This is a great
way to create pushpin templates.
Additional Resources:
Using CSS colors is a bit more familiar when creating web apps and using them instead of the Color class
has a slight performance benefit as there is no need to create an instance of the Color class which would
use more memory then a simple CSS color string.
Before: V7
polygon.setOptions({ fillColor: new Microsoft.Maps.Color(128,255,0,0) });
After: V8
polygon.setOptions({ fillColor: 'rgba(255,0,0,0.5)' });
In this scenario, V8 requires 26% less code than V7, however the performance improvement of V8 is the
real benefit.
Additional Resources:
Colors in V8
Color Class
Before: V7
Microsoft.Maps.Events.addHandler(map, 'click', function (e) {
var point = new Microsoft.Maps.Point(e.getX(), e.getY());
var loc = e.target.tryPixelToLocation(point);
After: V8
Microsoft.Maps.Events.addHandler(map, 'click', function (e) {
var loc = e.location;
});
Additional Resources:
Events documentation
Events interactive code samples
Before: V7
var shapes = [];
After: V8
var shapes = [];
In this scenario, V8 requires 15% less code than V7. However, the shapes are stored in a layer which will
make handling the data easier, especially if there are multiple layers of data. Additionally, the V8
solution provides a good performance benefits.
Additional Resources:
Layer class
Layer interactive code samples
with holes was needed. A great example is the borders of South Africa. Within the main borders of
South Africa is a land locked country called Lesotho. In order to correctly draw the borders of South
Africa a hole needs to be cut out of a polygon for Lesotho.
Some developers created workarounds in Bing Maps V7 initially, and not long after the Bing Maps team
added the AdvancedShapes module. Knowing that this is a more commonly used feature in today’s
apps, V8 supports polygons with holes in the core library. An AdvancedShapes module is no longer
required, however, to reduce migration efforts, if you do use the AdvancedShapes code from V7, it will
continue to work in V8.
Before: v7
var polygon = new Microsoft.Maps.Polygon(/*ring data*/);
Microsoft.Maps.loadModule('Microsoft.Maps.AdvancedShapes', function () {
map.entities.push(polygon);
});
After: V8
var polygon = new Microsoft.Maps.Polygon(/*ring data*/);
map.entities.push(polygon);
Not including the code to create the polygon object, V8 requires writing 74% less code than v7.
However, there is no need to make any code changes to a V7 app for this feature when migrating, unless
you would like to clean up the code.
Additional Resource:
Polygon Class
Polygon interactive code samples
Bing Maps V7 to V8 Migration Guide
Before: V7
Microsoft.Maps.loadModule('Microsoft.Maps.GeoJson', function () {
Microsoft.Maps.loadModule('Microsoft.Maps.HeatMap', function () {
});
});
After: V8
Microsoft.Maps.loadModule(['Microsoft.Maps.GeoJson', 'Microsoft.Maps.HeatMap'],
function () {
});
V8 requires 32% less code than V7 when loading two modules at the same time. V8 would provide even
more savings when loading more than two modules at a time. However, the performance improvement
of V8 is the real benefit.
Additional Resources:
Modular Framework
Modular Framework interactive code samples
Bing Maps V7 supports quadkey ids, but adding the other two types as tile layers requires passing in a
callback function that creates a URL for each tile instead of simply passing in a formatted tile URL. V8
now supports X, Y, Zoom and WMS bounding box tile layers.
map.layers.insert(tileLayer);
Important Note: In V8, the tiles levelOfDetail property name has changed to zoom. This is noted in the
map.layers.insert(tileLayer);
var wmsTileService =
'https://tileServerUrl?SERVICE=WMS&VERSION=1.1.1&REQUEST=GetMap&LAYERS=CoolData&width=2
56&height=256&BBOX='
Tip: When using custom tile layers, often the tiles are not everywhere and at all zoom levels. To reduce
the number of unneeded tile requests which can slow down your application and also hammer the tile
server for no reason you can specify a bounds and zoom level range of your tile layer in the TileSource
options.
Additional Resources:
Geocoding a Location
Getting Route Directions
Eventually, Search and Direction modules where added to the V7 control which wrapped the REST
services and made it easy to use in JavaScript and also provided a number of user friendly features such
as draggable routes and nicely formatted instructions. V8 also includes Search and Direction modules.
One new feature in the V8 directions module that wasn’t in V7 is a directions input panel option, which
provides a nice user interface for requesting directions. Using the modules is highly recommended as it
can save you writing a lot of code and it also ensures that best practices are implemented when
accessing the services. The REST services can continue to be used and are a good option if you need
complete control over how the data is rendered or if you simply need to perform a calculation without
any rendering.
If using the REST service or Search module to power a search textbox, you may find that Autosuggest
module provides an improved user experience. Note that the Autosuggest module can be used without
a map which is useful if your search box is on a separate page from your map.
Additional Resources:
Autosuggest module
Bing Maps V7 to V8 Migration Guide
function GetMap() {
var map = new Microsoft.Maps.Map('#myMap', {
credentials: "Your Bing Maps Key"
});
map.getCredentials(function (c) {
sessionKey = c;
});
}
Once you have a session key simply use this instead of your Bing Maps keys in your REST service
requests. See the Understanding Bing Maps Transactions documentation for more details on billable and
non-billable transactions.
1. Avoid post backs that cause the page to fully reload on pages that have maps. Every time the
page reloads a new session is created. Instead look at using AJAX to pull in data and make
requests without refreshing the page.
2. Keep the user on a single page. Spreading the mapping functionality across multiple pages
causes multiple page loads/refreshes which generate a lot of sessions. In many cases not only
does keeping the user on a single page and pulling in data accordingly reduce the number of
sessions created but it also makes for a much better user experience.
3. Generate a session key right after the map loads and store it in a global variable inside your app.
This will save you time later in your application when you need to use it.
4. If you have a long running application where you expect the user to be using the app for more
than 30 minutes, then generate the session key for each request to ensure the key doesn’t time
out.
If your application is storing data in a spatial database and have created a custom web service to return
the data to the webpage, send the spatial data back as Well Known Text. In SQL if you use the STAsText
or the ToString methods on a SqlGeometry or SqlGeography object, it will return a Well Known Text
string. Version 8 has a Well Known Text module that can easily parse this for you. This would be a much
better approach than creating custom data models for handling the spatial data. You can find
documentation on this module here. Interactive code samples can be found here.
Rather than storing your data in a database and creating a custom web service, or even worse, storing
your data in flat files, upload the data to the Bing Spatial Data Services. This service will expose it for you
as a spatial REST service that you can easily connect to using the Spatial Data Services module in v8.
There are many benefits to doing this;
Obtaining a user’s location can easily be done using the W3C Geolocation API. This API is exposed
through the navigator.geolocation property in the browser. The browser will display a notification to
the user the first time this API tries to get the users location, and ask permission to share this data.
This example shows how to request the user’s location and then display it on the map using a pushpin.
<!DOCTYPE html>
<html>
<head>
<title></title>
<meta charset="utf-8" />
<script type='text/javascript'
src='http://www.bing.com/api/maps/mapcontrol?callback=GetMap'
async defer></script>
<script type='text/javascript'>
function GetMap() {
var map = new Microsoft.Maps.Map('#myMap', {
credentials: ‘Your Bing Maps Key’
Bing Maps V7 to V8 Migration Guide
});
If you run this code a notification will be displayed asking if you want to share your location. If you allow
it to use your location the map will center on your location and a pushpin will be displayed.
This example shows how to monitor the user’s location and update the position of a pushpin as the user
moves.
<!DOCTYPE html>
<html>
<head>
<title></title>
<meta charset="utf-8" />
<script type='text/javascript'
src='http://www.bing.com/api/maps/mapcontrol?callback=GetMap'
async defer></script>
<script type='text/javascript'>
var map, watchId, userPin;
function GetMap()
{
map = new Microsoft.Maps.Map('#myMap', {
credentials: ‘Your Bing Maps Key’
});
}
function StartTracking() {
//Add a pushpin to show the user's location.
userPin = new Microsoft.Maps.Pushpin(map.getCenter(), { visible: false });
map.entities.push(gpsPin);
function UsersLocationUpdated(position) {
var loc = new Microsoft.Maps.Location(
position.coords.latitude,
position.coords.longitude);
function StopTracking() {
// Cancel the geolocation updates.
navigator.geolocation.clearWatch(watchId);
If you are a licensed Bing Maps Enterprise Customer you can contact the Bing Maps Enterprise support
team for assistance with any technical issue you have. They are available by email during EU and NA
business hours. You can find contact details for the support team here.
Developer Forums
The Bing Maps developer forums is also a good place to find migration assistance, especially if you are
not an Enterprise customer with access to the Enterprise Support team. The Bing Maps developer
forums are regularly monitored by community developers and by members of the Bing Maps team. You
can find the Bing Maps developer forums here.
Licensing Queries
If you have licensing related questions you should take them to your Bing Maps account manager if you
know who they are. If not, you can send queries to the Bing Maps licensing team and they will assist. For
queries inside of North or South America you can contact them at maplic@microsoft.com. For queries in
the rest of the world you can contact them at mapemea@microsoft.com.
1) If you don’t already have Fiddler installed, download and install it from here:
https://www.telerik.com/download/fiddler
2) When you first open Fiddler you may see an information dialog about the isolation technology in
Windows which may interfere with the app. You can ignore this.
4) Check both the Enable Rules and the Unmatched requests passthrough checkboxes
5) Press Add Rule. In the Rule Editor, copy and paste the following two lines into the two textboxes
and press Save.
REGEX:http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx(.*)
*redir:http://www.bing.com/api/maps/mapcontrol
6) With the rule checked, go to the webpage that has your v7 map and test your application. If you
are already on that page, refresh the page. There are a few signs you can use to verify if your
webpage is using V8;
a. The Bing logo will have a capital “B”.
b. The navigation bar, if displayed will look much different.
c. If you inspect the DOM of the map div you will find that it contains HTML5 canvas
objects.
7) If you notice any issues, open the browsers developer tools by pressing F12. Errors will generally
appear in the console and can often provide an indication of where the source of an issue is.
Using the developer tools, you can also add breakpoints in your application code and step
through the code, line-by-line, by pressing F10. This is a good way to find which line of code is
causing an issue. Once the line or block of code that is having issues is identified, check this
migration guide to verify that the feature in question is not deprecated, and if it is, if there is a
new alternative solution available.