On last January I started playing around with the Google Maps API that is especially intended to instigate the coding skills of the developers around the world. At that time I created a simple page to host a map that showed the directions from a start city to a destination city. Then I did other test in which I used Microsoft Visual C# 2008 Express to retrieve and parse the XML data generated by a Google Map search query. I was curious about how I could send a search to Google Map webservice and as a result get back the structured data to be consumed by some application. I just wanted to explore and see how it worked. At that time I set plans to blog about the Google Map functionally and so today I'm doing just that.
As the title states, I'm going to list here the steps necessary to add a Google Map on a web page and I will comment about the drawbacks I had to overcome to get it functioning the way I wanted.
The map I'll show has different markers. When one of these markers is clicked an info windows is opened to display some useful information. For a real example look at the map I place here on this blog. It's on the sidebar. As you can see the map starts in a hybrid fashion, that is, it shows normal and satellite views. The zoom level is adjusted based on the bounds of the existing markers. I'll detail what is necessary to do to get a map just like the one you see on this blog so that you can make your own.
The programming language used to construct the map is basically JavaScript. It's a good idea to check the Google Maps API documentation in order to get acquainted with the object types used when coding the map. For more information regarding a specific map object, refer to the documentation.
The steps I followed to get a functional map were:
- Obtain a Google Maps API key at the Sign Up for the Google Maps API form
The Google Maps API lets you embed Google Maps in your own web pages. A single Maps API key is valid for a single "directory" or domain. At the end of the sign up form just enter your domain name and you'll be given a key. Without this key your maps won't function. - Implement the map code
The following is the code I used to build the map:
<!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" xmlns:v="urn:schemas-microsoft-com:vml">
<head>
<meta http-equiv="content-type" content="text/html; charset=utf-8"/>
<title>Leniel Macaferi's blog - Places I cite on this blog - Google Maps JavaScript API Example: Asynchronous Data Retrieval</title>
<script src="http://maps.google.com/maps?file=api&v=2&key=YourKey" type="text/javascript"></script>
<script type="text/javascript">
function initialize()
{
if(GBrowserIsCompatible())
{
<!-- Create a base icon for all of our markers that specifies the shadow, icon dimensions, etc. -->
var baseIcon = new GIcon();
baseIcon.shadow = "http://www.google.com/mapfiles/shadow50.png";
baseIcon.iconSize = new GSize(20, 34);
baseIcon.shadowSize = new GSize(37, 34);
baseIcon.iconAnchor = new GPoint(9, 34);
baseIcon.infoWindowAnchor = new GPoint(9, 2);
baseIcon.infoShadowAnchor = new GPoint(18, 25);
<!-- Creates a marker whose info window displays the letter corresponding to the given index. -->
function createMarker(point, index, tooltip, html)
{
<!-- Create a lettered icon for this point using our icon class -->
var letter = String.fromCharCode("A".charCodeAt(0) + index);
var letteredIcon = new GIcon(baseIcon);
letteredIcon.image = "http://www.google.com/mapfiles/marker" + letter + ".png";
<!-- Set up our GMarkerOptions object -->
markerOptions = { icon:letteredIcon, title:tooltip};
var marker = new GMarker(point, markerOptions);
GEvent.addListener(marker, "click", function()
{
marker.openInfoWindowHtml(html);
});
return marker;
}
<!-- Creating the map and setting its essential properties -->
var map = new GMap2(document.getElementById("map_canvas"));
map.setCenter(new GLatLng(0,0),0);
map.setMapType(G_HYBRID_MAP);
map.addControl(new GLargeMapControl());
map.addControl(new GMapTypeControl());
var bounds = new GLatLngBounds();
<!-- Download the data in data.xml and load it on the map. The format we expect is:
<markers>
<marker lat="37.441" lng="-122.141" tooltip="Tooltip" html="HTML Code" />
<marker lat="37.322" lng="-121.213" tooltip="Tooltip" html="HTML Code" />
</markers> -->
GDownloadUrl("googlemap.xml", function(data)
{
var xml = GXml.parse(data);
var markers = xml.documentElement.getElementsByTagName("marker");
for(var i = 0; i < markers.length; i++)
{
var latlng = new GLatLng(parseFloat(markers[i].getAttribute("lat")), parseFloat(markers[i].getAttribute("lng")));
var tooltip = markers[i].getAttribute("tooltip");
var html = markers[i].getAttribute("html");
map.addOverlay(createMarker(latlng, i, tooltip, html));
bounds.extend(latlng);
}
map.setZoom(map.getBoundsZoomLevel(bounds));
map.setCenter(bounds.getCenter());
});
}
}
</script>
</head>
<body onload="initialize()" onunload="GUnload()" style="width:265px; height:300px; margin:0px; padding:0px;">
<div id="map_canvas" style="float:left; width:265px; height:300px; margin:0px; padding:0px;"></div>
</body>
</html>
Let's see the first java script tag right beneath the title tag
<script src="http://maps.google.com/maps?file=api&v=2&key=YourKey" type="text/javascript"></script>
Note the YourKey value. Substitute this value with you own Google Maps API key. The JavaScript function initialize() is called when the page hosting the map is loaded. Look at the body tag:
<body onload="initialize()" ...
The initialize function firstly checks if the client browser is compatible with Google Maps with the
GBrowserIsCompatible function:
if(GBrowserIsCompatible())
{
...
}
If this is the case, it's possible to go ahead and start the map construction. I won't comment the code I
reuse. I'll just pass by it and brief explain what it does. Expect me explaining the other parts for sure. See the following lines:
<!-- Create a base icon for all of our markers that specifies the shadow, icon dimensions, etc. -->
var baseIcon = new GIcon();
baseIcon.shadow = "http://www.google.com/mapfiles/shadow50.png";
baseIcon.iconSize = new GSize(20, 34);
baseIcon.shadowSize = new GSize(37, 34);
baseIcon.iconAnchor = new GPoint(9, 34);
baseIcon.infoWindowAnchor = new GPoint(9, 2);
baseIcon.infoShadowAnchor = new GPoint(18, 25);
The above lines of code are defining a standard icon that'll be used to construct the markers on map.
The function createMarker does a really beautiful work. See it bellow:
<!-- Creates a marker whose info window displays the letter corresponding
to the given index. -->
function createMarker(point, index, tooltip, html)
{
<!-- Create a lettered icon for this point using our icon class -->
var letter = String.fromCharCode("A".charCodeAt(0) + index);
var letteredIcon = new GIcon(baseIcon);
letteredIcon.image = "http://www.google.com/mapfiles/marker" + letter + ".png";
<!-- Set up our GMarkerOptions object -->
markerOptions = { icon:letteredIcon, title:tooltip};
var marker = new GMarker(point, markerOptions);
GEvent.addListener(marker, "click", function()
{
marker.openInfoWindowHtml(html);
});
return marker;
}
What does it do? I receives a point, more specifically a
GPoint, and index, a tooltip, and a html code. It then creates a
GIcon using Google's letter images for each marker, based on its index. The markerOptions variable has a type of
GMarkerOptions and stores the attributes that has do with the icon properties as for example the title that receives the tooltip parameter value. For each maker it's set up an event handler for the click event. When the marker is clicked its
openInfoWindowHtml method is called with the html content passed as a parameter. The
createMarker function then returns the new created marker that will be added to the map overlay.
What follows is the instantiation of the map:
var map = new GMap2(document.getElementById("map_canvas"));
A new object of type
GMap2 is created. This object is instantiated in order to create a map. This is the central class in the API. Everything else is auxiliary. The object
constructor accepts as
argument an HTML container, which is typically a
DIV element. In this case the id of the DIV element I use is
map_canvas. If you look at the div tag that is inside the body tag you'll see the
map_canvas id applied to the div.
<div id="map_canvas" ...
Next we center the map with zero values. I'll explain later why I do so. Then the map type is set:
map.setCenter(new GLatLng(0,0),0);
map.setMapType(G_HYBRID_MAP);
The function
setMapType can accept the following list of values:
G_NORMAL_MAP- the default view G_SATELLITE_MAP - showing Google Earth satellite images G_HYBRID_MAP - showing a mixture of normal and satellite views G_DEFAULT_MAP_TYPES - an array of these three types, useful for iterative processing
The next line of code uses a
GSmallMapControl object to add to the map a control with buttons to pan in four directions, and zoom in and zoom out, and a zoom slider:
map.addControl(new GSmallMapControl());
The last line of code to mount the basic map framework uses a
GMapTypeControl object to add a standard map type control for selecting and switching between supported map types via buttons:
map.addControl(new GMapTypeControl());
This line of code has to do with the zoom that will be applied to the map. A variable called bound is declared and its type is
GLatLngBounds. It will be used afterwards to set the zoom level of the map. This variable represents a rectangle in geographical coordinates, including one that crosses the 180 degrees meridian:
var bounds = new GLatLngBounds();
After constructing the framework it's time to populate the map with the desired data. That's the exciting part. Let's get to it.
As the green commentary lines state there's a predefined data format to structure the bits relative to the markers (GMarker class) that will be shown on the map. In this post I'm using a XML file called googlemap.xml to store the markers' data. The data is composed of lat (latitude), lng (longitute), tooltip (title of the marker) and html (any text). What is really cool is that you can format the text inside the html value using HTML and CSS. The text will be displayed inside the marker's info window. Altough I don't use formating in my XML file you're being infored that this is possible. Bellow is the content of the file:
<markers>
<!-- Don't use copy and paste on this XML file, use "View Source" or "Save As"
What the browser displays is *interpreted* XML, not XML source. -->
<marker lat="-22.522778" lng="-44.103889" tooltip="Hello World!" html='Hello World!"/>
<marker lat="-23.209862" lng="-45.876168" tooltip="Jesus Message" html="I'm the way, the truth and the life. John 14:6" />
</markers>
To consume this data we must make a call to the
GDownloadUrl function. This function provides a convenient way to asynchronously retrieve a resource identified by a URL. Notice that, since the
XmlHttpRequest object is used to execute the request, it is subject to the same-origin restriction of
cross-site scripting, i.e. the URL must refer to the same server as the URL of the current document that executes this code. This is known as the
Same Origin Policy. Therefore, it is usually redundant to use an absolute URL for the
url argument, and it is better to use an absolute or relative path only.
This explanation is really important. While implementing the map you see on the sidebar of this blog I tried to store the googlemap.xml file on a domain different from the one of this blog, that is, I placed the XML data file on leniel.googlepages.com and was trying to consume its content at lenielmacaferi.blogspot.com. It's not possible because of cross-domain scripting limitations. It's a security issue! So what I did? I thought about other way of implementing it. I created the map host page at leniel.googlepages.com and used an IFrame to show the page on the sidebar of this blog. Simple, isn't it? Doing so, there's no security issue since I'm running the above JavaScript and consuming the XML data on the same domain leniel.googlepages.com. An inconvenience if I can call it this way is that I had to get another Google Maps API key to use on the other domain. It's not a inconvenience at all! :)
That said, let's move on.
The GDownloadUrl function has the following signature:
GDownloadUrl(url, onload, postBody?, postContentType?)
As you can see I'm using just two of the
parameters above when I call the function in the code:
GDownloadUrl("googlemap.xml", function(data)
{
...
});
It then retrieves the resource from the given URL and calls the
onload function, in this case
function with the text of the document as first argument.
Now what must be done is the parsing operation. We need to read each line of the markers' XML file and extract its individual components such as lat, lng, html and tooltip. To that end we declare a variable named xml that will store the GXml parsed content. Note the use of the parse static method that consumes the data we got from the googlemap.xml:
var xml = GXml.parse(data);
After parsing it's now created a variable named markers that will store the individual nodes (markers) of the XML file:
var markers = xml.documentElement.getElementsByTagName("marker");
As you can see the getElementByTagName function gets the marker elements from the XML file. Each marker has this form:
<marker lat="-23.209862" lng="-45.876168" tooltip="Jesus Message" html="I'm the way, the truth and the life. John 14:6" />
In the next step an iteration takes place over the collection of markers with a for loop:
for(var i = 0; i < markers.length; i++)
{
...
}
The next instruction instantiates a new object of type
GLatLng so that we can get the
lat and
lng values of each marker and store the same in the
latlng variable:
var latlng = new GLatLng(parseFloat(markers[i].getAttribute("lat")), parseFloat(markers[i].getAttribute("lng")));
It's time to retrieve the html code and tooltip values that will be shown on each mark. To that end are the following to lines:
var html = markers[i].getAttribute("html");
var tooltip = markers[i].getAttribute("tooltip");
A
GMarker marks a position on the map. It implements the
GOverlay interface and thus is added to the map using the
GMap2.addOverlay() method. Each marker is created using its respective lat and lng values along with other relevant data you want as is the case of the following line of code. This is without doubt the trickiest part of the code :). I mean, after we call the
createMarker function defined and explained above:
map.addOverlay(createMarker(latlng, i, tooltip, html));
For the purpose of setting a nice zoom on the map I use the
bounds variable:
bounds.extend(latlng);
This variable is extended in conformity with the largest latitude and longitude. The above line is the last one pertaining to the loop and now we're almost done. We have two more lines of code to go through to finalize the map construction:
map.setZoom(map.getBoundsZoomLevel(bounds));
map.setCenter(bounds.getCenter());
The first line sets the zoom using the
bounds variable and the second one center the focus on the map using the
getCenter method from the
bounds variable. That's it. The map is ready!
You can see this map running at this URL: http://leniel.googlepages.com/googlemap.html
Final notes
Pay close attention to the written code. If you change a letter in the name of a variable for example, your code won't function and you'll probably not see the map.
If loading the information from XML as is the case of this post, replace '<' and '>' characters with < and >. For example: <img src="image.jpg" width=150 height=100>
There are plenty of excellent material about the Google Maps API on the internet and the possibilities are uncountable. Just let your imagination flow and build amazing, astonishing maps that fit your will.
References
The code I present on this post is a mix from a variety of sources and some of them are listed bellow. I just adapted it so that I could get the result I wanted.
The following links are great sources of information. Particularly, take a look at Mike's Little Web Page. He has a bunch of great stuff about Google Maps API.
Mike Little's Web Page
http://www.econym.demon.co.uk/
Google Maps API Tutorial
http://econym.googlepages.com/index.htm
Fitting the map to the data
http://econym.googlepages.com/basic14.htm
Links and Images, etc.
http://econym.googlepages.com/basic6.htm http://econym.googlepages.com/example_map6b.htm
Services - Google Maps API - Google Code http://code.google.com/apis/maps/documentation/services.html
Google Maps JavaScript API Example: Asynchronous Data Retrieval http://code.google.com/apis/maps/documentation/examples/xhr-requests.html
Google Maps JavaScript API Example: Custom Icon http://code.google.com/apis/maps/documentation/examples/icon-custom.html
