Migration Guide

Bing Maps V6.3 to V8 Bing Maps V6.3 to V8 Migration Guide

Table of Contents 1.0 Introduction ...... 3 1.1 Purpose of this Guide ...... 3 1.2 But I’m not using v6.3, I’m using v5 or 6.x ...... 3 1.3 Why Bing Maps v8? ...... 3 1.4 Service Comparison...... 3 1.5 Notable Changes ...... 6 1.6 Suggested Migration Plan ...... 6 1.7 Next Steps ...... 6 1.8 Technical Resources ...... 6 2.0 Authentication ...... 7 2.1 Getting a Bing Maps Key ...... 7 2.2 How to authenticate the map ...... 7 3.0 Localization ...... 9 4.0 Mapping Examples ...... 10 4.1 Loading a Map ...... 10 4.2 Map Navigation ...... 12 4.3 Geocoding ...... 14 4.4 Reverse Geocoding ...... 15 4.5 Adding a Pushpin ...... 16 4.6 Adding Shapes ...... 17 4.7 Shape Layers & Collections ...... 19 4.8 Displaying Routes ...... 20 5.0 Additional Bing Maps Tips ...... 25 5.1 Optimizing Transactions with the REST services ...... 25 5.2 Bing Maps V8 Tips & Tricks ...... 25 5.3 Determining a User’s Location ...... 28 6.0 Useful Tools & Support ...... 30 6.1 Migration Support ...... 30 6.2 Bing Maps Blog ...... 30 6.3 Bing Maps v7 Modules CodePlex project ...... 30 Appendix A: Bing Maps v6.3 to v8 class Mapping ...... 31 A1: Class Type Mapping ...... 31

Bing Maps V6.3 to V8 Migration Guide

A2: Map Functions Mapping ...... 33

Bing Maps V6.3 to V8 Migration Guide

1.0 Introduction 1.1 Purpose of this Guide This guide is designed to support you in your Bing Maps migration from version 6.3 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. 1.2 But I’m not using v6.3, I’m using v5 or 6.x It is possible that your application appears to be pointing to older versions of Bing Maps (i.e. v6.2 or v5), however these versions are actually redirecting to the v6.3 control on the backend and have been doing so for over 6 years. So in reality your application is using v6.3. 1.3 Why Bing Maps v8? The version 6.3 of Bing Maps has been around for over 7 years and hasn’t seen any code updates since the release of Bing Maps v7, 6 years. Version 8 of Bing Maps was just recently released and offers numerous advantages over both v6.3 and v7, including:

 Faster and more fluid map control  A cleaner, more modern, programming model  Increased culture support  World Wrap support  Improved Routing Capabilities  Traffic data available in outside of the US  Ability to optimize transactions using map sessions  Mobile browser support  Many new features 1.4 Service Comparison The Bing Maps v8 web control is the recommended migration path from v6.3. There is a small learning curve as there has been some notable improvements made in the code syntax from v6.3 to v8.

Faster and more fluid map control

When it comes to performance the v8 is miles ahead of v6.3. Version 8 is capable of rendering data much faster than versions 6.3 and 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. Noticeable performance issues in v6.3 have generally occurred when 200 or more pushpins have been added to the map, while v8 is capable of rendering thousands of pushpins and polygons with good performance.

A cleaner, more modern, programming model.

One of the most notable changes in v8 is that the API uses a Microsoft namespace. Doing this significantly reduces code conflicts between 3rd party JavaScript libraries. This also significantly speeds up the map control as there are less global variables for the browser to keep track of. In v6.3 the code

Bing Maps V6.3 to V8 Migration Guide

was made to be backwards compatible with previous versions of Bing Maps. This was a nice feature but resulted in the map control growing significantly and in some cases multiple functions were created that did the same thing thus making the API much more confusing to use than needed. Version 8 also uses a modular framework. Many features of the map API are needed when the page loads. By modularizing the API additional features can be loaded when need, often sometime after the page has loaded. As a result, the initial JavaScript downloaded which contains the core functionalities needed to load the map and display data on it is significantly smaller than the JavaScript downloaded by v6.3.

Increased culture support

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

World Wrap Support

In v6.3 of Bing Maps the map consisted of a single map that was disconnected at the edges. In reality we know that the far edges of the map wrap around and attach in real life but we can’t see this in v6.3. This becomes an issue if you want to represent information that crosses that edge. In v6.3 if you try and draw the shortest path between Sydney Australia and Los Angeles, USA it would take you across the full map. In v8 the map wraps around such that we can continually pan left or right just as if you were to spin a globe. In addition to this if you were to repeat the previous task of drawing a shortest path, v8 would draw the line going over the Pacific Ocean which is the shortest most logical route to take. Overall this makes for a much better user experience.

Improved routing capabilities

In v8 not only can you easily render routes on the map but users can also drag the route using the mouse if they wanted to modify it to go through a certain area or avoid another. In addition to this the directions module also generates nicely formatted directions for you with keyword bolding, and turn by turn icons. So no more having to generate HTML from the raw route data like you have to with v6.3. In addition to this hovering over one of the instructions shows you where that location is on the map. The direction module also has an optional input panel you can display which can save you a lot of development. Version 8 also provides driving, walking and transit directions.

Traffic data outside of the US

Traffic data has been available in Bing Maps for a number of years, however, in earlier versions of Bing Maps it was only available in the US. In v8, traffic data is available in 35 countries.

Bing Maps V6.3 to V8 Migration Guide

Ability to optimize transactions using map sessions

In v7 the concept of map sessions was introduced and has been carried over to v8. When one of the interactive Bing Maps map controls is loaded, a special Bing Maps key, called a session key, can be retrieved from the map and uses to access the Bing Maps REST and Spatial Data Services. Any transactions occurred using the session key as non-billable in the reports. A session starts when a map is loaded and ends when the browser is closed, the user leaves the page, or the page is refreshed. This can help significantly reduce the number of billable transactions that get generated by your application and as a result make a big difference in terms of licensing by potentially lowering your overall billable usage.

Mobile browser support

Not only is v8 supported in most modern desktop browsers, it is also supported on all major mobile browsers as well.

Many new features

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 V6.3 to V8 Migration Guide

1.5 Notable Changes As mentioned in the previous section, the v8 control has been redesigned from the ground up and as a result there are some significant syntax changes in the API. In addition to these changes other notable changes include:

3D functionality removed

The Bing Maps 3D control was released as a beta control over a decade ago. It was originally developed using Active-x which required an add-in to be installed into your browser. Since the original release of this control web technology has changed significantly. The Bing Maps team announced the deprecation the 3D control in November 2010 and officially deprecated it in December 2011. Even though it was deprecated it has been left online so as not to break applications built on top of v6.3. If you require a 3D map control, we recommend taking a look at the Windows 10 UWP map control which provides rich 3D maps that are significantly more detailed than what was available in v6.3. 1.6 Suggested Migration Plan To assist you with planning, we have compiled this list of high‐level steps to use as a baseline plan to move your codebase and development practices to version 8 equivalents. While your ultimate plan will depend on your specific situation, the following steps outline suggested components of any effort:

1) Review existing application and identify where Bing Maps v6.3 code is being used. 2) Identify which features of Bing Maps v6.3 are being used and review the migration information in this document or Appendix A: Bing Maps v6.3 to v8 class Mapping. 3) Migrate code to version v8 of Bing Maps and update script reference to point to the new v8 map control URL. 4) Test your migrated application. 5) Deploy your application to your production environment. 1.7 Next Steps The remaining sections of this migration guide provides sample code that introduces you to the basics of how to leverage the most commonly used v6.3 functionality using the v8 API. You will also find discussions on the differences in the general development cycle and authentication between the two platforms. 1.8 Technical Resources Here is a list of useful technical resources for the Bing Maps v8 web control.

 Bing Maps v8 Interactive SDK  Bing Maps v8 documentation  Bing Maps MSDN documentation (All Bing Maps APIs)  Bing Maps MSDN Forums  Bing Maps Dev Center  Bing Maps REST Services (MSDN)  Bing Spatial Data Services (MSDN)  Bing Maps Terms of Use

Bing Maps V6.3 to V8 Migration Guide

2.0 Authentication The Bing Maps terms of use states that you must use proper authentication credentials when using Bing Maps SDK. However, the v6.3 control did not throw an error if credentials were not provided. As a result, there has been a number of production applications released that are not properly authenticated. If you do not have a Bing Maps key, you will need this to authenticate the Bing Maps v8 control and to access any of the Bing Maps services. 2.1 Getting a Bing Maps Key There are two functions in which you can get a Bing Maps key. This first function is recommended if you fall into one of these categories;

 Are an enterprise customer who has a volume license agreement with Microsoft.  Currently generate more than 500 thousand transactions a month. Documentation on transactions can be here.  Are using Bing Maps in an asset tracking application.  Internal applications where you prefer to use a known user license (cost per user) rather than a transactional license.

The second function is recommended for all other applications that generate less than 500 thousand transactions a month.

Method 1: Create a Bing Maps Account

1) Create a Bing Maps account at the Bing Maps Dev Center. You can find documentation on how to create a Bing Maps account here. 2) Create a Bing Maps key. a. We invite you to use the “basic” key type and free use terms outlined in the Bing Maps Terms of Use (TOU) as you migrate to Bing Maps. Production applications outside the free use thresholds in the TOU will need a Bing Maps Enterprise account. For assistance with Bing Maps licensing, please contact [email protected] (including your Bing Maps Account Center ID). b. Enterprise customers are advised to use keys of type “basic” for all pre‐production application testing. An enterprise key should be created and used for production use. c. See the MSDN documentation for more information on Getting a Bing Maps key.

Method 2: License Bing Maps through Azure Marketplace

Sign up for the Bing Maps API for Enterprise in the Azure Marketplace here. If you do not have an Azure account, you will have to create one and provide a credit card. Fill out the forms provided and select the transaction level that meets your monthly transaction requirements. Note that you can change this at any time. One benefit of license Bing Maps through the Azure Marketplace is that you get the flexibility of licensing on a month to month basis, rather than being locked into a contract for one of more years. 2.2 How to authenticate the map This section of the migration guide discusses the differences in authentication functions between the v6.3 and v8. The main difference between these versions is that v6.3 requires you to create a map object, set the credentials on it and then load it, where as in v8 this all gets done with one line of code.

Bing Maps V6.3 to V8 Migration Guide

Additional the URL to version 8 has changed completely to align with the newer Bing branding, and to also reduce confusion about the meaning of “dev” in the v6.3 URL.

Before: v6.3

In v6.3 authentication of the map occurs by passing in a Bing Maps key into the maps SetClientToken or SetCredentials function before calling the LoadMap function. You can load the map control by adding a script reference to the API:

You would then create an instance of the map object and specify your credentials: var map = new VEMap('myMap'); map.SetCredentials('Your Bing Maps Key'); map.LoadMap();

Where 'mapDiv' is the id of the DIV element on the page that contains the map.

After: v8

The v8 control requires specifying authentication credentials when creating a new instance of the map, otherwise an error message appears on top of the map. First change the script reference to Bing Maps to version 8 like so:

You can then create an instance of the map object and specify your credentials: var map = new Microsoft.Maps.Map('#myMap', { credentials:'Your Bing Maps Key' });

Where 'mapDiv' is the id of the DIV element on the page that contains the map.

The script reference used above will load the map components synchronously as needed. Version 8 also supports asynchronous loading of the map control as well which is recommended for better page load performance. When loading the map script asynchronously you will need to provide the name of a callback function that will be called when the map script has been downloaded. Here is an updated map script reference that calls a GetMap function wen the script has finished downloading.

Bing Maps V6.3 to V8 Migration Guide

3.0 Localization Localization of maps is the process of rendering maps in a specific language other than the default. Both v6.3 and v8 support localization. Version 6.3 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 v6.3 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 v6.3 and how it can be done in v8.

Before: v6.3

To get a localized map using v 6.3, add an mkt parameter to the API script reference.

Bing Maps V6.3 to V8 Migration Guide

If you run this code in a browser, you should end up with a map that looks like the following image:

After: v8

In v8 things are slightly different. Rather than passing in our view settings as parameters when loading the map, instead an object that contains the view settings is passed in as a single parameter to the map. The following code is an example of how to load Bing Maps v8 such that it is centered over London, UK which is at coordinates (51.50632, -0.12714) at zoom level 10 with aerial imagery with labels displayed.

If you run this code in a browser, you should end up with a map that looks like the following image:

Try this in the interactive SDK 4.2 Map Navigation The maps in both v6.3 and v8 APIs can be programmatically moved to new geographic locations by calling the appropriate functions in JavaScript.

Before: v6.3

The v6.3 map control can be programmatically moved using one of several functions on the map including; Pan, PanToLatLong, SetAltitude, SetBirdseyeOrientation, SetBirdseyeScene, SetCenter, SetCenterAndZoom, SetHeading, SetMapMode, SetMapStyle, SetMapView, SetPitch, SetZoomLevel, ZoomIn, ZoomOut. This is a lot of functions and can be a bit confusing to figure out which one to use, especially since many of them appear to do the same thing. The following example moves the map center to the specified location (35.027222, -111.0225) and zooms to the specified level (15 of 19 available zoom levels). map.SetCenterAndZoom(new VELatLong(35.027222, -111.0225), 15);

Bing Maps V6.3 to V8 Migration Guide

Interestingly enough you might decide that the same thing could be achieved by doing the following: map.SetCenter(new VELatLong(35.027222, -111.0225)); map.SetZoomLevel(15);

However, if you try this, you will find that only the zoom level changes on the map.

After: v8

In the v8 control, you can use the setView function to accomplish the same thing as nearly all of those functions mentioned in the v6.3 section. The setView function takes in a set of view options which are used to define how the map should be displayed. This significantly reduces the complexity of the map control and also reduces issues like we saw in the previous example. The following example moves the map center to the specified location (35.027222, -111.0225) and zooms to the specified level (15 of 20 available zoom levels). map.setView({ center: new Microsoft.Maps.Location(35.027222, -111.0225), zoom: 15 });

Bing Maps V6.3 to V8 Migration Guide

Try this in the Interactive SDK 4.3 Geocoding Geocoding is the process of determining a specific latitude and longitude for a street address or other geographic feature or vice‐versa (reverse geocoding). The following examples highlight the differences in geocoding syntax between the v6.3 control and the v8 control.

Before: v6.3

In v6.3 there two functions on the map called Find and Geocode which can be used to make Geocoding requests. Again, we see multiple functions for doing the same thing in v6.3. Here is an example of a basic implementation used to geocode an address and return the results to a callback in v6.3: function GeocodeAddress(address) { map.Find(null, address, null, null, null, null, null, null, null, GeocodeCallback); } function GeocodeCallback(layer, results, places, hasMore, veErrorMessage) { // Do something with the results }

Alternatively using the Geocode function, the same thing can be done like this: function GeocodeAddress(address) { map.Geocode(address, GeocodeCallback); } function GeocodeCallback(layer, results, places, hasMore, veErrorMessage) { // Do something with the results }

After: v8

Bing Maps V6.3 to V8 Migration Guide

When using v8, geocoding can be accomplished using the Search module. Being a module you can delay the loading of this functionality until it is needed by the application. This helps improve page load performance. You can load the search module using the following code.

Microsoft.Maps.loadModule('Microsoft.Maps.Search', { callback: searchModuleLoaded });

Once the module is loaded you can use the SearchManager class to perform a geocode request. Here is an example of a basic implementation used to geocode an address and returns the results to a callback function in v8: function GeocodeAddress(address) { var searchManager = new Microsoft.Maps.Search.SearchManager(map); searchManager.geocode({ where: address, callback: GeocodeCallback }); } function GeocodeCallback(results, userData) { // Do something with the results }

4.4 Reverse Geocoding The term geocoding generally refers to translating a human-readable address into a point on the map. The process of doing the converse, translating a point into a human-readable address, is known as reverse geocoding.

Before: v6.3

In v6.3 reverse geocoding is done using the FindLocation function on the map. Here is an example of a basic implementation used to reverse geocode a coordinate in v6.3: function GetAddress(coordinate) { map.FindLocations(coordinate, ReverseGeocodeCallback); } function ReverseGeocodeCallback(result) { // Do something with the results }

After: v8

When using v8, reverse geocoding can be accomplished using the Search module. You can load the search module using the following code.

Microsoft.Maps.loadModule('Microsoft.Maps.Search', { callback: searchModuleLoaded });

Once the module is loaded you can use the SearchManager class in it to preform your reverse geocode request. Here is an example of a basic implementation used to reverse geocode a coordinate in v8 function GetAddress(coordinate) { var searchManager = new Microsoft.Maps.Search.SearchManager(map); searchManager.reverseGeocode({ location: coordinate, callback: ReverseGeocodeCallback }); }

Bing Maps V6.3 to V8 Migration Guide

function ReverseGeocodeCallback(results, userData) { // Do something with the results }

4.5 Adding a Pushpin Both the v6.3 control and the v8 control allow you to add one or more pushpins to the map controls. Pushpins are used to mark specific locations on a map.

Before: v6.3

In v6.3 you would create a VEShape object and define it as a Pushpin. The following creates a pushpin in the center of the map. var center = map.GetCenter(); var pin = new VEShape(VEShapeType.Pushpin, center); map.AddShape(pin);

After: v8

In v8 there is a Pushpin class that you can use. The following creates a pushpin in the center of the map. var center = map.getCenter(); var pin = new Microsoft.Maps.Pushpin(center); map.entities.push(pin);

Bing Maps V6.3 to V8 Migration Guide

Try this in the interactive SDK

You can find additional information on how to customize pushpins in v8 here. 4.6 Adding Shapes Both the v6.3 control and the v8 control allow you to add one or more polylines and polygons to the map.

Before: v6.3

In v6.3 you would create a VEShape object and define it as a Polyline or Polygon. The following creates a polyline from New York to Seattle and colors it purple. var vertices = [new VELatLong(40.75, -73.98), new VELatLong(47.6, -122.33)]; var polyline = new VEShape(VEShapeType.Polyline, vertices); polyline.SetLineColor(new VEColor(100, 0, 100, 0.39)); map.AddShape(polyline);

Bing Maps V6.3 to V8 Migration Guide

After: v8

In v8 there is are Polyline and Polygon classes that you can use. The following creates a polyline from Sydney to Los Angeles and colors it purple. var vertices = [new Microsoft.Maps.Location(40.75, -73.98), new Microsoft.Maps.Location(47.6, -122.33)]; var polylineColor = new Microsoft.Maps.Color(0.39, 100, 0, 100); var polyline = new Microsoft.Maps.Polygon(vertices, { strokeColor: polylineColor }); map.entities.push(polyline);

Note that the VEColor constructor takes in parameters as (r, g, b, a) whereas the Microsoft.Maps.Color constructor takes in parameters as (a, r, g, b). In v8 you can also use CSS color string as documented here.

Bing Maps V6.3 to V8 Migration Guide

One noticeable difference is that in v8 there is no pesky pushpin appearing in the center of the polyline for no reason. 4.7 Shape Layers & Collections Both v6.3 and v8 have a function of grouping shapes together as a layer or collection.

Before: v6.3

In v6.3 the VEShapeLayer class would be used for grouping shapes together. Once you have created a VEShapeLayer you can add it to the map using the AddShapeLayer function that is on the map. You can then add your shapes to the layer in a similar way to how you would add them to the map as shown here: var layer = new VEShapeLayer(); map.AddShapeLayer(layer);

//Add Shapes to Layer var pin = new VEShape(VEShapeType.Pushpin, new VELatLong(0, 0)); layer.AddShape(pin);

After: v8

In v8 the Layer class is used for grouping shapes together. Similar to v6.3, you can then add your shapes to the layer in v8 as shown here: var layer = new Microsoft.Maps.Layer(); map.layers.insert(layer);

//Add Shapes to Layer var pin = new Microsoft.Maps.Pushpin(new Microsoft.Maps.Location(0, 0)); layer.add(pin);

Bing Maps V6.3 to V8 Migration Guide

4.8 Displaying Routes Both API’s allow you to add customized routes to the map control. In both of the examples below, routes are calculated and drawn on the map by specifying a series of waypoints.

Before: v6.3

Directions in v6.3 are requested using the GetDirections function on the map. The following is an example of how to use this function to get directions from Seattle, WA to Redmond, WA.

If you run this code in a browser, you should end up with a map that looks like the following image:

Bing Maps V6.3 to V8 Migration Guide

After: v8

There are two ways to get directions into Bing Maps. The first option is to use the Bing Maps Directions Module. This is an easy to use module that allows you to easily import the routing functionality into Bing Maps. In addition to being able to render a route on the map it can also generate nicely styled instructions. The following is an example of how to use the directions module to get directions from Seattle, WA to Redmond, WA.

If you run this code in a browser, you should end up with a map that looks like the following image:

Bing Maps V6.3 to V8 Migration Guide

Bing Maps V6.3 to V8 Migration Guide

Try this in the interactive SDK

Notice how much nicer the instructions are and how much easier it was to create them. You didn’t have to loop through the callback and create the HTML yourself. Version 8 even provides alternative route suggests as well. Note that the route result data is available in the directions manager. If you would prefer to format the turn by turn instructions yourself, you can use the route result information to do this instead.

Bing Maps V6.3 to V8 Migration Guide

5.0 Additional Bing Maps Tips 5.1 Optimizing Transactions with the REST services If you are using the Bing Maps REST or Spatial Data services with a Bing Maps controls, you can optimize your application to reduce the number of transactions it uses. This can be done by making use of sessions. A session occurs when a map is loaded and lasts until it is unloaded or the page it is on is refreshed. To take advantage of sessions you need to generate a session key from the map. A session key is special Bing Maps key that when used with the Bing Maps REST services marks all the requests as non-billable transactions. If your application provides users, the ability to geocode and/or perform routing requests sessions can drastically reduce the number of billable transactions that occur. To make things easy it is best to generate a session key right after the map loads and store it like this: var sessionKey; 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.

Here are a few tips to maximize your use of sessions:

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. 5.2 Bing Maps V8 Tips & Tricks The following is a list of useful tips and tricks when developing with the Bing Maps v8 map control.

Add and array of shapes to the map

In all previous versions of Bing Maps, adding an array of shapes required looping through the data and adding each shape individually. This often required 3 – 5lines of code. In v8, simply pass the array into

Bing Maps V6.3 to V8 Migration Guide

map.entities.push or the Layer.insert functions and the map will add them all for you. This reduces the code down to a single line.

Create polygons with holes

Version 6.3 of Bing Maps did not have any support for polygons with holes, however there was a hack to work around this which required creating a line to each hole from the outer ring. Version 8 supports polygons with holes by default. Simply pass in an array of Location arrays, where each Location array is a ring of the polygon.

Load two modules at the same time

Sometimes you may need to load multiple modules. Instead of them one by one you can create an array of all the module names you wish to load and load them in a single call. There are two benefits to doing this. The first is that it requires a lot less code and second the modules can be loaded in parallel rather than synchronously which will allow you code to start using the modules sooner.

Use the Autosuggest module on its own

It is common for applications to have a search box on a different page from their map page. Often these applications call the Bing Maps REST geocoding service to get the coordinate of the user’s query. However, if a location isn’t found for the user’s location, often the user would have to do another search which would generate another billable transaction. The autosuggest module provides a much better user experience by providing suggestions as the user types. It can also be used with or without a map. Additionally, all the suggestions are known locations in Bing Maps, thus reducing the number of potential queries and reducing the number of billable transactions generated by your application. This module is also great at helping users fill out address forms too. Documentation the autosuggest module can be found here. Interactive code samples can be found here.

Bing Maps V6.3 to V8 Migration Guide

Test Data Generator

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. You can find documentation here. Interactive code samples can be found here.

Spatial Data in SQL

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.

Host your data in the Bing Spatial Data Services

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;

 Your hosting requirements are less.  If you use a session key from the map, the first 9 million requests to this service are non-billable which would help reduce your overall costs.  The amount of code that would need to be maintained by your development team is very small compared to a custom database/web service solution.

Here are some useful resources:

 Spatial Data Services module documentation  Spatial Data Services module interactive code samples  Managing data sources through the Bing Maps portal

Bing Maps V6.3 to V8 Migration Guide

 Bing Spatial Data Services REST API’s 5.3 Determining a User’s Location Version 8 of Bing Maps provides a button that will center the map over the user’s location, however, depending on your application, you may want to do more than just this with the user’s location.

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.

Example - Display user’s location

This example shows how to request the user’s location and then display it on the map using a pushpin.

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.

Example – Continuously track user’s location

This example shows how to monitor the user’s location and update the position of a pushpin as the user moves.

Bing Maps V6.3 to V8 Migration Guide

Bing Maps V6.3 to V8 Migration Guide

6.0 Useful Tools & Support Here are some great tools that can be used to make your migration to Bing Maps easy. 6.1 Migration Support Technical support

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 [email protected]. For queries in the rest of the world you can contact them at [email protected]. 6.2 Bing Maps Blog The Bing Maps blog is where the Bing Maps team announces any new features about Bing Maps. In addition to this regular technical posts showing how to do new and interesting things with the Bing Maps controls are made available. You can find the blog here. 6.3 Bing Maps v7 Modules CodePlex project Both the Bing Maps v7 and v8 map controls support modules. Version 8 is largely backwards compatible with v7. Many modules have been created by the developer community for v7 over the years. Many of these also work with v8 and many of these functionalities already exist in v8. However, there are a few modules in the Bing Maps v7 Modules CodePlex project that may not be in v8 which provide additional functionality that you may require. For instance, there are great modules for importing GeoRSS and GPX data into the map.

Bing Maps V6.3 to V8 Migration Guide

Appendix A: Bing Maps v6.3 to v8 class Mapping A1: Class Type Mapping The table below lists every class type found in Bing Maps v6.3 and provides the corresponding Bing Maps v8 type or functionality to use.

V6.3 V8 VEClusteringOptions class ClusterLayerOptions object VEClusterSpecification class Use the Clustering module VEClusteringType Enumeration Microsoft.Maps.ClusterPlacementType Enumeration which is part of the Clustering module VEColor class Microsoft.Maps.Color or CSS color strings. Note that the VEColor constructor takes in parameters as (r, g, b, a) whereas the Microsoft.Maps.Color constructor takes in parameters as (a, r, g, b). VECustomIconSpecification class Use the PushpinOptions object to customize your pushpin icon. Additional pushpin customizations documented here. VEDashboardSize Enumeration Use the navigationBarMode map option to select a different size navigation bar. Alternatively use the showDashboard, showMapTypeSelector, showLocateMeButton, and showZoomButtons options of the MapOptions object to customize the map navigation control. VEDataType Enumeration Use one of the data modules; GeoJSON, Well Known Text, GPX, GeoRSS VEDistanceUnit Enumeration Both miles and kilometers are displayed on the map control. VEException class An error message is returned. VEFailedShapeRequest Enumeration Due to implementation differences, there is not a need for a corresponding type. VEFindResult class Use the Search Module. VEFindType Enumeration Use the Search Module. VEGeocodeLocation class Use the Search Module. VEGeocodeOptions class Use the Search Module. VEImageryMetadata class Use the Bing Maps REST Services to retrieve imagery metadata as described in the Get Imagery Metadata documentation. VEImageryMetadataOptions class Use the Bing Maps REST Services to retrieve imagery metadata as described in the Get Imagery Metadata documentation. VELatLong class Microsoft.Maps.Location VELatLongRectangle class Microsoft.Maps.LocationRect VELocationPrecision Enumeration Use the Search Module. VEMap class Microsoft.Maps.Map

Bing Maps V6.3 to V8 Migration Guide

VEMapMode Enumeration 3D is not supported. All available map types are found in the Microsoft.Maps.MapTypeId. VEMapOptions class Microsoft.Maps.MapOptions VEMapStyle Enumeration Microsoft.Maps.MapTypeId VEMapViewSpecification class ViewOptions object VEMatchCode Enumeration Use the Search Module. VEMatchConfidence Enumeration Use the Search Module. VEMiniMapSize Enumeration Use the Mini Map Module. VEModelFormat Enumeration 3D Models are not supported. VEModelOrientation class 3D Models are not supported. VEModelScale class 3D Models are not supported. VEModelScaleUnit Enumeration 3D Models are not supported. VEModelSourceSpecification class 3D Models are not supported. VEModelStatusCode Enumeration 3D Models are not supported. VEOrientation Enumeration Use the heading property of the ViewOptions object VEPixel class Microsoft.Maps.Point VEPlace class There is no equivalent class. VEPrintOptions class There is no equivalent class. VERoute class Microsoft.Maps.Directions.Route VERouteDistanceUnit Enumeration Microsoft.Maps.DistanceUnit VERouteHint class Use the postIntersectionHint and preIntersectionHint properties of the Microsoft.Maps.Directions.DirectionsStep class VERouteItinerary class Use the itineraryItems property of the Microsoft.Maps.Directions.RouteLeg class VERouteItineraryItem class Microsoft.Maps.Directions.DirectionsStep VERouteLeg class Microsoft.Maps.Directions.RouteLeg VERouteLocation class Use the address or location property of the Microsoft.Maps.Directions.WaypointOptions object VERouteMode Enumeration Microsoft.Maps.Directions.RouteMode VERouteOptimize Microsoft.Maps.Directions. VERouteOptions class Mircosoft.Maps.Directions.DirectionsRequestOptions or Microsoft.Maps.Directions.DirectionsRenderOptions VERouteSegment class Microsoft.Maps.Directions.RouteLeg VERouteType Enumeration Microsoft.Maps.Directions.RouteOptimization VERouteWarning class Use the warnings property of the Microsoft.Maps.Directions.DirectionsStep VERouteWarningSeverity Enumeration Use the warnings property of the Microsoft.Maps.Directions.DirectionsStep VESearchOptions class Use the Search Module. VEShape class Microsoft.Maps.Pushpin, Microsoft.Maps.Polygon, Microsoft.Maps.Polyline VEShapeLayer class Microsoft.Maps.Layer VEShapeAccuracy Enumeration Due to implementation differences, there is not a need for a corresponding type. VEShapeSourceSpecification class Microsoft.Maps.Layer

Bing Maps V6.3 to V8 Migration Guide

VEShapeType Enumeration Shapes can be either a Microsoft.Maps.Pushpin, Microsoft.Maps.Polygon, Microsoft.Maps.Polyline VETileSourceSpecification class Microsoft.Maps.TileSource and Microsoft.Maps.TileLayer

A2: Map Functions Mapping The table below lists every function found in the VEMap class of the Bing Maps v6.3 and provides the corresponding Bing Maps v8 functionality to use.

V6.3 VEMap Function V8 Equivalent VEMap.AddControl Overlay a div using absolute positioning. For example:

< /div>

My Control

VEMap.AddCustomLayer See VEMap.AddControls function. VEMap.AddShape Shapes can be added to the map in two ways, directly into the entities property of the Microsoft.Maps.Map class, or they can be added to a Microsoft.Maps.Layer which is inserted into the layers property of the map. TileLayer, ClusteringLayer, HeatMapLayer can be added to the map by inserting into the maps layers property. Infoboxes can be displayed by using the setMap function of the infobox. VEMap.AddShapeLayer Insert a Layer into the maps layers property. Live demo VEMap.AddTileLayer Insert a Layer into the maps layers property. Live demo VEMap.AttachEvent Use the addHandler or addThrottledHandler functions of the Microsoft.Maps.Events object. Live demo VEMap.Clear Objects stored in the entities property of the Microsoft.Maps.Map class can be removed using the map.entities.clear() function. Items in a Layer can be removed using the layer.clear() function. Layers can be removed from the map by using the map.layers.clear() function. An infobox can be removed from the map by using the setMap function. VEMap.ClearInfoBoxStyles Customize your own infobox using the htmlContent property of the InfoboxOptions object. Set your options using the setOptions function of the Microsoft.Maps.Infobox class. VEMap.ClearTraffic Use the hide function of the Microsoft.Maps.Traffic.Traffic Manager class to hide traffic. VEMap.DeleteAllShapeLayers Use the clear function on the maps layers property. Also use the clear function of the entities property if using that as well. VEMap.DeleteAllShapes Objects stored in the entities property of the Microsoft.Maps.Map class can be removed using the map.entities.clear() function. Items in a Layer can be

Bing Maps V6.3 to V8 Migration Guide

removed using the layer.clear() function. Layers can be removed from the map by using the map.layers.clear() function. An infobox can be removed from the map by using the setMap function. VEMap.DeleteControl Due to implementation differences, there is no need for corresponding functionality. VEMap.DeleteRoute Use the clearDisplay or resetDirections functions of the Microsoft.Maps.Directions.DirectionsManager Class. VEMap.DeleteShape Use the remove or removeAt functions of the Layer class or the maps entities property. VEMap.DeleteShapeLayer Use the remove or removeAt functions of the maps layers property, VEMap.DeleteTileLayer Use the remove or removeAt functions of the Layer class. VEMap.DetachEvent Use the removeHandler function of the Microsoft.Maps.Events object. VEMap.Dispose Use the dispose function of the Microsoft.Maps.Map class. VEMap.EnableShapeDisplayThreshol Due to implementation differences, there is no need for d corresponding functionality. VEMap.EndContinuousPan Use the JavaScript setTimeout function and the setView function of the Microsoft.Maps.Map class. VEMap.Find Use the Search Module. VEMap.FindLocations Use the Search Module. VEMap.Geocode Use the Search Module. VEMap.GetAltitude Use the Bing Maps REST Elevation Service VEMap.GetBirdseyeScene New birds eye experience being developed in V8. VEMap.GetCenter Use the getCenter function of the Microsoft.Maps.Map class. VEMap.GetDirections Use the calculateDirections function of the Microsoft.Maps.Directions.DirectionsManager class. VEMap.GetHeading Use the getHeading function of the Microsoft.Maps.Map class. VEMap.GetImageryMetadata Use the Bing Maps REST Services to retrieve imagery metadata as described in the Get Imagery Metadata topic. VEMap.GetLeft Use the getPageX function of the Microsoft.Maps.Map class. VEMap.GetMapMode 3D is not supported. All available map types are found in the Microsoft.Maps.MapTypeId Enumeration. VEMap.GetMapStyle Use the getMapTypeId function of the Microsoft.Maps.Map class. VEMap.GetMapView Use the functions of the Microsoft.Maps.Map class to return information about the current or target map view. VEMap.GetPitch 3D is not supported. VEMap.GetRoute Use the calculateDirections function of the Microsoft.Maps.Directions.DirectionsManager class. VEMap.GetShapeByID Add custom properties to the metadata property of a shape. Use the Filter class to search against the entities property of a map or within a Layer. VEMap.GetShapeLayerByIndex Use map.layers[index]

Bing Maps V6.3 to V8 Migration Guide

VEMap.GetShapeLayerCount When using the Layer class, use layer.getPrimitives().length VEMap.GetTileLayerByID Add custom properties to the metadata property of the TileLayer. Use the Filter class to search against the layers property of a map. VEMap.GetTileLayerByIndex Use map.layers[index] VEMap.GetTileLayerCount Loop through the layers in the map.layers property and count the number of tile layers. VEMap.GetTop Use the getPageY function of the Microsoft.Maps.Map class. VEMap.GetVersion No equivalent function. VEMap.GetZoomLevel Use the getZoom function of the Microsoft.Maps.Map class. VEMap.Hide3DNavigationControl 3D is not supported. VEMap.HideAllShapeLayers Loop through all layers in map.layers property and use setVisible(false) on each layer. This is supported by all layer types. VEMap.HideBaseTileLayer No equivalent function. VEMap.HideControl No equivalent function. VEMap.HideDashboard Use the showDashboard, showMapTypeSelector, showLocateMeButton, and showZoomButtons options of the MapOptions object to customize the map navigation control. VEMap.HideFindControl No equivalent function. VEMap.HideInfoBox Set the visible property of the InfoboxOptions object to false using the setOptions function of the Microsoft.Maps.Infobox class to hide an infobox. VEMap.HideMinimap Use the Mini Map Module. VEMap.HideScalebar Use the setOptions function of the Microsoft.Maps.Map class to set the showScalebar property of the MapOptions object. VEMap.HideTileLayer Use the setVisible function on the Microsoft.Maps.TileLayer class. VEMap.HideTrafficLegend Use the hide function of the Microsoft.Maps.Traffic.TrafficManager class to hide traffic. VEMap.Import3DModel 3D Models are not supported. VEMap.ImportShapeLayerData Use one of the data modules; GeoJSON, Well Known Text, GPX, GeoRSS VEMap.IncludePointInView Get the bounding box of the map, and use this to create an array of locations. Add the location that you wish to add to the view into the array. Use the LocationRect.fromLocation function to generate a new bounding box and use this with the setView function of the map. var bounds = map.getBounds(); var locs = [bounds.getNorthwest(), bounds.getSoutheast(), pointToInclude];

map.setView({ bounds: new Microsoft.Maps.LocationRect.fromLocation(locs) });

VEMap.IsBirdseyeAvailable No equivalent function.

Bing Maps V6.3 to V8 Migration Guide

VEMap.LatLongToPixel Use the tryLocationToPixel function of the Microsoft.Maps.Map class. VEMap.LoadMap Initialize a Microsoft.Maps.Map class. VEMap.LoadTraffic Use the show function of the Microsoft.Maps.Traffic.TrafficManager class. VEMap.Pan No equivalent function. VEMap.PanToLatLong Use the setView function of the Microsoft.Maps.Map class to set the center property of the ViewOptions object. VEMap.PixelToLatLong Use the tryPixelToLocation function of the Microsoft.Maps.Map class. VEMap.RemoveCustomLayer See VEMap.AddControls function. VEMap.Resize Simply change the map DIV size and the map will automatically resize accordingly. VEMap.Search Use the Search Module. VEMap.SetAltitude Set map view properties using the setView function of the Microsoft.Maps.Map class. VEMap.SetBirdseyeOrientation Set map view properties using the setView function of the Microsoft.Maps.Map class. VEMap.SetBirdseyeScene Set map view properties using the setView function of the Microsoft.Maps.Map class. VEMap.SetCenter Use the setView function of the Microsoft.Maps.Map class to set the center property of the ViewOptions object. VEMap.SetCenterAndZoom Use the setView function of the Microsoft.Maps.Map class to set the center and zoom properties of the ViewOptions object. VEMap.SetClientToken Client tokens are not supported. VEMap.SetCredentials Use the credentials property of the MapOptions object to set the map credentials. Your credentials are your Bing Maps Key. VEMap.SetDashboardSize Use the navigationBarMode of the MapOptions object to select a navigation bar that is a different size. Note that the navigation bar automatically changes to a different size when the map is loaded on a mobile device. VEMap.SetDefaultInfoBoxStyles Create a basic infobox using the Microsoft.Maps.Infobox class. VEMap.SetFailedShapeRequest Due to implementation differences, there is no need for corresponding functionality. VEMap.SetHeading Use the setView function of the Microsoft.Maps.Map class to set the heading property of the ViewOptions object. VEMap.SetMapMode 3D is not supported. All available map types are found in the Microsoft.Maps.MapTypeId Enumeration. VEMap.SetMapStyle Use the setView function of the Microsoft.Maps.Map class to set the mapTypeId property of the ViewOptions object. VEMap.SetMapView Use the setView function of the Microsoft.Maps.Map class to set map view properties of the ViewOptions object. VEMap.SetMouseWheelZoomToCen The mouse wheel always zooms to the cursor position on the ter screen.

Bing Maps V6.3 to V8 Migration Guide

VEMap.SetPitch Use the setView function of the Microsoft.Maps.Map class to set the pitch property of the ViewOptions object. This will change the pitch of a Streetside image. VEMap.SetPrintOptions No equivalent function. VEMap.SetScaleBarDistanceUnit Scale bar displays both km and miles always. VEMap.SetShapesAccuracy Due to implementation differences, there is no need for corresponding functionality. VEMap.SetShapesAccuracyRequestLi Due to implementation differences, there is no need for mit corresponding functionality. VEMap.SetTileBuffer Due to implementation differences, there is no need for corresponding functionality. VEMap.SetTrafficLegendText Use the showLegend or hideLegend functions of the Microsoft.Maps.Traffic.TrafficManager class to hide/show traffic. VEMap.SetZoomLevel Use the setView function of the Microsoft.Maps.Map class to set the zoom property of the ViewOptions object. VEMap.Show3DBirdseye 3D is not supported. VEMap.Show3DNavigationControl 3D is not supported. VEMap.ShowAllShapeLayers Loop through map.layers property and make each layer visible. For example, map.layers[i].setVisible(true); VEMap.ShowBaseTileLayer No equivalent function. VEMap.ShowControl See VEMap.AddControls function. VEMap.ShowDashboard Use the navigationBarMode map option to select a different size navigation bar. Alternatively use the showDashboard, showMapTypeSelector, showLocateMeButton, and showZoomButtons options of the MapOptions object to customize the map navigation control. VEMap.ShowDisambiguationDialog The disambiguation dialog is not supported. VEMap.ShowFindControl The find control is not supported. VEMap.ShowInfoBox Add an infobox to the map using the Microsoft.Maps.Infobox class. VEMap.ShowMessage Add a div to your HTML page to show a message. VEMap.ShowMinimap Use the Mini Map Module. VEMap.ShowScalebar Use the setOptions function of the Microsoft.Maps.Map class to set the showScalebar property of the MapOptions object. VEMap.ShowTileLayer Add a tile layer to the map using the Microsoft.Maps.TileLayer class. VEMap.ShowTrafficLegend Use the showLegend function of the Microsoft.Maps.Traffic.TrafficManager class. VEMap.StartContinuousPan No equivalent function. VEMap.ZoomIn Use the setView function of the Microsoft.Maps.Map class to set the zoom property of the ViewOptions object. VEMap.ZoomOut Use the setView function of the Microsoft.Maps.Map class to set the zoom property of the ViewOptions object.