Maps are becoming ubiquitous in web applications. They are being used as an effective and non-intrusive way of gathering geo-specific data from the user or to present geo-specific information to the user including tracking report of shipments et al. However even two years ago, embedding a map within an application was considered a specialized area requiring good understanding of Geographical Information System or GIS. But the arrival of Google Maps and its corresponding set of APIs, incidentally known as Google Map API, have changed the scenario. Now a developer having a good grasp on JavaScript, can without much ado embed an interactive map in a web-application using Google Map API. The questions that arise next is what exactly is Google Map API and what are the steps to be followed in using Google Map API. The answer to these questions is the focus of this discussion. The first section would deal with the whys and wherefores of Google Map API. In the second section I would detail the steps to use Google Map API. The last section would focus on a real world example based on the steps discussed in second section. That is the outline of the discussion.
Google Map API – What is it:
Google Map provides not only the map, satellite image or a hybrid of both but also an extensive range of operations on the map such as zooming, panning, information pop-ups, overlays etc. Google Map API provides interface into these operation through JavaScript objects. The beauty of the setup is that the functionalities work in the same non-intrusive way as the original Google Maps without developer needing to know the details of AJAX or how it is implemented in Google Maps. The developer has to just know the classes and their methods to access the services of Google Maps. The functionalities exposed by the Google Map API can be categorized as follows:
1. Configuration
2. Controls
3. Map Types
4. Map State
5. Overlays
6. Information Window
7. Map Navigation
8. Events
The accesses to most of the group of functionalities mentioned above are through the methods of GMap2 class. GMap2 class forms the basis of map creation, display and manipulation.
1. Configuration:
All the aspects of any map provided by Google Maps are configurable -be it the enabling of dragging and information windows or continuous zooming. The methods of GMap2 class sectioned under configuration enables configuration of the map. Following are the most oft used methods for configuring maps:
i. enableDragging() – enables the dragging of map. Dragging is enabled by
default.
ii. disableDragging() – disables the dragging of map.
iii. enableInfoWindow() – enables the information window
iv. disableInfoWindow() – disables the displaying of information window.
2. Controls:
The UI elements using which user controls the map and its functionalities come under controls category. There are two main methods related to controls which are:
i. addControl(control, [position]) – adds the specified control to the map at the
place specified by position parent. The position
parameter is optional.
ii. removeControl(control) – removes the specified control from the map.
Both the above functions takes instance of GControl class. There are four existing instances of GControl class – GSmallMapControl, GLargeMapControl, GSmallZoomControl, GScaleControl and GMapTypeControl. These can be passed to the addControl() method to add controls to the map.
3. Map Types:
Google Maps provide three types of map – simple map that provides outline based map, satellite map that streams the satellite imaged maps and hybrid map which is a combination of both aforementioned maps. The map types provided by Google Maps is controlled by the following methods:
i. setMapType(type) – sets the type of map to be displayed.
ii. removeMapType(type)- removes a already set map type.
The type parameter is specified using the constants provided by GMapType class. It can be G_NORMAL_MAP, G_SATELLITE_MAP, G_HYBRID_MAP corresponding to maps of type simple, satellite image based or combination of both.
4. Map State:
The methods that provide information about the state of the map comes under it. The information provided by map state methods include whether the map is loaded or not, the current focus point or center of the map etc. The commonly used methods are:
i. isLoaded() – it tells whether the map is loaded on to client browser or not
ii. getCenter() – this method provides the latitude and longitude of the center of
current viewport of the map.
5. Overlays:
By definition “A map overlay refers to a point or polyline that is added on top of the Google Map”. In essence an overlay means a point or line that is placed on the map to distinguish it from rest of the map. Mostly used methods in this category are:
i. addOverlay(overlay) – it adds an overlay presented by the overlay object
passed as parameter.
ii. removeOverlay(overlay) – it removes an overlay already added and
represented by the overlay object passed as
parameter.
The overlay object can be of type GPoint or GPolyline.
6. Information Window:
When an overlay is clicked, a window containing detailed information can be displayed. It is called the Information window or info window in short. Following are the main methods to control an info window:
i. openInfoWindow(latlng,dom,[opts]) – opens an information window at the
point specified by latlang and with the
data specified as dom which is a DOM
node.
ii. showMapBlowup(latlng,[opts]) – opens a info window at the specified as
specified latlng containing the close-up view of
the latlng specified as parameter.
The parameter latlng is of the type GLatLng.
7. Map Navigation:
The navigation of map can be controlled using the methods provided under this category. The commonly used methods are:
i. setCenter(center,[zoom],[type]) – loads the map with focus on the point
specified by center with an optional level of
zoom and type of the map.
ii. panTo(center) – it navigates to the point on the map specified by center.
iii. setZoom(level) – it zooms into or magnifies the current center to the level
specified with the parameter level.
8. Events:
Google Map API provide methods to intercept any event taking placing on the map. The common events supported by Google Map API are:
i. click – it is generated when user clicks on any point within the boundaries of the
map.
ii. move – it is fired when the map is moving or panning. During the panning it
may be fired many times.
iii. moveend – it is fired when the panning is completed.
That brings us to the end of first section. In the next section I would detail the steps required to work with Google Map API.
Using Google Map API – Step By Step:
Now that the services provided by Google Map API have been discussed, lets see the steps to use the API. To use Google Map API, two main steps have to be followed:
1. Acquiring the Registration Key
2. Setting-up the map
The second step again consists of sub-steps that actually deals with the setting up of HTML and Google Map API library.
1. Acquiring the Registration Key:
It is through the registration key that one can access the API. A key can be used within a web directory i.e. files within that directory and its subdirectories can make use of the key. To get the key, go to the site and provide the URL of the site for which the key has to be generated. The key alongwith an example would be provided which can be used as base for further developments.
2. Setting-up the map:
The Google Map API library is a JavaScript library. So its focus would be HTML and JavaScript based applications. In other words, Google Map API targets the UI for the web-applications. To set-up the page to display map the required steps can be enumerated as follows:
i. Set-up the HTML page:
The first step in displaying the map is by providing the required placeholder within the page where the map has to be shown. To do this <div> tag has to be used. It creates a logical block for the map to be displayed. For example following statement creates a placeholder named ‘map’:
<div id=”map” style=”width: 500px; height: 500px”></div>
ii. Importing/Including the Google Map API:
To use the API, its library has to be referenced. In case of JavaScript importing or including of the library (other terms for referencing a library) is done using the src attribute of <script> tag. So to include Google Map API library, the src of the <script> tag would be as follows:
<script src=”http://maps.google.com/maps?file=api&v=2&key=[yourkey]“
type=”text/javascript”></script>
The value of src attribute tells us two important points about Google Map API. First is the location of the API which is the Google’s site itself. So even for testing purpose, availability of internet is required. Second the is usage of the key provided after registration. The key is passed along with the URL in the src to tell Google that the site trying to access the API library is authorized site. Next step is to implement a function that would be called when the document is loaded. That is done by calling a function in the <body> tag’s onload handler. the statements would be :
<script type=”text/javascript”>
//<![CDATA[
function load() {
}
//]]>
</script>
For defining the function and it would be called from the body thus:
<body onload=”load()” >
:
:
</body>
The first step in implementation of logic within the function is to check whether the client browser is capable of displaying map or not. That can be done using GBrowserIsCompatible(). It return a Boolean value specifying whether the browser is capable of displaying map or not. The code block using it would be thus:
if (GBrowserIsCompatible()) {
//…
}
To display the map what we need is an object of GMap2 class. To get it, GMap2 constructor with the id of the <div> serving as placeholder, is required. For example the following code creates an instance of GMap2 class and assigns it to the variable named map:
var map = new GMap2(document.getElementById(“map”));
The last step in displaying the map is to set its focus on a particular point. That can be accomplished by calling the setCenter() method on map variable. The argument passed is of type GLatLng which, in turn accepts latitude and longitude as its parameter. The following sets the focus on the point defined by latitude 31.122027 and longitude 77.111664:
map.setCenter(new GLatLng(31.122027, 77.111664), 13);
The map object can be used to manipulate map by using the methods enumerated in first section. The last but not least point is to call GUnload() through onunload handler of body tag to prevent memory leak:
<body onload=”load()” onunload=”GUnload()”>
:
</body>
That brings us to the end of the second section. In the next section I would develop a small application that would show the different functionalities discussed in first section using the steps detailed in this section.
Google Map API – In Real World:
Now I will be building a small application that displays map using Google Map API. It does the following:
1. Display the map with Shimla (India) as its center.
2. Provide zoom and pan controls for navigation.
3. Provide map type control to change between the three map types
4. Handle the click event and display information window showing the current focus
point on click upon the map.
So lets get going. First the HTML setup:
<!DOCTYPE html PUBLIC “-//W3C//DTD XHTML 1.0 Strict//EN” “http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd”>
<html xmlns=”http://www.w3.org/1999/xhtml”>
<head>
</head>
<body onload=”load()” onunload=”GUnload()”>
<div id=”map” style=”width: 500px; height: 500px”></div>
</body>
</html>
The onload handler calls the load function which is as follows:
<!DOCTYPE html PUBLIC “-//W3C//DTD XHTML 1.0 Strict//EN” “http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd”>
<html xmlns=”http://www.w3.org/1999/xhtml”>
<head>
<script src=”http://maps.google.com/maps?file=api&v=2&key=[yourkey]“
type=”text/javascript”></script>
<script type=”text/javascript”>
//<![CDATA[
function load() {
}
</head>
<body onload="load()" onunload="GUnload()">
<div id="map" style="width: 500px; height: 500px"></div>
</body>
</html>
Place the key you received in place of [yourkey]. This sets up the link to Google Map API and declares the load function. Next comes the creating the map instance and setting the center.
<!DOCTYPE html PUBLIC “-//W3C//DTD XHTML 1.0 Strict//EN” “http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd”>
<html xmlns=”http://www.w3.org/1999/xhtml”>
<head>
<script src=”http://maps.google.com/maps?file=api&v=2&key=[yourkey]“
type=”text/javascript”></script>
<script type=”text/javascript”>
//<![CDATA[
function load() {
if (GBrowserIsCompatible()) {
var map = new GMap2(document.getElementById("map"));
map.setCenter(new GLatLng(31.122027, 77.111664), 13);
}
}
</head>
<body onload="load()" onunload="GUnload()">
<div id="map" style="width: 500px; height: 500px"></div>
</body>
</html>
Next lets add the controls:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<script src="http://maps.google.com/maps?file=api&v=2&key=[yourkey]“
type=”text/javascript”></script>
<script type=”text/javascript”>
//<![CDATA[
function load() {
if (GBrowserIsCompatible()) {
var map = new GMap2(document.getElementById("map"));
map.addControl(new GSmallMapControl());
map.addControl(new GMapTypeControl());
map.addControl(new GScaleControl());
map.setCenter(new GLatLng(31.122027, 77.111664), 13);
}
}
</head>
<body onload="load()" onunload="GUnload()">
<div id="map" style="width: 500px; height: 500px"></div>
</body>
</html>
The controls have to be added before setting the center. The last part is to handle the click event and show the current focus point on a information window:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<script src="http://maps.google.com/maps?file=api&v=2&key=[yourkey]“
type=”text/javascript”></script>
<script type=”text/javascript”>
//<
