Published on
Updated on
Updated on

How to Add XYZ Tile Layers to a Google Maps JavaScript API Map

This article teaches you how to create a simple Google Maps JavaScript API application with XYZ tile layers. You can use any of the layers on our categorized layer list to add to the application.

Here is a CodePen of the resulting application:

First, let's create an index.html file:

<!DOCTYPE html>
    <title>Google Maps JavaScript API - XYZ Tiles Demo</title>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1, user-scalable=no" />
    <link rel="stylesheet" href="style.css" />
    <script src=""></script>
    <div id="map"></div>
    <script src="main.js"></script>

What's happening here:

  • We include a CSS file on line 7 that we will create later.
  • We include JavaScript polyfills on line 8 to support older browsers.
  • We create a container for the map on line 11, defining 'map' as the id (you can use any id you want).
  • We include a JavaScript file on line 12 that we will create later.
  • We load the Google Maps JavaScript API on lines 13-16. You have to replace YOUR_API_KEY on line 14 with your own Google Maps JavaScript API key. You can get your key by following Google's instructions. The callback parameter specifies the name of a global function to be called once the JavaScript API has been completely loaded. We will define the initMap function later in our JavaScript file. The async attribute asks the browser to asynchronously download and execute the script.

Now, let's create a style.css file to style the map:

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

#map {
  height: 100%;

These rules will make our map appear full screen.

Finally, we'll create a main.js file that will handle creating the map object and adding layers to the map:

let map;

initMap = () => {
  map = new google.maps.Map(document.getElementById('map'), {
    center: { lat: 52.2, lng: -1.5 },
    zoom: 8,
    mapTypeControlOptions: {
      mapTypeIds: ['roadmap', 'satellite', 'terrain', 'hybrid', 'cartoDBDarkMatter']
    mapTypeId: 'cartoDBDarkMatter'

  const cartoDBDarkMatter = new google.maps.ImageMapType({
    getTileUrl: (coord, zoom) => {
      const subdomains = ['a', 'b', 'c', 'd'];
      const subdomain = subdomains[~~(Math.random() * subdomains.length)];
      return `https://${subdomain}${zoom}/${coord.x}/${coord.y}.png`;
    alt: 'CartoDB - DarkMatter',
    name: 'CartoDB - DarkMatter',
    maxZoom: 19

  map.mapTypes.set('cartoDBDarkMatter', cartoDBDarkMatter);

Let's break it down:

  • We initialize the map on lines 4-11:
    • First we obtain a reference to the map's container that we added to the HTML file via the document.getElementById() method.
    • Then we set the map's view to our chosen geographical coordinates and zoom level (here we use coordinates for some place in England).
    • Next, in mapTypeControlOptions, we define the mapTypeIds that will be available in the application. The roadmap, satellite, terrain and hybrid map types are available from the API and we add our own map type to the list.
    • Lastly, with mapTypeId, we set the initial map type ID to be displayed in the application.
  • We define the tile layer (or 'map type' using Google's terminology) on lines 13-22 (the highlighted part) and save it to a variable.
  • Finally, on line 24, we set the map type registry to associate the created map type with an ID.

You can pick any of the layers from our categorized layer list to add to your application. Just copy the code to create the layer in the preview application, paste it into your JavaScript file in place of the highlighted part and add the map.mapTypes.set(MAPTYPE_ID, mapType) command.