You Can’t Fire Me, I Don’t Work In This Van

Today we released a framework for interacting with Microsoft’s Virtual Earth Web Services called VirtualEarthKit. I thought I’d put together a little tutorial on using this framework.

To get started you’ll need:
• A Mac running Mac OS 10.5 (this is Objective C 2.0 so Mac OS 10.4 is not supported)
• Phillipe Casgrain’s CoreLocation framework for Mac OS X (included with VirtualEarthKit, if you’re on the iPhone you don’t need this)
• A Virtual Earth user id and password
• VirtualEarthKit

This tutorial expects that you know your way around Cocoa a bit, but most of the VirtualEarthKit classes are analogous to classes in the official Windows Communication Foundation API.

To get VirtualEarthKit, go to Terminal and type the following command:

svn co http://svn.consonancesw.com/vekit/trunk VirtualEarthKit

This will download the current version of VirtualEarthKit into the working directory in Terminal. We do plan to make a binary version available in the near future, but for now this is the quickest way to acquire VirtualEarthKit.

(Note: VirtualEarthKit works on the iPhone, but this tutorial is targeted for Mac OS X.)

Before you create a project, you should compile VirtualEarthKit via the included XCode project, and install both it and CoreLocation.framework into a frameworks directory of your choice (in Library/Frameworks at either the root of your drive or the home folder, for those of you new to Mac programming, this is where OS X looks for frameworks that your program may depend on.)

Next, create a new project in XCode. You can either create a command line utility, or a gui application. We just need to get to a place where we can execute code at some point. The example included at the end of this post just is a GUI app with some code included in an awakeFromNib function, but feel free to improve upon that.

Wherever it is you’ve decided to put this code, you’ll need to import the VirtualEarthKit header.

#import <VirtualEarthKit/VirtualEarthKit.h>

The first thing we have to do is acquire a Virtual Earth token. This is a magical string that you attach to every request you make to Virtual Earth. It lets Microsoft keep track of what resources of theirs you are using, and may impact your billing. To get a token, we need to first create a VECommonService object. The common service is just a representation for the general functions of Virtual Earth. While we’re at it we’ll declare the NSString to hold the token.


VECommonService *commonService = [[VECommonService alloc] init];
NSString *token;

Now to actually fetch the token… You’ll need your Virtual Earth user id (not your user name) and your password. Virtual Earth wants us also to supply the client IP address. As far as I can tell, this is mostly useful for servers who may be vending requests coming from different ips. For desktop apps, it may be a little more difficult to determine the outside ip of the machine. In talking with Microsoft I have found that the IP is simply for record keeping purposes for you. Don’t worry, you can supply a fake ip here and the world won’t explode. If you want to track usage by IP, you can ping off of whatismyip.com or something.


[commonService getToken:&token forUserID:@"yourUserID" password:@"yourPassword" ipAddress:@"192.168.0.1"];

See? Not at all painful. In the event of an error, getToken:… will return an NSError, but we’re going to be bad and assume everything went fine.

Now we’re going to perform a geocode operation. A geocode consists of giving Virtual Earth a place name, and it gives us back a coordinate. Virtual Earth also can do the reverse, find a place name for a coordinate (called a reverse geocode) but we won’t be doing that today…

To talk to Virtual Earth’s geocode service, we need to create a VEGeocodeService object.


VEGeocodeService *geocodeService = [[VEGeocodeService alloc] init];

Again, not too painful.

Now we need to create the actual request to send to the geocode service. This is represented by another object.


VEGeocodeRequest *geocodeRequest = [[VEGeocodeRequest alloc] init];

We need to set the place we want to find. For this example, I’m going to use Portland State University, the school I’m currently attending (as a CS student, of course.)

Don’t forget, we also need to attach that magic token to the request.


geocodeRequest.query = @"Portland State University";
geocodeRequest.token = token;

Now it’s time to send that request on it’s way using the geocode: function. The result is a VEServiceResponse.


VEServiceResponse *geocodeResponse = [geocodeService geocode:geocodeRequest];

The response is a wrapper class for any error from the server, and any actual results. Notice I used the plural form of the word result. A geocode can have multiple results. For example, searching for “London” might return London, UK or London, TX. For this example, I’m going to assume that we only care about the first example, and even worse, that we got one result. Note that if we didn’t get back any results this line will crash. Extra credit for testing to make sure that there is at least one result.


VEGeocodeResult *geocodeResult = [geocodeResponse.results objectAtIndex:0];

The VEGeocodeResult contains the nice gooey morsels of information we want. We can log them out to the console.


NSLog([geocodeResult.location description]);
NSLog([geocodeResult.address description]);

Note that VirtualEarth gave us back the location, and the nice clean address of Portland State. Nifty! The location property is going to be a CLLocation. The address property is an NSDictionary formatted for the Address Book framework, so you can shove that right into a contact or whatever.

(Here is the extra special iPhone note: The iPhone and Mac OS X use slightly different constants in their Address Book framework keys. I don’t know what this means for serialized addresses being moved between Mac OS X and an iPhone. VirtualEarthKit will always use the native constants of the current platform.)

So at this point you’re probably thinking this is pretty cool, but wait! There’s more! We can actually open a map of Portland State University based on this information!

Our starting point will be a lot like where we started with the geocode. We’re going to need to create the service object (this time for the imagery service…)

VEImageryService *imageryService = [[VEImageryService alloc] init];

Now we need to create the request. For a static map, we use the VEMapURIRequest object. If you want to fetch map tiles, this is not the best way, you’d want to use the VEImageryMetadataRequest object, but that’s the topic of a different tutorial. For now, we want Virtual Earth to do the rendering for us.


VEGetMapURIRequest *mapRequest = [[VEGetMapURIRequest alloc] init];

Now we set the center of the map request to the location we got from our geocode. Remember, we need to include the magic token.


mapRequest.center = geocodeResult.location;
mapRequest.token = token;

We need to send the request and get a response back. Note that the header defines the response class as a VEGetMapURIResponse.

VEGetMapURIResponse *mapResponse = [imageryService getMapURI:mapRequest];

The VEGetMapURIResponse class doesn’t vend it’s results as individual result classes. Instead we can query it directly for a url of the resulting map. We’ll go ahead and tell NSWorkspace to open the URL, which should cause it to appear in your web browser of choice.

[[NSWorkspace sharedWorkspace] openURL:mapResponse.mapURL];

And that’s it! Pretty painless, eh?

The framework is a work in progress. Virtual Earth provides four services: geocoding, imagery, route guidance, and yellow pages lookup. VirtualEarthKit current provides geocoding and imagery, with route guidance and yellow pages lookup coming. We’re also working on including native map views. The NMobile program we worked on with Njection.com currently implements a native map view on the iPhone in OpenGL. We’re just cleaning that up for release.

The API can probably be made nicer by adding better init functions that could shorten this code, but in it’s current form it’s a very powerful API and it makes interacting with Virtual Earth much simpler for the Mac programmer.

Here is a link to the finished code:

http://consonancesw.com/blog/images/LiveEarthApp.zip