Author: John O'Brien
The version 6 update of the Virtual Earth API builds on the existing API adding new functionality, new interface options and support for the Safari web browser. Critically there are no breaking changes from Version 5. So for your application to take advantage of these new features it may just be a matter of changing the version number to 6.
The Correct URL
First up there has been confusion over the correct URL for the API. The correct way to reference Version 6 is:
The new interface
On first glance you will immediately notice the new dashboard control and scale bar. Although the other optional sizes have remained the same (tiny and small) the normal dashboard is now identical to that on maps.live.com. I have spotted one difference though, the API for “road” uses the plain road tiles while maps.live.com uses the newer “hill shaded” style. Fortunately this is now available to developers as a map style:
New Zooming Option
Another interesting interactive option is to change from the default scroll wheel zooming on the centre of the screen to zoom on the mouse location – ala google maps. It is enabled with one line of code:
Check out a demo here.
Birdseye in 3D
While on the subject of birdseye two new methods have crept in to solve some outstanding issues. The first is:
This returns oversized, approximate, bounds for the current birdseye view. For developers that load there data on demand for what is current visible this is a much welcomed addition and makes the many hacks and breaches of licensing redundant. A big thank you to the dev team for sorting this out.
The second addition is the ability to request a Birdseye view based on Latitude, Longitude and Zoomlevel:
VEMap.SetBirdseyeScene(veLatLong, orientation, zoomLevel,
For areas that support it developers can now add traffic flow overlays really simply. You just add the line:
See a demo here
The API does note:
All use of traffic data is restricted to customers who have received explicit permission and instructions about traffic from Microsoft. For more information on terms for use of traffic, contact the Microsoft Virtual Earth Licensing Team
The map.Find() method has had some improvements also. The VEPlace class now contains:
- VEPlace.LatLong Property
Gets a VELatLong Class object that represents the location of the found result.
- VEPlace.Name Property
Gets the String object that represents Virtual Earth's unambiguous name for the location.
- VEPlace.MatchCode Property
A VEMatchCode Enumeration value specifying the match code from the geocoder.
- VEPlace.MatchConfidence Property
A VEMatchConfidence Enumeration value specifying the match confidence from the geocoder.
VEMatchCode has 5 levels:
- None - No match was found
- Good - The match was good
- Ambiguous - The match was ambiguous
- UpHierarchy - The match was found by a broader search
- Modified - The match was found, but to a modified place
VEMatchConfidence has 3:
- High - The confidence of a match is high
- Medium - The confidence of a match is medium
- Low - The confidence of a match is low
Finally the by far most requested feature has been implemented. Routing has now been overhauled to allow much more control. See a simple demo here. It deserves an entire article but to summarise you now pass an array of locations along with some options:
locations = new Array("Tacoma WA", "Seattle
WA", "Everett WA");
The options include:
- KM or Miles
- Draw the route
- The callback function
- Route Line colour
- RouteOptimisation – logic that plans the best order to visit the locations, vey cool.
- The Line weight (thinkness)
- Line Zindex
- Set the map to fit the route
- Show Disambiguation dialog
- Show error messages.
The function’s callback gets a rich set of information contained in the VERoute class. This has the total distance but also each segment has a distance and array of latlong, shape and text. Look out for a more detailed look at this soon.
In Version 5 we saw pushpins, polylines and polygons become a more generic “shape”. In version 6 these shapes now get more goodies. First off we get methods for Zindex allow complete control over what is on top and below including the polyline/polygon separate from its pushpin:
Secondly we can now set altitude for 3D mode. This was undocumented in V5 and a little confusing, well they have sorted it out, you now set the altitude in meters and choose how that distance is applied through a mode:
- Default - The altitude is meters above ground level
- Absolute - The altitude is meters above the WGS 84 ellipsoid
- RelativeToGround - The altitude is meters above ground level
Additionally you can also draw a line from the shape to the ground, again it is a simple property:
This allows you to do some very cool 3D things:
The other major addition to Shapes surrounds accuracy and performance. Several new features have been introduced to help in this area. First up have the ability to set a maximum and minimum zoom level for shapes:
Note: If the minimum and maximum zoom levels are equal, the shape is never visible.
Next up the AddShape method now accepts an array of shape objects.
Performance demo here
This allows us to bulk load shapes. What is the difference? This demo is a little inaccurate but repeating the test over and over clearly shows a large performance gain. On my laptop the difference is 3.8s to load 1000 pins separately versus 1.1s using the bulk method. Feel free to view source and play more, interestingly if the shapes are not in the current map view, pan away from Africa in the demo, the old method takes 0.5s while the bulk method still takes 1.1s.
Simply pass an array of shapes for great performance gains.
Lastly we can configure the shape accuracy for use in Birdseye mode. The documentation states:
When switching between aerial and birdseye views, pushpin accuracy is maintained, delivering a more seamless experience.
As usual it’s pretty simple and straight forward to configure, we have two settings, first:
The policy is a new class VEShapeAccuracy that can be set to:
- None - No shapes are accurately converted (default)
- Pushpin - Only pushpins are accurately converted
- All - All shapes are accurately converted
Secondly we can set a limit to how many will be accurately plotted.
The default value is 50.
I’m very impressed with this release of Virtual Earth, many of new features I know have been asked for directly by customers and to integrate them into this release while not breaking version 5 code is very well done. Big congratulations to the VE team.
Of course there are some new features missing from what was unveiled on maps.live.com. Notably we see no new methods for 3D tours or recording, previous attempts trying to build 3D tours in Virtual Earth have been very stop start, a smooth experience was not achievable. We also see no mention of custom 3D models. There is a new method on shapes, VEShape.IsModel(), but no mention of how to add custom models.
I hope this article has highlighted the changes in Version 6 and will allow you to make the painless upgrade and start using the features today.