Google Maps JavaScript API

About Google Maps JavaScript API

An Application programming interface (API) is an interface that enables a software program to interact with other software. The Google Maps APIs provide a way to embed Google Maps into Web pages with a host of customization options. There are several different APIs available from Google, but we will focus on the Google Maps JavaScript API version 3. You will notice that many of the commands required to produce a map on your Web page are written in JavaScript. Fear not—by no means do you need to become an expert in JavaScript!

Google released version 3 of the Maps JavaScript API on May 19, 2010. You may need to check the browsers that version 3 supports. A few years ago, I needed to upgrade both my browser and my version of Java to make my maps work.

Google seems to go back and forth on whether they require a Google Maps API key. In version 2, Google required you to register a free API key for your server and include the key within your HTML code. Then Google made a major change in version 3 of the JavaScript API and no longer required a key for embedded maps. On the other hand, you could use a key to track usage on your site. However, on June 11, 2018, Google made another major change and now requires a key attached to a valid billing account. Dizzying, right? Embedded maps will still show up without a key, but users will see a darkened map watermarked with the text "for development purposes only." The good news is that Google provides a credit each month and normal usage will not exceed this credit amount, so the key is effectively free. Rather than have you register for a Google Maps API key with your own billing information, I have set up a universal billing account and generated a key that you can use for your site on Blizzard.

A good starting point is for you to peruse the Maps API Developer's Guide. Start with the "Overview" and move forward from there to learn all about embedding interactive maps on your Web page. The documentation contains a wealth of example code and instructions for customizing your maps. Some of the examples that you see below are borrowed from this documentation. Remember that an API key is required, so be sure to retain the key=YOUR_API_KEY section of the script source in the example documentation and replace YOUR_API_KEY with the key that I will provide.

Your First Map

Google makes it very easy to create and then customize a map. First view my simple example. Do you recognize this place? Copy the source code (in Firefox and Chrome, use CTRL+U) and paste it into your very own firstmap.html on Blizzard and play with some of the options. It's somewhat obvious where you can change the latitude and longitude coordinates of the center of your map. The rest of the options are explained in Google's tutorial. Please copy my API key for your own maps. To prevent anyone from stealing my key and sticking me with the bill, note that I have set up a restriction so that this key only works on the department's servers, including Blizzard. I have also set up a quota so that we never reach the threshold of usage that would trigger billing. You are not likely to reach the limit, so don't hesitate to reload your maps as necessary.

Map Controls

You can use the default user interface elements on your map without doing anything special. These elements include the navigation tools (pan and zoom) and the map type (e.g., satellite). By adding a few lines of JavaScript, you can modify these controls, add a scale, and move everything around as you please. Follow these detailed directions for modifying the controls on your map and customizing your user interface.

Map Overlays

To see how overlays may be added, removed, and customized, read about Overlays. For the task below, you will draw markers with custom icons and create info windows, so pay particular attention to these types of overlays. Also note that it's relatively simple to draw filled polygons, so you could draw severe thunderstorm and tornado watch boxes and warning polygons on your maps like this!

SPC Storm Reports

You have probably seen the tiny dots indicating tornado, hail, and severe wind observations on the maps showing the storm reports from the Storm Prediction Center. Unfortunately, it's sometimes difficult to see exactly where the dots are or which reports correspond with which dots. Wouldn't it be nice to place these reports on a Google map? It turns out that the SPC has in fact made this possible via ESRI maps since I first wrote this tutorial, but the concepts involved in creating these maps have wide-ranging applications.

Your task is to reproduce and (hopefully) improve upon my example of storm reports for the event on April 27, 2011. Here, I have used custom markers to create different colored markers, including shadows (well, the code is there, but note that marker shadows were removed in version 3.14 of the Google Maps JavaScript API), for each type of storm report. Hovering over each marker shows a label with the text of the comments section of the storm report. Clicking on each marker opens an info window showing the entire contents of the storm report at that location. Notice how each info window is formatted with bold headings and that hail sizes and wind speeds have appropriate units. At the top of the page, there are buttons that will remove each type of storm report and there is one button that puts them all back on the map. Reproducing each of these elements on your own map will satisfactorily complete this task. Before you begin, please read the sections below for key information that will help you accomplish this goal.

Important Information and Tips

JavaScript in this context is not particularly helpful as far as error messages. If you happen to have a syntax error in your code, your map won't appear. It's common to forget to include the semicolon at the end of each line in your code. I recommend editing your JavaScript in very small increments and checking to make sure that your map still appears. That way you can at least narrow down the problem if something breaks. The developer tools in Chrome and Firefox are especially useful. To access these in Chrome, go to the three dots at the top right > More tools > Developer tools. In Firefox, go to the three lines at the top right > Web Developer > Toggle Tools. Experiment a bit with these tools.

I recommend using an external JavaScript file to simplify your HTML code and make it more readable. Most professional Web developers take this approach. Place the following in your HTML <head> section, along with any other HTML in that section: <head>
  <script type="text/javascript" src="your_javascript.js"></script>
</head> Now you can edit your_javascript.js as a separate file that is independent of your HTML source code and contains only the JavaScript for your map. This may come in handy if you choose to use my Python script to create the markers for your storm reports (see below).

You will find a very helpful example for drawing custom markers at this site. Copy and modify this example, using the following tips as a guide. You can use my red, green, and blue markers and this shadow image (which won't do you much good). Use your browser to view the properties of each image to obtain the pixel dimensions. You will need these in order to make the marker images look reasonable via the JavaScript in this example.

You may find, as I did, that the text in your info windows is centered instead of aligned to the left. To fix this, add <p align="left"> to the beginning of your HTML code in contentString and add </p> to the end.

To make buttons that will remove or add particular storm reports, read about removing and adding overlays and copy the code from that example. As you implement the code to add and remove markers, you will need to be very careful where you put the line var markersArray = []; This line (or a similar modified set of lines defining the individual array of markers for tornado, hail, and wind reports) must go before function initialize() {

Use a Script

There were a lot of storms reports on April 27, 2011. If you don't have anything else to do with your time, then have fun manually typing the storm report information for each of the reports. If you're busy like me, then you may wish to use spcrpts.py. This Python script parses storm reports into the format required for creating markers on your map. The program reads a comma-delimited list of storm reports and writes the necessary JavaScript for making the markers. You can also expand upon the script to have it write out your entire JavaScript code for your map. Carefully read the comments throughout the Python code to accomplish this. You may also find that a few of the more complicated pieces of JavaScript are written for you. Note that you will need to download the comma-delimited (.csv) list of storm reports from the Storm Prediction Center. You will find this file under the "Full report" link at the bottom of the list of storm reports for April 27, 2011. With this approach, you can easily plot the storm reports for any event! In fact, there is a project idea for you.