Tuesday, June 16, 2009

How low can you go? Introducing getMaxZoomAtLatLng

When you're showing satellite imagery with our Maps API, it's often the case that you want to show the most detailed imagery available. But it's always been tricky figuring out the best zoom level for a particular location. If you don't zoom in far enough, your users won't immediately get the most detailed image available. If you zoom in too far, you might get the dreaded message "We are sorry, but we don't have imagery at this zoom level for this region", and no imagery at all.

What if there were a way to know programatically what the maximum zoom level was for any point in the world? Fortunately, now there is.

It's not easy to solve this problem naively; the world is a big place. At zoom level 22, there are 4 to the power of 22 potential satellite tiles -that's over 17.5 trillion. The zoom level for satellite imagery that exists varies wildly all over the world. Sydney's Bondi Beach has imagery right up to zoom level 22, whereas the centre of the Pacific Ocean only goes up to zoom level 9. (I make no accusations about whether this means the Google Maps team prefers to look at tanned, sunbathing Aussies).

But with a good search algorithm, and data based on the most frequently viewed areas of the earth, we've been able to make a search for the existence of imagery very efficient, and we are now exposing this functionality to our API developers.

The new solution is an asynchronous function which is part of the GMapType class: getMaxZoomAtLatLng. The function takes a GLatLng and returns the maximum zoom level at which imagery exists. Because the function requires a call to Google's servers (much like GClientGeocoder.getLocations()), you must also provide a callback parameter, which is a function which will deal with the response.

As an example, here's a function which will set the center of the given GMap2 object to the maximum zoom level at the given GLatLng:

function setMaxZoomCenter(map, latlng) {
  map.getCurrentMapType().getMaxZoomAtLatLng(latlng, function(response) {
    if (response && response['status'] == G_GEO_SUCCESS) {
      map.setCenter(latlng, response['zoom']);

As you can see, the response object contains a status code, and, if the response was successful, a zoom field containing the maximum zoom at that point.

Click on the map below, and it will zoom to the highest zoom level available at the point at which you clicked.

Note that this function is only implemented for satellite imagery, and not roadmaps, whose zoom levels don't vary nearly as much. It works for both the G_SATELLITE_MAP and G_HYBRID_MAP map types. The full reference is available here.

We hope this function makes developing with satellite imagery a simpler, easier and fuller experience. Please provide any feedback in the Maps API Google Group.