In usability we trust

The Google Maps API has evolved to version 3. This version is a complete rewrite and focuses primarily on speed. The new API also features new ways of using it. This article is the first in a series exploring version 3 of the Google Maps API. This first article will take a look on how to create a simple map and explain some differences from the previous version.

Background information

First of all, this is an early release of the new API and it’s still in Labs. It doesn’t contain all the features of the old API and will probably never do so since the old API is bloated with lots of helper methods for doing all sorts of things like making AJAX calls and showing log windows. Nowadays we have libraries like jQuery and Prototype and tools such as Firebug to take care of these things. Therefor these features will not be included in the new API, since it’s main focus is to be streamlined in order to be as fast as possible. Other missing features such as polygons and polylines will however probably eventually be included.

Secondly, since it’s an early release it’s still undergoing major changes. Features will be added as we go along and some changes of how to do certain things might be introduced.

That said, I think that the new API is mature enough to use and certainly to experiment with. It also contains the most common features seen in implementations on Google Maps on the Web.

Enough with the background info already! Let’s take a look of what the new API looks like.

Inserting a reference to the API

The first thing you will notice is that the API key is no longer necessary. In the previous versions the API key was inserted as a querystring into the script reference but not so anymore. This means that you don’t have to apply for a new API key for every domain you want to have a map at. It also means that the URI to the API is a lot shorter.

So the only thing you have to tell, while referencing the API, is whether your device has a sensor or not. sensor=false if you don’t have a sensor and sensor=true if you do. With a sensor is meant some way to determine your present location, like if you have a GPS in your device. This information is attached as querystring at the end of the URI.

<script type="text/javascript" src="http://maps.google.com/maps/api/js?sensor=false"></script>

Creating a map

A new namespace

In previous versions of the API there were lots of global variables, distinguishing them selfs by having a capital G in the beginning, like GMap and GLatLng. In the new API the namespace google.maps is used. So what was formerly called GLatLng is now called google.maps.LatLng. Using namespaces is good coding praxis. One should avoid cluttering the global namespace as much as possible in order to avoid collisions with other code. Read more about why in Global variables in Javascript.

So in practical terms, here’s how to create a new coordinate object the old way and how to do it the new way. The LatLng() method takes two arguments, an x and an y coordinate.

// The old way
var latlng = new GLatLng(57.8, 14.0);
// The new way
var latlng = new google.maps.LatLng(57.8, 14.0);

Object literals

The new API makes heavy use of object literals to pass arguments to it’s methods. The old API used object literals as well, but in this version they’ve taken it a step further which I think is positive. I think this is a really beautiful way of coding. It’s easy to use, easy to maintain and easy to expand. For you who doesn’t know what an object literal is, it looks like this:

var myObj = {
  id: '1',
  name: 'Whatever'
};
alert(myObj.name); // Will alert Whatever

It’s basically a fast and easy way to create a Javscript object. Some of you might also recognize it as JSON, and that’s exactly what it is. JSON stands for Javascript Object Notation and is in fact a Javascript Object.

Initializing the map

To initialize the map we need to call the constructor of the Map class. It takes two arguments the first one being a reference to a HTML elemtn where you want the map to be inserted (often <div id="map">) and the second one being an object literal (options) containing a set of properties.

This is much like how it works in the old API. The big difference is that in the old API you had to call the method setCenter() immediately after calling the constructor in order for the map to display. setCenter() told the map what location would be the center of the map and what the initial zoom level would be. In the new API this is not neccesary since both these properties are passed in the option parameter. So instead of making two calls, you now have to do only one. An approach that I think makes a lot more sense.

Before we get into the details of what properties option contains, lets have a look at what the code to create a map looks like.

// Creating a LatLng object containing the coordinate for the center of the map
var latlng = new google.maps.LatLng(57.8, 14.0);
// Creating an object literal containing the properties we want to pass to the map
var options = {
  zoom: 6,
  center: latlng,
  mapTypeId: google.maps.MapTypeId.ROADMAP
};
// Calling the constructor, thereby initializing the map
var map = new google.maps.Map(document.getElementById('map'), options);

Options

The option parameter is, as mentioned before, an object literal containing the properties we want to pass to the map object. There are three required properties that must be passed to the map on initialization. These are:

• center
  This property sets the center of the map and takes a coordinate of the type google.maps.LatLng
• zoom
  This is a number that sets the initial zoom-level of the map
• mapTypeId
  This property sets what kind of map type that would initially be used. The most common type is google.maps.MapTypeId.ROADMAP

There are of course lots of other properties that you can use when initializing the map, including which controls to display and which features to enable or disable. For a full list see the documentation.

Live example

A live demonstration of a simple map

I’ve put together a live example of how to add a Google Map v3 on a web page.

Conclusion

In conclusion I would say that the Google Maps API team has done several things right here. First of all by using a proper namespace, thereby not cluttering the global namespace. Secondly by heavy use of object literals to pass arguments. This way the API is more consistent and also easier to expand in future releases.

Please note that the API is still under development and is still undergoing changes. The way it works might change before the final release.

This is the first article in a series about the Google Maps API V3, so keep your eyes open for the next one which will explore the different properties for the map object and how you can use these to make the map behave and look differently.

This article was published on Friday, June 5th, 2009 in Articles.