As part of my job, I spend a lot of time working with the Microsoft Virtual Earth teams. Since version 6.2 of Virtual Earth just released, along with the new VE Web Services, I figured this is a good time for my first VE-related blog.

One aspect of the Virtual Earth infrastructure that hasn't received the attention it probably deserves is Client Tokens. A token is a unique value that can be used both for reporting map usage and acts as the authentication method used for some aspects of Virtual Earth functionality, plus the two related web service offerings - MapPoint Web Service (MWS) and the new Virtual Earth Web Service (VEWS).

I get a lot of questions about the tokens when I take calls from VE customers, and since it's becoming more important within the mapping platform, it seems like a good thing to spend just a little time providing nice, clean code for.

Follow up:

I'll be working in C# and in Visual Studio, so my examples will be specific to that, but there's nothing here that won't work in other languages/environments.

Getting a Developer Account:

In order to get started, you'll need a Virtual Earth Platform Developer account. Without a licensing agreement, you'll only have access to the staging servers, but that's enough for what I'll be talking about here.

Once you have your account, you can sign in to the the Customer Service Site and set your account password.

One word of caution here, there seems to be a lot of confusion about what name & password to use. In order to sign up for the VE Developer account, you need to supply a LiveID and a password. Then, once you sign up, you are assigned a few pieces of information: an account name which looks like COMPANY123456, a data source name which looks like COMPANY123456.123456, and an account ID (just 123456). For logging into the Customer Service Site, use your LiveID & password. For connecting to the Virtual Earth web services, use the Account ID (123456) and the password you set at the customer service site.

It can take a couple hours for your account to be activated, and the customer service site has a page to test your id & password until it is.

Adding the Token Service to the project:

Just some standard web service stuff here. The Token Service is supplied by a web service which resides at https://staging.common.virtualearth.net/find-30/common.asmx (or at least the staging version of it does). Open or Create a new Visual Studio project. In the solution explorer, right-click on the project node and select "Add Web Reference...", input the URL above and press 'Go'. When asked for your name and password, use the account ID (numbers only) and password. You may have to enter them a couple times. Once the web service is showing, it will also provide you with a Web Reference Name of 'net.virtualearth.common.staging'.

Once the web service reference is added to the project, you need to add the 'using' directive to the top of your C# file. Take the base namespace for your project (for my test web application it was 'WebApplication1'), and add the name it was given when you added the service:

using WebApplication1.net.virtualearth.common.staging;

You will also need System.Net, so go ahead and add it now while you're at it.

Writing code against the Token Service:

The Token Service has a method named GetClientToken(), and Intellisense will come in handy, but really the code is very simple:

// Get a reference to the service, supply your credentials
CommonService commonService = new CommonService
{
   Credentials = new NetworkCredential(accountID, password)
};

// Construct a request for the token, note that you supply
// the visiting IP & the time that the token should live for
// (15-480 minutes)
TokenSpecification tokenSpec = new TokenSpecification
{
   ClientIPAddress = Page.Request.UserHostAddress,
   TokenValidityDurationMinutes = 60
};

// Make the request
string token = commonService.GetClientToken(tokenSpec);

Now that you have the token you can use it to access MapPoint Web Services, the new Virtual Earth Web Services, or access some special functionality in Virtual Earth itself.

Have fun, and good mapping.