Virtual Earth 101

Virtual Earth 101

read somewhere that nearly 80 percent of all data has some location-related aspect. Some examples of common location-related data questions might include:

  • Where do we ship these orders?
  • Where are flood plains located, and what rainfall amounts are problematic for them?
  • Where are vendors and/or customers located?
  • What delivery route should we use?
  • Can we track shipments using GPS?
  • 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’s highly likely that a significant portion of the data you work with has a location-related aspect as well. Presenting this information visually could lead to better management decisions or even possibly uncovering trends that were not previously evident. A good application can present this information using a location-oriented approach. That’s where Microsoft Virtual Earth fits in.

This article aims to start you on your way developing applications with Virtual Earth, and get you thinking outside the box regarding the way you display information to your web site visitors or your corporate management.

For example, consider a postal code sales report sorted in descending order 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, which reveals that the top three postal codes are all on 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 level.

Virtual Earth makes it easy to get started developing location-based applications, but 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. The AJAX Map Control’s primary advantage is that it’s platform independent. Though it works in ASP.NET, it doesn’t require ASP.NET. You can use it on any web development platform.

The other option uses the ASP.NET Map Control contained in the just released Windows Live Tools for Visual Studio November 2008 CTP. The ASP.NET Map Control’s advantages are that you can control it via managed code (Visual Basic, C# or any .NET language) and it substantially reduces or totally eliminates the amount of JavaScript code you need to write.So should you choose managed code or JavaScript? I don’t know about you, but I’ll go with managed code every time. However, this article shows examples of both.

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 group of services 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 developers with a platform, API, and other tools for visualizing data on a map. That data could be something as simple as pushpin points indicating where retail stores are located, or lines connecting points, or 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. The examples first show how to add content to a map using code, and then 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 and proximity, routing and directions, 3D models, and more. These features are delivered by two separate but complimentary pieces: the Virtual Earth AJAX Map Control and (new to version 6.2), Virtual Earth Web Services 1.0.

You can learn much more about Virtual Earth, download the SDK, check out Virtual Earth team blogs, and so on at

Editor’s Note: This article was first published in the January/February 2009 issue of CoDe Magazine, and is reprinted here by permission.

Your First AJAX Control Map

Unlike ASP.NET controls that you drag and drop onto an ASPX page, you add the Virtual Earth AJAX Map Control to a page via JavaScript code. The code required 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 (FirstMap.aspx), I could have dropped the following code into a plain HTML page as well:

         My First Map                        
Figure 1. Default Map: Virtual Earth displays a default map when you don’t indicate a specific location.

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.2), and the second contains the JavaScript code required to launch the map. The second script first defines a map variable and then defines a GetMap function, which gets called from the onload argument in the tag. Therefore, when the body of the page has loaded it launches the GetMap function, which creates a new instance of the VEMap class in the

tag located in the . Opening the page in a browser causes the map to be displayed. In this example, because a specific geographic location was not specified, the page displays the default map of the United States (see Figure 1). Refer to the Virtual Earth SDK for additional properties and methods for the VEMap class.

With this simple map displayed, you can find 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 offline viewing (see Figure 2).

Figure 2. Offline Support: The Virtual Earth Map Control SDK (VirtualEarthSDK.chm) provides offline support for the Virtual Earth API.
Figure 3. Sample JavaScript: The Virtual Earth Interactive SDK provides JavaScript source code to learn from.

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 the JavaScript source code for every example (see Figure 3).

Location, Location, Location

Figure 4. Partial Campus View: This map view shows part of the Microsoft campus.

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


The preceding code introduces the VELatLong class, which represents the latitude and longitude of a single point. It also expands on the arguments available for the LoadMap method (see Table 1).

Table 1. Load Map Method Arguments: The table shows the arguments available for the LoadMap method, along with an example and description for each.






Refers to the location of the map center.

Zoom Level


Specifies the initial zoom level for the map.

Map Style


Specifies which type of map to display, road, aerial, or hybrid for example. Use the VEMapStyle enumeration for all the possible values.

Location Fixed


Specifies if the map location is fixed or not. This determines if the user can click and drag to change the map location.

Map Mode


Specifies if the map is viewed in 2D or 3D mode. 3D mode requires a browser plug-in be installed but provides a complete 3D experience without having to install client software as Google Maps does.

Display Dashboard


Specifies if the dashboard in the upper left corner displays the ability to switch between 2D and 3D modes.

Want to get rid of that annoying birds-eye popup displayed when the map loads? Add this code just after the line defining the map control.


Determining Latitude and Longitude Coordinates

I am a lifelong Miami Dolphins football fan. I have been since I was a kid growing up in South Florida but even I did not know that 25.957948, -80.238849 are the latitude and longitude coordinates at the center of the 50-yard line in Miami Dolphin Stadium (see Figure 5). How do I know that now? Because Virtual Earth provides map events that you can code handlers for. Take a look at the line immediately following the map.LoadMap line in Listing 1. The AttachEvent method specifies that the onclick event will be handled by the OnClickHandler function. Passed into the OnClickHandler is the event argument, e, which provides the button clicked and the x and y coordinates for the location clicked. The VEPixel object created from the e.mapX and e.mapY coordinates gets passed into the map's PixelToLatLong method to create the clickedLatLong object. The clicked position's latitude and longitude coordinates are then assigned to their respective locations on the screen.

Figure 5. Dolphin Stadium: Here's a Virtual Earth view of Dolphin Stadium.

Author's Note: See the "Mouse Events" section in the Virtual Earth Map Control SDK for additional supported mouse events.

Ogres Are Like Onions

Figure 6. Microsoft Campus Map with Overlays: This map identifies some of the buildings on the Microsoft campus.

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?they also have layers. Adding content to a map involves adding items such as pushpins, polylines, or polygons to a layer, and then adding that layer to a map. For example, Listing 2 takes the map of the Microsoft campus you saw earlier and adds a few pushpins, lines, and a polygon to produce the map in Figure 6.

The CreateLayer function creates the layer to contain the map objects, then adds All the Virtual Earth objects by calling the AddPushpins(), AddPolylines(), and AddPolygon() functions. Listing 2 introduces two key classes: VEShapeLayer and VEShape.

A VEShapelayer class contains VEShapes (such as pushpins, polylines, and polygons). You can create shape layers manually via JavaScript code or have them created for you based on data imported from GeoRSS data, custom map tiles, or from Live Search Map collections. This article covers importing data a little later.

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 2 also demonstrates a number of other properties for the VEShape class, including setting the shape's title, description, line width, line color, URL to click 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.

You've seen the fundamentals of displaying content objects with the Virtual Earth AJAX Map Control. The next section introduces the ASP.NET Map Control contained in the Windows Live Tools for Visual Studio, November 2008 CTP.

Introducing the Windows Live Tools for Visual Studio

Microsoft released the Windows Live Tools for Microsoft Visual Studio November 2008 CTP to help developers quickly and easily add Windows Live services to their ASP.NET applications. The CTP 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. 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 the same functionality using 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 because 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.

After you install the toolkit and launch Visual Studio 2008, you should see the Windows Live and Virtual Earth tabs added to your toolbox (see Figure 7).

Figure 7. VS Toolbox Support: The Visual Studio Toolbox with the Windows Live and Virtual Earth tabs expanded.
Figure 8. ASP.NET Map Control Properties: Here's the ASP.NET Map Control and the VS Properties window in design mode.

To use the control, drag the ASP.NET Map Control from the Virtual Earth tab onto a

tag and voila!?instant map. You can size the ASP.NET Map Control with your mouse and set properties via the Properties window (see Figure 8). The control is also available and fully configurable in Source mode.

The map displayed in Visual Studio is static and will not reflect any 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 =    Microsoft.Live.ServerControls.VE.MapStyle.Aerial
Figure 9. Sample Map with Overlay: This is the map that results when you run the ASP.NET Map sample code.

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

As an example, here's the same map created earlier using the AJAX Map Control and JavaScript but this time using the ASP.NET Map Control. Listing 3 shows the Visual Basic code required in the Page_Load event that matches the functionality of the prior example, while Figure 9 shows that the page displays identical results.

The code in Listing 3 is little different than the JavaScript code used before except that it's managed .NET code, and the code resides in the code-behind file rather than in the file containing the markup or an external JavaScript library file.

The added Imports statement references the Microsoft.Live.ServerControls.VE namespace, so the code can reference the Virtual Earth classes. The Page_Load method sets 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 = _     Microsoft.Live.ServerControls.VE.MapStyle.Aerial

Next it creates a shape layer and adds that to the map. That shape contains the pushpins, polylines and polygon.

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

Author's Note: You can add multiple layers and control them independently. For example, you could build a map to display your retail outlets using three layers: one representing profitable stores, a second displaying the break-even stores, and the third the non-profitable stores. Using a dropdown or option buttons, you could set the Visible property for the specific layer you want to display, and include a Show All option to display all of them concurrently.

After creating all the pushpins, Listing 3 creates the polyline, which uses a list of points to indicate the path of the line on the map.

Finally, Listing 3 creates a polygon, sets some properties for it, and then creates the list of points that define the polygon. Note how several of the properties use HTML markup. If you have ever wondered how pictures, text, graphics, links, etc., appear when you select an item on a map, you now know. Another property to take a look at is CustomIcon. This example points to a graphic file on a remote web server; however, it could have referenced a graphic stored on the local web server. Although space available here prevents further examples, you should 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'll show you how to import data to overlay your map.

GeoRSS is a variation on the popular RSS format that adds tags for point, polyline, and polygon data. For example, Listing 4 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 , and correspond to pushpoints, polylines, and polygons. This GeoRSS file is very simple.

Importing GeoRSS Data with the AJAX Map Control

In Listing 5 you can see that all the code required to add those map objects manually 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);
Figure 10. GeoRSS Data Import: This is the map displayed after importing the GeoRSS data.

The preceding code creates a new VEShapeLayer to contain the imported data points. Next, it creates a VeShapeSourceSpecification object, which specifies the import format (VEDataType.GeoRSS), the name of the GeoRSS file (MSFT_AJAX.xml), and the layer it should be imported into (mylayer). Finally, it calls the map's ImportShapeLayerData method to import the data.

Listing 4 contains the GeoRSS data being imported in the preceding example. Running the page from Listing 5 results in the same map being displayed (see Figure 10) as the earlier example that adds the map objects manually.

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 below imports an existing GeoRSS file (MSFT_ASPNET.xml) and displays it.

   Imports Microsoft.Live.ServerControls.VE   Partial Public Class GeoRSS_ASPNET   Inherits System.Web.UI.Page   Protected Sub Page_Load(ByVal sender As Object, _   ByVal e As System.EventArgs) Handles Me.Load   'Initialize map properties           Map1.Center.Latitude = 47.6439           Map1.Center.Longitude = -122.129           Map1.ZoomLevel = 17           Map1.MapStyle = _           Microsoft.Live.ServerControls.VE.MapStyle.Aerial   'Create new layer to contain shapes   Dim layer As New ShapeLayer           Map1.AddShapeLayer(layer)   Dim ShapeSpecs As New ShapeSourceSpecification( _             DataType.GeoRSS, "MSFT_ASPNET.xml", layer)           Map1.ImportShapeLayerData(ShapeSpecs, "", True)   End Sub   End Class

The preceding code first initializes the initial map position, type, and zoom level. 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.

Figure 11. Map with HTML Markup: This map results from importing the GeoRSS data with HTML markup included in the data.

The DataType enum values are GeoRss, ImportXML, and VECollection. ImportXML is used primarily to import KML files, while 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.

Lastly, the code calls the map's ImportShapeLayerData method, passing in 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 that determines whether the map focus should shift to display the imported data. Running the preceding code produces the map displayed in Figure 11.

The GeoRSS data imported into the ASP.NET Map Control (see Listing 6) is similar to the data used with the AJAX Map Control example, but it differs in the polygon section at the end of the file. Just like the HTML markup added to some of the properties when adding map objects manually earlier, you can add HTML markup to the GeoRSS file (as shown here) to provide a richer user experience.

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 can easily store latitude and longitude values in your databases. For example, you could create a query to generate a list of retail stores along with their address, website URL, manager name, phone number, latitude and longitude coordinates, and so on to generate a GeoRSS file that you could import into a map. You could add links to your corporate logo, store picture, etc., to create a rich user experience when people 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 or download it here. The Virtual Earth Web Services 1.0, new in version 6.2, provides imagery, search, geocoding, and routing services.

There are additional server-side and client-side events you should learn how to handle. For example, one sample in the Interactive SDK demonstrates how to react to client-side events such as zooming in and out using JavaScript; another shows how to handle other mouse events, such as clicking or double-clicking. Other features that make it easy to provide driving directions, display points of interest, work with birds-eye views, 3D maps, and much more await your discovery. Check out the Virtual Earth Resources sidebar, which lists a number of resources to help you continue the learning process. Good luck and happy mapping!


Share the Post: