Lab 9-- Working with the Google Maps API

Fall 2011, Siena College

Lab 9: Working with the Google Maps API
Due: 1:30 PM, Monday, November 28, 2011

This week's lab will introduce you to the Google Maps API, a free and fun way to get maps, just like the ones you see when you go to http://maps.google.com, into your own documents.

You may work individually or with a partner on all parts of this lab.

There are a series of questions you need to answer and turn in by email. You may wish to open an email draft or a Word document to record your answers as you go.

Google Maps API Basics

Google has made an application programmer interface (API) available to allow customized plots of data in Google Maps. An API is a set of mechanisms that allow us to create and interact with some data, in this case a Google Map. We will work this week with the JavaScript-based API, meaning we will create and modify our maps using JavaScript code.

We will start with an example that simply displays a map and allows us to navigate around using the familiar Google Maps controls. Copy this example to your folder for this week's lab. Load it into your browser and make sure you see a map.

Question 1: What is located at the center of the map that is displayed? (Hint: Zoom in without recentering the map by clicking on the "+" on the upper left of the map until you can tell what we're looking at.)

View the source of this example. Much of what you see is going to look familiar. This example was based on the one on Google's Google Maps Javascript API V3 Tutorial. Read through that page and make sure everything makes sense.

A couple more items of note:

Just like we can include style information with a link to an external CSS file to be able to use it in many documents, we can include JavaScript source from an external file by specifying a src= attribute on a <script> tag. This is done here to access all of the JavaScript code that makes up the Google Maps API.
The onload attribute of the <body> tag executes the given JavaScript function when the page first loads. This gives us a way to create the map in JavaScript code as soon as the page loads.

Now, we will make some modifications to the initialize function.

In the first line of the initialize function, we create a LatLng, which as you may guess, represents a latitude, longitude pair. This will be used to set the center of the map when it is first displayed. Latitude values are positive for north latitude, negative for south latitude. Longitude values are positive for east longitude, negative for west longitude.

Question 2: Change the coordinates to each of the following, reload the map, and indicate the landmark at that location.

40.6896 N, 74.0448 W
36.1058 N, 115.1729 W
21.2759 N, 157.8268 W
48.1492 N, 11.58749 E

Next, change the value of the zoom option on the third line of the initialize function to a few other values in the range 0-18 and reload the page after each change.

Question 3: What happens for smaller values? What happens for larger values?

Finally, change the part of the mapTypeId value that is currently set to ROADMAP to each of the other basic map types and reload after each. The other types are SATELLITE, HYBRID, and TERRAIN.

Question 4: Describe how the map appears initially for each of these alternate mapTypeId values.

All of the options we have been experimenting with are passed into the constructor for google.maps.Map. The other parameter is an HTML element that will contain the map itself. In this case, it is a <div> that is intended to take up the entire window.

One more experiment before we start adding things to our maps. Change the onload= in the <body> tag to be onclick=.

Question 5: What happens when you reload the page? What happens when you try to use the mouse to zoom or pan the map? Why?

Assuming we really do want the map to be displayed only after someone has clicked on the body of the document, we should give some indication that this is what needs to be done to get the map displayed. Add a message like "Click to create your map" to the <div> element. It will go away when the map is created (the map will replace the contents of the <div>). We also need to make sure we only load the map once. To accomplish this, we'll add a global variable just before the initialize function inside the second <script> element:

  var mapLoaded = false;

Then, in the body of the initialize function, we add two lines:

    if (mapLoaded) return;
    mapLoaded = true;

This will make sure that we remember when the map is created (by changing mapLoaded to true), and any subsequent mouse clicks will still call initialize but will not cause the map to be redrawn.

Save this version of the document as clicktoload.html. You need not link to it from your main index, but you should include it in your email submission of this lab.

Combining Maps with Other Elements

Make a copy of the second starter example in your folder for this lab. We will add some new elements to the HTML to combine the map with some other information.

The starting document has some style attributes and a new <div> before the map that gives us a place to add other HTML to the document that will be displayed above the map.

Within this <div>, create a form that displays the following:

When the button is pressed, your form should call a JavaScript function (mine is called recenter). This function will read the values from the two text inputs as a latitude and longitude pair, and if they are valid, recenter the map at that position.

Your form's two text inputs should be validated to require a value between -90 and 90 for latitude, -180 and 180 for longitude. Note that a function is provided in the starter document that will determine if a string represents a valid number in a given range. You may use any of the techniques we have seen this semester to report validation errors, so long as there is some feedback and the map does not recenter unless the inputs are valid.

Once you have validated the new latitude and longitude, you should recenter the map. We will use two steps:

Create a google.maps.LatLng to represent the position entered in the text inputs. If the contents of your text inputs are in variables newlat and newlng, you would use:
```
  var newpos = new google.maps.LatLng(newlat, newlng);
```
Call the map's setCenter method to recenter at the position:
```
  map.setCenter(newpos);
```

Question 6: One change from the first example to this one is that the variable declaration for map was moved from inside the initialize function to outside any function. Why?

Question 7: Which of the following values for latitude validate and which do not? Why?

123.33
42 40' N
-95.321
00.02100
180

The remaining task is to have the line below the inputs and button display the current center of the map's view at all time. This should happen not only when the map is recentered by our button, but whenever someone interacts with the map itself in a way that changes its center coordinates.

Here are the tools you will need to accomplish this:

You will need to be able to change the "TBD" for the current map center to different values. This means you will need to be able to access it from JavaScript. Use an appropriate HTML element, giving it an id that you can use to locate it from JavaScript, then set its innerHTML to the new coordinates.
Each time the map moves, you will need to know about it, so you can update the coordinates. This is done by adding a "listener" to the map that will call a JavaScript function every time the map's center changes:
```
   google.maps.event.addListener(map, 'center_changed', updatecenter);
```
This will call the function updatecenter each time the center of the map is changed for any reason.
You can retrieve the current center coordinates (as a LatLng) at any time from the map with
```
  map.getCenter();
```
This can then be used as appropriate - in our case we simply set this as the innerHTML of your message element.

Add a link to this document on the main index of each group member and include this document in your email submission.

Adding Overlays

There are several types of map overlays supported by the Google Maps API. These allow us to add some information about locations and routes on top of an existing map view. The overlays we will consider are markers that are placed at specific locations on the map, polylines that are lines connecting a collection of locations, and info windows that can display additional information in a popup "balloon" with text and/or images.

Start with this document.

The first item we will add is a marker. Add the following code to the bottom of your initialize function:

  var marker = new google.maps.Marker({
    position: latlng, 
    map: map, 
    title:"Siena College"
  });

Question 8: What happens when you add this code and reload the page?

Question 9: What happens when you hover your mouse over the new item that appeared on the map?

Next, add the following after the code you added in the previous step:

  var sienaInfo = '<div><h3>Siena College</h3>' +
         '<p>This is <a href="http://www.siena.edu">' +
         'Siena College</a></p></div>';

  var infowindow = new google.maps.InfoWindow({
      content: sienaInfo
  });

  google.maps.event.addListener(marker, 'click', function() {
       infowindow.open(map,marker);
    });

Then reload your page.

Question 10: What happens when you click on the marker on the map?

You have created an info window.

More Markers and Info Windows

Now, add at least two more markers with appropriate info windows, at least one of which is within a few miles of Siena. The steps to add each of these:

Create a new google.maps.LatLng with the coordinates of your marker. Your solution for the second task might prove helpful here as a means to obtain coordinates.
Create the new google.maps.Marker with this LatLng as its position and an appropriate title.
Create the contents of an appropriate info window, use that as the content of a new google.maps.InfoWindow.
Use google.maps.event.addListener to cause this info window to open when someone clicks on this marker.

For each, choose new variable names as needed for the objects you are creating.

Polylines

We will next add a path to the map connecting two of your markers. I called two of my markers latlng and latlng2, so the following adds the path:

  var path = [ latlng, latlng2 ];

  var poly = new google.maps.Polyline({
    path: path
  });

  poly.setMap(map);

Add similar code, using the names you chose for two of your markers.

Question 11: What do you see when you reload the page and zoom in near the two points you have connected?

We have some control over how this path will be rendered. Change your Polyline construction to specify some options:

  var poly = new google.maps.Polyline({
    path: path,
    strokeColor: "#800080",
    strokeOpacity: 0.4,
    strokeWeight: 6
  });

Question 12: Based on this and your own experiments with each of the three new options, describe the effect of each.

Choose values that you think make your line look nice.

Your last task is to augment this path to include some intermediate points to make it roughly follow roads between your markers.

To do this, determine the latitude, longitute coordinates of a set of at least three additional points along a reasonable driving route between your markers. For each one, create a new google.maps.LatLng and give it a name. If your intermediate points are named waypoint1, waypoint2, and waypoint3, the path definition would become:

  var path = [ latlng, waypoint1, waypoint2, waypoint3, latlng2 ];

Add a link to this document on the main index of each group member and include this document in your email submission.

Submitting Your Work

Before 1:30 PM, Monday, November 28, 2011, submit your files for grading. There are three things you need to do to complete the submission: (i) make sure your pages are uploaded properly to the class web space and are available at your URI, (ii) update your main index on the class web space to have links to the documents you have created for this lab, and (iii) email a copy of your files to me at jteresco AT siena.edu. If you worked with a partner, you need only upload to the account of one of the team members, but each team member should link to the page on his or her own main index. Make sure your pages validate properly as XHTML Strict.

Grading Sheet

This lab is worth 30 points, which are distributed as follows:

> Feature	Value	Score
Required Components
Lab questions	6
`clicktoload.html`	2
`mapbrowse.html` form and validation	2
`mapbrowse.html` map recenters correctly	2
`mapbrowse.html` map center always displayed	2
`plotroute.html` first marker	1
`plotroute.html` first info window	1
`plotroute.html` additional markers and info windows	4
`plotroute.html` basic polyline	2
`plotroute.html` polyline path between 2 markers	3
Style
XHTML document passes validation	2
Formatting of HTML text	1
Submission
Main index updated	1
Email submission	1
Total	30