Google Maps

Google Maps is a useful feature to add to many websites and it's (almost) free! Both Google and the W3Schools have nice tutorials and a number of fun examples. We won't read all of them, but a few will be helpful.

API Key

I said Google Maps was almost free. What that means is that Google generously allows you to make queries to their map servers per month for free (it's many thousands), but after that, they will bill you (and the charge is pretty low, $7 per thousand queries, I believe).

Unfortunately, all of that means that in order to use Google Maps, they need to be able to bill you, even if you're just playing around and won't be doing industrial-scale numbers of queries.

This "we need to be able to bill you if we need to" policy, while understandable, is a serious impediment for us. If you have a personal Google account, you can give them a credit card for billing purposes then create an API key and use that.

Unfortunately, the Google accounts that we have thanks to Wellesley College don't allow us to add a credit card. So, I've given my credit card to Google for my personal Google account, and created an API key for that. I can share that with you for educational purposes; just don't cost me any money. :-)

So, when you read these tutorials and they refer to the API key, understand that that is a unique identifier that tells the Maps server who is making the query, so that they can count how many queries you make and, if it gets beyond the free level, can bill you.

Google's Tutorial

First, read this one (longish) web page that is Google's tutorial on adding a Google Map with a Marker

Note that they have a fun interface to the code that divides it up into different "tabs" for

  • TypeScript
  • JavaScript
  • CSS
  • HTML
  • all

What's typescript? Typescript is JavaScript plus optional type declarations. So if you miss the type declarations of Java, TypeScript is for you. However, TypeScript isn't native to browsers, so it has to be translated into JavaScript. There are Node.js modules that do that, but we aren't going to learn yet another language and tool. You can compare the TypeScript and JavaScript tabs to see the differences.

I suggest you ignore the TypeScript code and read only the JavaScript, CSS and HTML code. Or switch to the All tab and read all the code without having to switch tabs. The All tab shows JavaScript code.

Defer and Callback

The Google code does a couple of clever things that we should learn about.

First, it loads the Google Maps API at the top of the file, instead of putting it at the bottom, as I've taught you to do:

<head>
    <title>Add Map</title>
    <script
      src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap&libraries=&v=weekly"
      defer
    ></script>
   ...
   <script>
      function initMap() { ... }
   </script>
</head>
...

Second, it adds a defer attribute to the script tag. We'll talk more about that in a moment.

Third, it adds two parameters to the URL for the script tag, namely key=YOUR_API_KEY, which we talked about above, and callback=initMap. (It adds a couple more, but we'll ignore them.)

The defer attribute tells the browser that it can keep loading the rest of the HTML page while the script is loading. That is, we are allowing the browser to do two things in parallel:

  • load the google maps library, and
  • load the rest of the page, parsing the HTML, reading and running the script element that defines the initMap function

Parallel code is always fraught, because you have to worry about dependencies and which thing finishes first. The initMap function calls functions defined in the google maps library, such as google.maps.Map.

What happens if initMap is defined before the library is loaded? Will we get an error? No, because the library calls the initMap function when it is finished loading. That's the purpose of the callback=initMap part of the URL.

Here we see yet another occurrence of the callback idea. Here we aren't handing the initMap function to another function (like we did .map in the Plotting assignment, or to .click in the Zodiac assignment). Instead, we are indirectly giving it to this library, to be invoked when the library is ready.

The parallelism here can, in principle, allow the page to load a little faster, at the cost of a bit of complexity. I decided to teach you to load your scripts at the end of the file to avoid some of these issues, but you're ready for them now.

If you'd like to learn more about defer and its companion async, see this page on script, defer and async

Tutorial

Then, if you have time, please read through the first two pages of the W3Schools tutorials (linked below). You can just start at the first one and click the big green "next" button on each page.

  1. Maps Intro This is the set up to show a nice, static map, at a place of your choosing (specifying the center given a latitude and longitude. Note that latitude measures north/south location and ranges from -90 (south pole) to +90 (north pole). Longitude measures east/west location and ranges from -180 (middle of the Pacific) to +180 (same as -180) with 0 degrees longitude being Greenwich, England.
  2. Maps Basic This is more information on the basic map, explaining about the map container (a div) and the initialization function. It also shows a demo of four different map types (ROADMAP, SATELLITE, HYBRID, and TERRAIN)