Harnessing the Google Maps JavaScript API the Right Way

Jamie Shields
Jamie Shields

This article was peer reviewed by Tim Severien, Nuria Zuazo and Mallory van Achterberg. Thanks to all of SitePoint’s peer reviewers for making SitePoint content the best it can be!

Google Maps icon

Google Maps is an online mapping service providing up-to-date road maps, business listings, directions, street-level photos and more.

There are notable alternatives to Google Maps, such as Mapbox and Open Street Map. But in my view, none of the competitors can match up to Google Maps for the sole reason of the completeness of its business directory. Google is able to present a complete and vast map equipped with up-to-date business details, thanks mainly to the crossover with their search offering.

There are various APIs for interacting with Maps, from the simple Static API to the powerful JavaScript API, which is the focus of this article.

Of course, you can place Google Maps on your site without leveraging the various APIs on offer. This makes life easier, of course, and still offers a lot of useful features. But the Maps JavaScript API gives us full control over our map for performance and customization purposes.

Harnessing the Google Maps JavaScript API

In this article, I’d like to show you how to make the most of the Maps JavaScript API — using it the right way.

There are lots of tutorials and examples already out there for this, but too often without a focus on the best way of achieving the desired result. They get things done quickly, but without a considered approach or explanation of why certain steps have been taken.

The complete source code for this article can be found on our GitHub repo.

Creating a Basic Map Canvas

The first thing we need to do is set up a simple front-end framework for building the mapping application.

Create the HTML

Let’s create an HTML file with the following markup:

<!DOCTYPE html>
<html lang="en">
    <meta charset="utf-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>Google Maps API Template</title>

    <link rel="stylesheet" href="style.css" />
    <div id="map"></div>

    <script src="script.js" defer></script>

This gives us a robust platform for building a full mapping application.

Notice how we’ve used the defer attribute for our script. This tells the browser to download the specified scripts as soon as possible, but to wait until HTML parsing has finished before executing them. It’s important to use defer whenever possible, as it will prevent the rendering of the page from halting before it’s finished in order to execute JavaScript code — providing a janky loading experience for the user. The eagle-eyed reader may notice how we haven’t included Google Maps’ JavaScript: this is deliberate, and will be explained shortly!

Build the on-ready callback

Now, let’s set up our initial JavaScript file, script.js, starting with the document.addEventListener('DOMContentLoaded', function () {}) call:

document.addEventListener('DOMContentLoaded', function () {
  if (document.querySelectorAll('#map').length > 0)
    if (document.querySelector('html').lang)
      lang = document.querySelector('html').lang;
      lang = 'en';

    var js_file = document.createElement('script');
    js_file.type = 'text/javascript';
    js_file.src = 'https://maps.googleapis.com/maps/api/js?callback=initMap&signed_in=true&language=' + lang;

The #map length check is a quick way to find out if a certain element is present on the current page. Quite often, the same external JavaScript file will be included on an entire website, and quite often some portions of code are only required for certain pages. In this instance, we only ever want to execute this code if we’re presenting a map canvas to the user. This prevents unnecessary code bloat on pages that don’t require it. (Performance matters!)

Once we’re sure we have a map canvas on the page, we may think we’re ready to proceed, but there’s one more check we should perform. By default, the Google Maps JavaScript API loads in English, regardless of what language the requesting page is in. A great way to counteract this is to set a lang variable based on the lang attribute in the <html> element. This will allow us to include the Google Maps JS in the correct language for our user. This is especially useful for multilingual (i18n) websites that include the same script.js file across all languages.

Grabbing Google’s JavaScript file

Now comes the time to load the external Google Maps JS file. The reason we’ve left it until now, rather than including it as a regular <script> tag in the HTML, is to prevent unnecessary code bloat in pages that don’t have a map canvas. To load in the file, we create a new <script> element and inject it into the <head> of the DOM. As Google’s API handles callbacks for us, we don’t need to do anything more fancy than this:

var js_file = document.createElement('script');
js_file.type = 'text/javascript';
js_file.src = 'https://maps.googleapis.com/maps/api/js?callback=initMap&signed_in=true&key=YOUR_API_KEY&language=' + lang;

There are a few interesting things to note in the query string parameters passed to the API.

Firstly, we pass our lang variable as the language parameter to instruct Google on which language we want the map to be in.

Secondly, we provide the signed_in parameter as true. This is to increase the personalization of the map (e.g. it will have your starred locations visible, amongst other things).

Next, we pass the key parameter with our API key (more on that shortly).

Finally, and most importantly, we specify our callback function using the callback parameter. This tells Google which of our functions it should trigger once the file has been fetched successfully.

Google Maps JS API will still work without a valid key parameter. However, we would be issued with a JavaScript error console warning message. So we should make sure we get ourselves a free API key by following Google’s guide.

Initializing the map canvas

Now that we’ve got our initialization function call set up, we can move on to defining our callback function initMap(). This is the function that the Google Maps JS API will trigger once it’s successfully loaded.

var map;

function initMap() {
  map = new google.maps.Map(document.getElementById('map'), {
    center: {lat: -34.397, lng: 150.644},
    zoom: 8

When creating a new Google Map, it’s best to create the variable for the map in the global scope (outside of any functions) so that it’s easier to interact with the map later. This is why we define map outside of initMap().

Now that we’ve got an empty map variable to work with, we can go ahead and assign the Google Map object to it inside the initMap function. This is exactly as Google’s Simple Map example. One important thing to note is that we must specify both a center and a zoom, or the map will not initialize at all. There is no default!

Don’t forget the CSS

One last important step to getting the initial basic map canvas to function is to provide some CSS in our style.css file:

html, body {
  height: 100%;
  margin: 0;
  padding: 0;

#map {
  height: 100%;

The most common pitfall we’ll cover today is forgetting to set a height attribute for the #canvas element. Regardless of everything else covered in this article, if there’s no height (or min-height) CSS attribute set, we won’t see a map at all. The styles applied to <html> and <body> are only there to allow the canvas to be full-screen.

Google map without markers

Adding Markers to the Map Canvas

Once we’ve got a basic map canvas displayed, the most common next task is to plot markers on the map. One piece of advice I always give in most programming contexts is to separate data from logic whenever possible. In this case this is illustrated by storing your marker details in a separate JSON file.

Create a JSON file for the markers

Go ahead and create a JSON file called markers.json:

    "lat": 53.817680,
    "lng": -1.537657
    "lat": 53.790123,
    "lng": -1.53243
    "lat": 53.756745,
    "lng": -1.5309087
    "lat": 53.6474675,
    "lng": -1.49564554
    "lat": 53.69123456,
    "lng": -1.6545466

It’s always a good idea to store Google Maps markers as latitude and longitude values rather than addresses. Otherwise, we have to use Google’s Geocoding service at runtime. This is a separate API with strict usage limits that will also add another external entity to the map initialization process, increasing latency.

Now that our JSON file is set up, we need to make use of it when initializing our map.

Plot the markers

Start off by amending the initMap() function to grab the markers.json file after the map has been initialized, using the shiny new Fetch API, passing a callback to a new function, plotMarkers(). We also use promises here to ensure the response is parsed into JSON before being passed to the callback function:

  .then(function(response){return response.json()})

Then let’s go ahead and define plotMarkers():

var markers;
var bounds;

function plotMarkers(m)
  markers = [];
  bounds = new google.maps.LatLngBounds();

  m.forEach(function (marker) {
    var position = new google.maps.LatLng(marker.lat, marker.lng);

      new google.maps.Marker({
        position: position,
        map: map,
        animation: google.maps.Animation.DROP



As with our map variable, we want to define some more variables outside of the function, in the global scope. In this function, we’ll be working with markers and bounds, both of which may be useful elsewhere later, so it’s a good idea to have these in the global scope.

Inside the plotMarkers function, the first things we need to do are set our markers variable to an empty array, and set our bounds variable to an empty Google LatLngBounds object. We’ll use the LatLngBounds object to keep track of the area that needs to be viewable on our canvas to fit all of our markers on.

Now we need to iterate over each marker, providing an anonymous callback function which creates a new Google position object from the lat and lng parameters available in our JSON file. Once we’ve got that, we’ll create a new Google map marker object and push it into our markers array. Finally, we’ll extend our bounds using the new position:

var position = new google.maps.LatLng(this.lat, this.lng);

  new google.maps.Marker({
    position: position,
    map: map,
    animation: google.maps.Animation.DROP


One thing to note: when creating a new Google map marker object, the only required parameters are position and map. The position parameter can be either an object containing lat and lng parameters, or a Google position object (as shown here). The map parameter is simply the Google map object that we want to plot the marker on. We also provide an animation parameter: this isn’t required, but is so easy to implement — and everyone loves a little animation!

Re-center the map canvas

Now that we’ve iterated through all of our markers, added them to the map and built our canvas bounds, we’ll call map.fitBounds() to re-center the map canvas around the markers plotted, overriding the initial center and zoom parameters we provided when initializing the map object. This is very useful, as it allows us to update our markers.json file without worrying about our center or zoom parameters.

See the Pen Google Maps JS API example by SitePoint (@SitePoint) on CodePen.

Closing Remarks

We should now have a working app that can display a full-screen Google Maps canvas, and plot markers on that map from a JSON file.

If you’re interested in taking it further, the next logical step would be to implement InfoWindows, which appear when a marker is clicked.

If you’re interested in building on the functionality already provided in this article, a good starting point would be to look at customizing the icons plotted on the map. This can be done by simply passing a URL as the icon parameter to the new marker object.

If you have any other improvements or suggestions, please feel free to add them in the comments.

And don’t forget, the full source code is available via our GitHub repo.

Frequently Asked Questions (FAQs) about Google Maps JavaScript API

What is the Google Maps JavaScript API and how does it work?

The Google Maps JavaScript API is a service provided by Google that allows developers to embed Google Maps on webpages using JavaScript. The API provides a number of utilities for manipulating maps and adding content to the map through a variety of services, allowing you to create robust maps applications on your website. It works by communicating with Google’s servers to fetch map data and render it on your webpage. You can customize the maps, add markers, polygons, and overlays, handle user interactions, and more.

How do I get started with the Google Maps JavaScript API?

To get started with the Google Maps JavaScript API, you first need to have a Google account and create a project in the Google Cloud Console. From there, you can enable the Maps JavaScript API for your project and generate an API key. This key is used to authenticate your application for usage of the API. Once you have the API key, you can include the Maps JavaScript API script in your HTML file with the key, and start using the API in your JavaScript code.

How can I customize the appearance of my Google Maps?

The Google Maps JavaScript API provides a variety of ways to customize the appearance of the maps. You can change the map type (roadmap, satellite, hybrid, terrain), control the zoom level, set the center of the map, and more. You can also use the Styled Maps feature to customize the color scheme of the map to match your website’s theme.

How do I add markers and info windows to my map?

Adding markers and info windows to your map involves creating new instances of the Marker and InfoWindow classes provided by the API, and adding them to your map. You can specify the position of the marker, the content of the info window, and other options in the constructor of these classes. You can also add event listeners to handle user interactions with the markers and info windows.

How do I handle user interactions with the map?

The Google Maps JavaScript API provides a number of event handlers that you can use to respond to user interactions with the map. These include click events, drag events, zoom change events, and more. You can add event listeners to your map and other objects (like markers and info windows) to handle these events and provide interactive functionality.

How can I use the Google Maps JavaScript API to get directions and distances?

The Google Maps JavaScript API provides the DirectionsService and DistanceMatrixService classes for getting directions and distances between locations. You can use these services to calculate routes, travel times, and distances in various travel modes (driving, walking, bicycling, transit), and display the results on your map.

How do I deal with errors and exceptions in the Google Maps JavaScript API?

The Google Maps JavaScript API provides error handling mechanisms to help you deal with errors and exceptions. These include error messages returned by the API, error events that you can listen for, and JavaScript exceptions that you can catch and handle in your code. It’s important to handle these errors gracefully to provide a good user experience.

How can I optimize the performance of my Google Maps application?

There are several ways to optimize the performance of your Google Maps application. These include using the minified version of the API, limiting the number of markers and other objects on the map, using marker clustering to group nearby markers, and using the bounds_changed event to load data only when necessary.

How do I use the Google Maps JavaScript API with other Google APIs and services?

The Google Maps JavaScript API can be used in conjunction with other Google APIs and services. For example, you can use the Geocoding API to convert addresses into geographic coordinates, the Places API to search for places and businesses, and the Street View API to display panoramic images. You can also use the Google Maps JavaScript API with Firebase to store and sync data in real time.

How do I stay updated with changes and new features in the Google Maps JavaScript API?

Google provides several resources to help you stay updated with changes and new features in the Google Maps JavaScript API. These include the official documentation, the Google Developers website, the Google Maps Platform blog, and the Google Maps APIs Google Group. You can also subscribe to the Google Cloud newsletter to receive updates directly in your inbox.