I read somewhere that nearly 80% of all data has some location-related aspect to it. Where are orders being shipped to, where are flood plains located and what rainfall amount are problematic for them, where are vendors and/or customers located, delivery routes, GPS tracking, where are voting districts located, where are the best hospitals located, where are the sales regions that produce the most revenue, and so on. It is highly likely that a significant portion of the data you work with has a location related aspect to it. Visually presenting this information could lead to better management decisions or possibly uncovering trends that were not evident before. It is important then that this information be presented using a location oriented approach. That is where Microsoft Virtual Earth fits in.

In this article, I want to start you on your way developing applications with Virtual Earth and get you thinking outside the box in regards to how you display information to visitors to your websites. For example, consider a sales report sorted descending by sales percentage. Maybe you could improve upon that report by presenting the data as a pie chart to help management see how specific postal codes compare to each other. Taking that idea even further, you could overlay that same information on a map and see that the top three postal codes are all one side of a particular highway. Maybe that’s important, maybe it’s not, but that fact would go unnoticed on a report or a pie chart. Geographically visualizing data takes the analysis to an entirely new visualization level and this is just one example.

Virtual Earth makes it easy to get started with developing location-based applications. First you’ll need to decide which technology you want to use. You have two choices; one uses the Virtual Earth AJAX Map Control where all the coding is done in JavaScript, and the other uses the ASP.NET Map Control contained in the Windows Live Tools for Visual Studio July 2008 CTP. In this article I’ll show examples that use both, but the ASP.NET Map Control has the advantage of being able to use managed code (Visual Basic, C# or any .NET language) and substantially reduces or totally eliminates the amount of JavaScript code you need to write. Managed code or JavaScript? I don’t know about you, but I will go with managed code every time. The AJAX Map Control’s primary advantage is that it is platform independent. Though it works in ASP.NET, it does not require ASP.NET. You can use it on any Web development platform.

But I’m getting ahead of myself. Let me back up and start with an answer to the question, what is Virtual Earth?

What Is Virtual Earth?

Virtual Earth is a service from Microsoft that provides a high-quality geospacial data and imagery platform for you to work with. Unfortunately that sounds like a Microsoft definition. What that really means is that Microsoft provides you, the developer, with a platform, API, and other tools to visualize your data on a map. That data could be something as simple as push-pin points indicating where retail stores are located, or maybe lines connecting points, or possibly polygons covering a geographic area, or a combination of all three.

Virtual Earth allows you to add content in several ways. You can add points, lines, and polygons via code or you can import data from other locations such as GeoRSS feeds, Keyhole Markup Language (KML), or GPS eXchange (GPX) files. In my examples, I’ll show you how to add content to a map using code and then I’ll move on to importing data from a GeoRSS feed.

The Virtual Earth platform consists of a number of features including imagery, buildings, geocoding, Yellow Pages and points of interest (POI), traffic, search & proximity, and routing & directions.

You can learn much more about Virtual Earth, download the SDK, check out Virtual Earth team blogs, and so on at http://dev.live.com/virtualearth.

Your First AJAX Control Map

Unlike ASP.NET controls that you are used to dragging and dropping onto an .aspx page, the Virtual Earth AJAX Map Control is added to a page via JavaScript code. The code required to add a Virtual Earth map to a Web page is minimal and does not require you to download or install anything on your development machine. Although I used Visual Studio to create an ASPX page, I could have dropped this code into a plain HTML page as well (Listing 1). You can see that the FirstMap.aspx Web form has two script sections. The first defines the reference to the Virtual Earth AJAX Map Control (v6.1). The second contains the JavaScript code required to launch the map. First a map variable is defined followed by the GetMap function. The GetMap function is called from the onload argument in the <body> tag. When the body of the page is loaded it launches the GetMap function. The GetMap function creates a new instance of the VEMap class in the <div id=’myMap’> tag located in the <body>. Opening the page in a browser causes the map to be displayed and in this example, since a specific geographic location was not specified for the map, the default map of the United States is displayed (Figure 1). Refer to the Virtual Earth SDK for additional properties and methods for the VEMap class.

With your simple map displayed, head over to http://dev.live.com/virtualearth/sdk/ for additional information pertaining to the Virtual Earth API, examples, on-line SDK, documentation, links to forums, and other developer-related information. For example, on the Learn More tab you will find a link to download the Virtual Earth Map Control SDK (CHM) file for off-line viewing (Figure 2).

The Virtual Earth Map Control SDK presents an interactive way to learn about the different things you can do with Virtual Earth. It displays all of the JavaScript source code for every example (Figure 3).

Location, Location, Location

In order to display a specific location on the map you will need to provide the longitude and latitude for the location. The process of determining the latitude and longitude coordinates of a particular location, such as an address, is called geocoding. For example, the code in Listing 2 displays a map centered on the Microsoft campus in Redmond (Figure 4).

This code introduces the VELatLong class which specifies the latitude and longitude of a single point on a map. It also expands on the arguments available for the LoadMap method (Table 1).

Ogres Are Like Onions

If you have seen the move Shrek then you know that ogres are like onions; they have layers. Virtual Earth maps are like onions as well in that they also have layers. Adding content to a map involves adding items (pushpins, polylines, and polygons) to a layer and then adding that layer to a map. I have taken the previous map of the Microsoft campus and added a few pushpins, lines, and a polygon (Listing 3) to produce the map in Figure 5.

I created the layer to contain the map objects in the CreateLayer function. Then I added all the Virtual Earth objects through calls to the AddPushpins(), AddPolylines(), and AddPolygon() functions. I introduced two key classes in Listing 3, VEShapeLayer and VEShape.

A VEShapelayer class contains VEShapes (pushpins, polylines, and polygons). You can create shape layers manually via JavaScript code or you can have them created for you based on data imported from GeoRSS data, custom map tiles, or from Live Search Map collections. I will cover importing data in an upcoming section.

VEShape classes represent the objects that are displayed on the map. The most important property, ShapeType, has three options: pushpin, polyline and polygon. The code in Listing 3 also demonstrates a number of other properties for the VEShape class including setting the shapes title, description, line width, line color, URL for additional information, and so on. Refer to the Virtual Earth SDK for additional properties, methods, and code samples for the VEShapeLayer and VEShape classes.

That covers the fundamentals of displaying content objects with the Virtual Earth AJAX Map Control. In the next section I will introduce you to the ASP.NET Map Control contained in the Windows Live Tools for Visual Studio July 2008 CTP.

Introducing the Windows Live Tools for Visual Studio

Microsoft released the Windows Live Tools for Microsoft Visual Studio July 2008 CTP to help developers quickly and easily add Windows Live services to their ASP.NET applications. It provides a set of controls that you add to a Web page to add Windows Live services into your Web applications. A deeper investigation of all the tools provided in the toolkit is better left for another article, but I will say that the MessengerChat and Contacts controls do look interesting. Obviously for this article I will focus on the ASP.NET Map Control. The ASP.NET Map Control provides access to the methods and properties derived from the Virtual Earth AJAX Map Control.

So what is the big deal about the ASP.NET Map Control? It sounds like it provides all the same features as controlling the Virtual Earth control via JavaScript code. The big deal is that you can implement nearly all of the same functionality utilizing managed code. That’s right, you can use Visual Basic, C#, or your favorite .NET language with the control, and like other ASP.NET controls, it provides a complete drag and drop experience inside Visual Studio 2008. If you are still using Visual Studio 2005 now might be the time to upgrade to Visual Studio 2008 since the Windows Live Tools for Visual Studio requires Visual Studio 2008 or Microsoft Visual Web Developer 2008.

You can find a link to the ASP.NET Map Control on the Windows Live Tools for Visual Studio page at http://dev.live.com/tools/.

Once you have the toolkit installed and launch Visual Studio 2008 you should see the Windows Live and Virtual Earth tabs added to your toolbox (Figure 6).

To use the control, drag the ASP.NET Map Control from the Virtual Earth tab onto a <div> tag and viola! instant map. You can size the ASP.NET Map Control with your mouse and set properties via the Properties window (Figure 7). The control is also available and fully configurable in Source mode.

<ve:Map ID="Map1" runat="server"
  Height="400px" Width="400px" ZoomLevel="4" />

The map displayed in Visual Studio is static and will not reflect any of the property changes you make until you run the page.

While being able to work with the ASP.NET Map Control at design time is nice, the real advantage is being able to manipulate and work with the control in the code-behind file. For example, this code centers the map over the Microsoft campus, zooms in to level 17, and sets the map style to Aerial.

Map1.Center.Latitude = 47.6439
Map1.Center.Longitude = -122.129
Map1.ZoomLevel = 17
Map1.MapStyle =

Look close at the code above. Do you see any JavaScript? No you don’t, and that is the primary advantage to using the ASP.NET Map Control.

Now I will replicate the same map that I created earlier using the AJAX Map Control and JavaScript but this time I will use the ASP.NET Map Control. Listing 4 shows the Visual Basic code required in the Page_Load event that matches the functionality of the prior sample. Figure 8 shows the page that gets executed has the same the results.

The code in Listing 4 really isn’t tremendously different than the JavaScript code used before. The primary difference, of course, is that this code is managed .NET code and the code resides in the code-behind file instead of in the file containing the markup or maybe even an external JavaScript library file.

I added an Imports statement to reference the Microsoft.Live.ServerControls.VE namespace in order to be able to reference the Virtual Earth classes. Then in the Page_Load I set the coordinates of the map, the zoom level, and the map style.

Map1.Center.Latitude = 47.6439
Map1.Center.Longitude = -122.129
Map1.ZoomLevel = 17
Map1.MapStyle = _

Next I created a shape layer and added it to the map. That shape will contain the pushpins, polylines and polygon.

'Add shapelayer to the map. Yes, this is done
'before items are added to the layer

By the way, yes, you can add multiple layers and control them independently. For example you could build a map to display your retail outlets. You could create three layers, one representing profitable stores, a second displaying the break-even stores, and the third the non-profitable stores. Through the use of a dropdown or perhaps option buttons you could set the Visible property for the specific layer to display and include a Show All option to display them all concurrently. After I created all the pushpins I created the polyline which uses a list of points to indicate the path of the line on the map.

Next I created the polygon, set some additional properties, and then created the list of points that define it. One thing to note is the use of HTML markup in a number of the properties. If you have ever wondered how pictures, text, graphics, links, etc., appear when you select an item on a map, now you know. Another property to take a look at is CustomIcon. In this example, I point to a graphic file on a remote Web server. I could have also referenced a graphic stored on the local Web server. My space here is limited but I suggest you take the time to review the Shape class to see what else you might want to use.

Importing GeoRSS Data

Now that you have seen how to create maps and manually add shapes (pushpins, polylines and polygons) with both the AJAX Map Control and the ASP.NET Map Control, I will show you how to import data to overlay your map.

So what is GeoRSS? GeoRSS is a variation on the popular RSS format and adds tags for point, polyline, and polygon data. Listing 5 contains the same pushpoint, polyline, and polygon information used to create the AJAX Map of the Microsoft campus earlier in the article.

At this point you should recognize some of the tags including the title and description. Obviously the <georss:point>, <georss:line> and <georss:polygon> correspond to pushpoints, polylines, and polygons. This GeoRSS file is very simple. When I review the file I’ll be using for the GeoRSS data import using the ASP.NET Map Control, you’ll see that I’ve added some additional tags.

Importing GeoRSS Data with the AJAX Map Control

In Listing 6 you can see that all of the code to manually add those map objects has been stripped out and replaced with these three lines.

var mylayer = new VEShapeLayer();
var veLayerSpec = new VEShapeSourceSpecification(
   VEDataType.GeoRSS, "MSFT_AjAX.xml", mylayer);
map.ImportShapeLayerData(veLayerSpec, null);

A new VEShapeLayer is created to contain the imported data points. Next a VeShapeSourceSpecification object is created and specifies that the import format (VEDataType.GeoRSS), the name of the GeoRSS file (MSFT_AJAX.xml), and the layer it will be imported into (mylayer). Finally the map’s ImportShapeLayerData method is called and imports the data.

Listing 6 contains the GeoRSS data being imported in this example. Running the page from Listing 5 results in the same map being displayed (Figure 9) as you saw earlier when I manually added the map objects.

Importing GeoRSS Data with the ASP.NET Map Control

The steps to import GeoRSS data using the ASP.NET Map Control are very similar. The code in Listing 7 imports an existing GeoRSS file (MSFT_ASPNET.xml) and displays it. First the initial position, map type, and zoom level are initialized. Next a shape layer is created and added to the map. The import happens on the next two lines. A ShapeSourceSpecification object is created with the import type specified (GeoRSS), the name of the GeoRSS file to import, and finally the layer to import the data on to. The DataType enum values are GeoRss, ImportXML, and VECollection. ImportXML is used primarily to import KML files and VECollection is used to import collections you may have created on Virtual Earth. I created Virtual Earth collections to get the latitude and longitude coordinates for all the samples in this article. Check out Virtual Earth for more information on creating and managing collections.

Lastly, the code calls the map’s ImportShapeLayerData method specifying the name of the ShapeSourceSpecification object, the name of the client-side JavaScript function to call when the import has completed, and a Boolean value which determines if the map focus should shift to display the imported data.

The GeoRSS data imported into the ASP.NET Map Control (Listing 8) is very similar to the data I used with the AJAX Map Control. The difference is in the polygon section at the end of the file. Just like I added HTML markup to some of the properties when manually adding map objects earlier in the article, you can add HTML markup to the GeoRSS file (which I did here) and use it to display a richer user experience.

Running the code in Listing 7 produces the map displayed in Figure 10.

Additional Data Importing Options

The two Virtual Earth map controls can import more than just GeoRSS formatted data. Other supported formats include KML, GPX and VECollection. Keyhole Markup Language (KML), like GeoRSS, is an XML-based format for managing the display of geospatial data in Google Maps and Google Earth. The GPS eXchange format (GPX) is a format for managing GPS data.

Another prime candidate for importing data is SQL Server. While SQL Server 2005 does not have the new geospacial data types that SQL Server 2008 provides, you could easily store latitude and longitude values for addresses in your databases. You could create a query to generate a list of your retail stores along with their address, website URL, manager name, phone number, latitude and longitude coordinates, and so on in order to generate a GeoRSS file to import into a map. You could add links to your corporate logo, store picture, etc., to create a rich user experience when they click on a specific store location.


I hope this introduction to developing Virtual Earth applications gets you thinking about new ways of delivering data to your users. There is still much to learn. For example, SQL Server 2008 has new geospacial data types that are tailor made to working with Virtual Earth. The Virtual Earth MapCruncher feature allows you to overlay your own map images over the Virtual Earth maps. You can learn more about MapCruncher and download it from http://dev.live.com/virtualearth/mapcruncher/.

There are additional server-side and client-side events to learn how to handle. For example, one of the samples in the Interactive SDK on the http://dev.live.com/virtualearth/sdk/ page demonstrates via JavaScript how to react to client-side events like zooming in and out and another demonstrates how to handle other mouse events like clicking and double-clicking. Other features like providing driving directions, displaying points of interest, working with birds-eye view, 3D maps and much more await your discovery. Check out the sidebars in this article where I’ve added a number of resources to help you continue the learning process. Good luck and happy mapping!