From 2acb4aa23a80a5bf5d10e3dc16d13b2dc3d347bc Mon Sep 17 00:00:00 2001
From: Kristiyan Kostadinov <crisbeto@abv.bg>
Date: Mon, 11 Jan 2021 20:06:38 +0100
Subject: [PATCH] feat(google-maps): add heatmap support

Adds support for rendering heatmaps on the `google-map` component using the
`map-heatmap-layer` directive. The directive is mostly a direct wrapper around the
`google.maps.visualization.HeatmapLayer` class, except for the fact that it also accepts a
`LatLngLiteral`, whereas the Google Maps class only accepts `LatLng` objects. I decided
to add some logic to convert them automatically, because creating `LatLng` requires
the Maps API to have been loaded which can lead to race conditions if it's being loaded
lazily.
---
 package.json                                  |   2 +-
 src/dev-app/google-map/google-map-demo.html   |  10 ++
 src/dev-app/google-map/google-map-demo.ts     |  20 +++
 src/dev-app/index.html                        |   4 +-
 src/google-maps/README.md                     |  24 ++-
 src/google-maps/google-maps-module.ts         |   2 +
 src/google-maps/map-heatmap-layer/README.md   |  64 +++++++
 .../map-heatmap-layer.spec.ts                 | 166 +++++++++++++++++
 .../map-heatmap-layer/map-heatmap-layer.ts    | 169 ++++++++++++++++++
 src/google-maps/package.json                  |   2 +-
 src/google-maps/public-api.ts                 |   1 +
 .../testing/fake-google-map-utils.ts          |  62 +++++++
 .../kitchen-sink/kitchen-sink.html            |   5 +
 .../google-maps/google-maps.d.ts              |  17 +-
 yarn.lock                                     |   8 +-
 15 files changed, 542 insertions(+), 14 deletions(-)
 create mode 100644 src/google-maps/map-heatmap-layer/README.md
 create mode 100644 src/google-maps/map-heatmap-layer/map-heatmap-layer.spec.ts
 create mode 100644 src/google-maps/map-heatmap-layer/map-heatmap-layer.ts

diff --git a/package.json b/package.json
index 39a5484f9184..835ef4938cc4 100644
--- a/package.json
+++ b/package.json
@@ -59,7 +59,7 @@
     "@angular/elements": "^11.1.0",
     "@angular/forms": "^11.1.0",
     "@angular/platform-browser": "^11.1.0",
-    "@types/googlemaps": "^3.43.0",
+    "@types/googlemaps": "^3.43.1",
     "@types/youtube": "^0.0.40",
     "@webcomponents/custom-elements": "^1.1.0",
     "core-js-bundle": "^3.8.2",
diff --git a/src/dev-app/google-map/google-map-demo.html b/src/dev-app/google-map/google-map-demo.html
index 7471a0fa3d02..f2512c6acb46 100644
--- a/src/dev-app/google-map/google-map-demo.html
+++ b/src/dev-app/google-map/google-map-demo.html
@@ -33,6 +33,9 @@
     <map-directions-renderer *ngIf="directionsResult"
                              [directions]="directionsResult"></map-directions-renderer>
 
+    <map-heatmap-layer *ngIf="isHeatmapDisplayed"
+                       [data]="heatmapData"
+                       [options]="heatmapOptions"></map-heatmap-layer>
   </google-map>
 
   <p><label>Latitude:</label> {{display?.lat}}</p>
@@ -153,6 +156,13 @@
     </label>
   </div>
 
+  <div>
+    <label for="heatmap-layer-checkbox">
+      Toggle Heatmap Layer
+      <input type="checkbox" (click)="toggleHeatmapLayerDisplay()">
+    </label>
+  </div>
+
   <div>
     <button mat-button (click)="calculateDirections()">
       Calculate directions between first two markers
diff --git a/src/dev-app/google-map/google-map-demo.ts b/src/dev-app/google-map/google-map-demo.ts
index 690c38d51967..ae487e365233 100644
--- a/src/dev-app/google-map/google-map-demo.ts
+++ b/src/dev-app/google-map/google-map-demo.ts
@@ -58,6 +58,10 @@ export class GoogleMapDemo {
   polylineOptions:
       google.maps.PolylineOptions = {path: POLYLINE_PATH, strokeColor: 'grey', strokeOpacity: 0.8};
 
+  heatmapData = this._getHeatmapData(5, 1);
+  heatmapOptions = {radius: 50};
+  isHeatmapDisplayed = false;
+
   isPolygonDisplayed = false;
   polygonOptions:
       google.maps.PolygonOptions = {paths: POLYGON_PATH, strokeColor: 'grey', strokeOpacity: 0.8};
@@ -208,4 +212,20 @@ export class GoogleMapDemo {
       });
     }
   }
+
+  toggleHeatmapLayerDisplay() {
+    this.isHeatmapDisplayed = !this.isHeatmapDisplayed;
+  }
+
+  private _getHeatmapData(offset: number, increment: number) {
+    const result: google.maps.LatLngLiteral[] = [];
+
+    for (let lat = this.center.lat - offset; lat < this.center.lat + offset; lat += increment) {
+      for (let lng = this.center.lng - offset; lng < this.center.lng + offset; lng += increment) {
+        result.push({lat, lng});
+      }
+    }
+
+    return result;
+  }
 }
diff --git a/src/dev-app/index.html b/src/dev-app/index.html
index ffd3891e73f2..e8a99f3ead95 100644
--- a/src/dev-app/index.html
+++ b/src/dev-app/index.html
@@ -42,9 +42,9 @@
       var iframe = document.getElementById('google-maps-api-key');
       var googleMapsScript = document.createElement('script');
       var googleMapsApiKey = iframe.contentDocument.body.textContent;
-      var googleMapsUrl = 'https://maps.googleapis.com/maps/api/js';
+      var googleMapsUrl = 'https://maps.googleapis.com/maps/api/js?libraries=visualization';
       if (googleMapsApiKey !== 'Page not found') {
-        googleMapsUrl = googleMapsUrl + '?key=' + googleMapsApiKey;
+        googleMapsUrl = googleMapsUrl + '&key=' + googleMapsApiKey;
       }
       googleMapsScript.src = googleMapsUrl;
       document.body.appendChild(googleMapsScript);
diff --git a/src/google-maps/README.md b/src/google-maps/README.md
index af5be3fe6014..48ccbc3ee6b9 100644
--- a/src/google-maps/README.md
+++ b/src/google-maps/README.md
@@ -19,14 +19,23 @@ To install, run `npm install @angular/google-maps`.
 <!doctype html>
 <head>
   ...
-  <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY">
-  </script>
+  <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY"></script>
 </head>
 ```
 
+**Note:**
+If you're using the `<map-heatmap-layer>` directive, you also have to include the `visualization`
+library when loading the Google Maps API. To do so, you can add `&libraries=visualization` to the
+script URL:
+
+```html
+  <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=visualization"></script>
+```
+
 ## Lazy Loading the API
 
-The API can be loaded when the component is actually used by using the Angular HttpClient jsonp method to make sure that the component doesn't load until after the API has loaded.
+The API can be loaded when the component is actually used by using the Angular HttpClient jsonp
+method to make sure that the component doesn't load until after the API has loaded.
 
 ```typescript
 // google-maps-demo.module.ts
@@ -102,10 +111,14 @@ export class GoogleMapsDemoComponent {
 - [`MapTransitLayer`](./map-transit-layer/README.md)
 - [`MapBicyclingLayer`](./map-bicycling-layer/README.md)
 - [`MapDirectionsRenderer`](./map-directions-renderer/README.md)
+- [`MapHeatmapLayer`](./map-heatmap-layer/README.md)
 
 ## The Options Input
 
-The Google Maps components implement all of the options for their respective objects from the Google Maps JavaScript API through an `options` input, but they also have specific inputs for some of the most common options. For example, the Google Maps component could have its options set either in with a google.maps.MapOptions object:
+The Google Maps components implement all of the options for their respective objects from the
+Google Maps JavaScript API through an `options` input, but they also have specific inputs for some
+of the most common options. For example, the Google Maps component could have its options set either
+in with a google.maps.MapOptions object:
 
 ```html
 <google-map [options]="options"></google-map>
@@ -130,4 +143,5 @@ center: google.maps.LatLngLiteral = {lat: 40, lng: -20};
 zoom = 4;
 ```
 
-Not every option has its own input. See the API for each component to see if the option has a dedicated input or if it should be set in the options input.
+Not every option has its own input. See the API for each component to see if the option has a
+dedicated input or if it should be set in the options input.
diff --git a/src/google-maps/google-maps-module.ts b/src/google-maps/google-maps-module.ts
index 412070bb66fc..b77c2d38f64f 100644
--- a/src/google-maps/google-maps-module.ts
+++ b/src/google-maps/google-maps-module.ts
@@ -23,6 +23,7 @@ import {MapPolyline} from './map-polyline/map-polyline';
 import {MapRectangle} from './map-rectangle/map-rectangle';
 import {MapTrafficLayer} from './map-traffic-layer/map-traffic-layer';
 import {MapTransitLayer} from './map-transit-layer/map-transit-layer';
+import {MapHeatmapLayer} from './map-heatmap-layer/map-heatmap-layer';
 
 const COMPONENTS = [
   GoogleMap,
@@ -40,6 +41,7 @@ const COMPONENTS = [
   MapRectangle,
   MapTrafficLayer,
   MapTransitLayer,
+  MapHeatmapLayer,
 ];
 
 @NgModule({
diff --git a/src/google-maps/map-heatmap-layer/README.md b/src/google-maps/map-heatmap-layer/README.md
new file mode 100644
index 000000000000..cca046f0560a
--- /dev/null
+++ b/src/google-maps/map-heatmap-layer/README.md
@@ -0,0 +1,64 @@
+# MapHeatmapLayer
+
+The `MapHeatmapLayer` directive wraps the [`google.maps.visualization.HeatmapLayer` class](https://developers.google.com/maps/documentation/javascript/reference/visualization#HeatmapLayer) from the Google Maps Visualization JavaScript API. It displays
+a heatmap layer on the map when it is a content child of a `GoogleMap` component. Like `GoogleMap`,
+this directive offers an `options` input as well as a convenience input for passing in the `data`
+that is shown on the heatmap.
+
+## Requirements
+
+In order to render a heatmap, the Google Maps JavaScript API has to be loaded with the
+`visualization` library. To load the library, you have to add `&libraries=visualization` to the
+script that loads the Google Maps API. E.g.
+
+**Before:**
+```html
+<script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY"></script>
+```
+
+**After:**
+```html
+<script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=visualization"></script>
+```
+
+More information: https://developers.google.com/maps/documentation/javascript/heatmaplayer
+
+## Example
+
+```typescript
+// google-map-demo.component.ts
+import {Component} from '@angular/core';
+
+@Component({
+  selector: 'google-map-demo',
+  templateUrl: 'google-map-demo.html',
+})
+export class GoogleMapDemo {
+  center = {lat: 37.774546, lng: -122.433523};
+  zoom = 12;
+  heatmapOptions = {radius: 5};
+  heatmapData = [
+    {lat: 37.782, lng: -122.447},
+    {lat: 37.782, lng: -122.445},
+    {lat: 37.782, lng: -122.443},
+    {lat: 37.782, lng: -122.441},
+    {lat: 37.782, lng: -122.439},
+    {lat: 37.782, lng: -122.437},
+    {lat: 37.782, lng: -122.435},
+    {lat: 37.785, lng: -122.447},
+    {lat: 37.785, lng: -122.445},
+    {lat: 37.785, lng: -122.443},
+    {lat: 37.785, lng: -122.441},
+    {lat: 37.785, lng: -122.439},
+    {lat: 37.785, lng: -122.437},
+    {lat: 37.785, lng: -122.435}
+  ];
+}
+```
+
+```html
+<!-- google-map-demo.component.html -->
+<google-map height="400px" width="750px" [center]="center" [zoom]="zoom">
+  <map-heatmap-layer [data]="heatmapData" [options]="heatmapOptions"></map-heatmap-layer>
+</google-map>
+```
diff --git a/src/google-maps/map-heatmap-layer/map-heatmap-layer.spec.ts b/src/google-maps/map-heatmap-layer/map-heatmap-layer.spec.ts
new file mode 100644
index 000000000000..6b74d30dfe21
--- /dev/null
+++ b/src/google-maps/map-heatmap-layer/map-heatmap-layer.spec.ts
@@ -0,0 +1,166 @@
+import {Component, ViewChild} from '@angular/core';
+import {waitForAsync, TestBed} from '@angular/core/testing';
+
+import {DEFAULT_OPTIONS} from '../google-map/google-map';
+
+import {GoogleMapsModule} from '../google-maps-module';
+import {
+  createMapConstructorSpy,
+  createMapSpy,
+  createHeatmapLayerConstructorSpy,
+  createHeatmapLayerSpy,
+  createLatLngSpy,
+  createLatLngConstructorSpy
+} from '../testing/fake-google-map-utils';
+import {HeatmapData, MapHeatmapLayer} from './map-heatmap-layer';
+
+describe('MapHeatmapLayer', () => {
+  let mapSpy: jasmine.SpyObj<google.maps.Map>;
+  let latLngSpy: jasmine.SpyObj<google.maps.LatLng>;
+
+  beforeEach(waitForAsync(() => {
+    TestBed.configureTestingModule({
+      imports: [GoogleMapsModule],
+      declarations: [TestApp],
+    });
+  }));
+
+  beforeEach(() => {
+    TestBed.compileComponents();
+    mapSpy = createMapSpy(DEFAULT_OPTIONS);
+    latLngSpy = createLatLngSpy();
+    createMapConstructorSpy(mapSpy).and.callThrough();
+    createLatLngConstructorSpy(latLngSpy).and.callThrough();
+  });
+
+  afterEach(() => {
+    (window.google as any) = undefined;
+  });
+
+  it('initializes a Google Map heatmap layer', () => {
+    const heatmapSpy = createHeatmapLayerSpy();
+    const heatmapConstructorSpy = createHeatmapLayerConstructorSpy(heatmapSpy).and.callThrough();
+
+    const fixture = TestBed.createComponent(TestApp);
+    fixture.detectChanges();
+
+    expect(heatmapConstructorSpy).toHaveBeenCalledWith({
+      data: [],
+      map: mapSpy,
+    });
+  });
+
+  it('should throw if the `visualization` library has not been loaded', () => {
+    createHeatmapLayerConstructorSpy(createHeatmapLayerSpy());
+    delete (window.google.maps as any).visualization;
+
+    expect(() => {
+      const fixture = TestBed.createComponent(TestApp);
+      fixture.detectChanges();
+    }).toThrowError(/Namespace `google.maps.visualization` not found, cannot construct heatmap/);
+  });
+
+  it('sets heatmap inputs', () => {
+    const options: google.maps.visualization.HeatmapLayerOptions = {
+      map: mapSpy,
+      data: [
+        new google.maps.LatLng(37.782, -122.447),
+        new google.maps.LatLng(37.782, -122.445),
+        new google.maps.LatLng(37.782, -122.443)
+      ]
+    };
+    const heatmapSpy = createHeatmapLayerSpy();
+    const heatmapConstructorSpy = createHeatmapLayerConstructorSpy(heatmapSpy).and.callThrough();
+
+    const fixture = TestBed.createComponent(TestApp);
+    fixture.componentInstance.data = options.data;
+    fixture.detectChanges();
+
+    expect(heatmapConstructorSpy).toHaveBeenCalledWith(options);
+  });
+
+  it('sets heatmap options, ignoring map', () => {
+    const options: Partial<google.maps.visualization.HeatmapLayerOptions> = {
+      radius: 5,
+      dissipating: true
+    };
+    const data = [
+      new google.maps.LatLng(37.782, -122.447),
+      new google.maps.LatLng(37.782, -122.445),
+      new google.maps.LatLng(37.782, -122.443)
+    ];
+    const heatmapSpy = createHeatmapLayerSpy();
+    const heatmapConstructorSpy = createHeatmapLayerConstructorSpy(heatmapSpy).and.callThrough();
+
+    const fixture = TestBed.createComponent(TestApp);
+    fixture.componentInstance.data = data;
+    fixture.componentInstance.options = options;
+    fixture.detectChanges();
+
+    expect(heatmapConstructorSpy).toHaveBeenCalledWith({...options, map: mapSpy, data});
+  });
+
+  it('exposes methods that provide information about the heatmap', () => {
+    const heatmapSpy = createHeatmapLayerSpy();
+    createHeatmapLayerConstructorSpy(heatmapSpy).and.callThrough();
+
+    const fixture = TestBed.createComponent(TestApp);
+    fixture.detectChanges();
+    const heatmap = fixture.componentInstance.heatmap;
+
+    heatmapSpy.getData.and.returnValue([] as any);
+    expect(heatmap.getData()).toEqual([]);
+  });
+
+  it('should update the heatmap data when the input changes', () => {
+    const heatmapSpy = createHeatmapLayerSpy();
+    const heatmapConstructorSpy = createHeatmapLayerConstructorSpy(heatmapSpy).and.callThrough();
+    let data = [
+      new google.maps.LatLng(1, 2),
+      new google.maps.LatLng(3, 4),
+      new google.maps.LatLng(5, 6)
+    ];
+
+    const fixture = TestBed.createComponent(TestApp);
+    fixture.componentInstance.data = data;
+    fixture.detectChanges();
+
+    expect(heatmapConstructorSpy).toHaveBeenCalledWith(jasmine.objectContaining({data}));
+    data = [
+      new google.maps.LatLng(7, 8),
+      new google.maps.LatLng(9, 10),
+      new google.maps.LatLng(11, 12)
+    ];
+    fixture.componentInstance.data = data;
+    fixture.detectChanges();
+
+    expect(heatmapSpy.setData).toHaveBeenCalledWith(data);
+  });
+
+  it('should create a LatLng object if a LatLngLiteral is passed in', () => {
+    const latLngConstructor = createLatLngConstructorSpy(latLngSpy).and.callThrough();
+    createHeatmapLayerConstructorSpy(createHeatmapLayerSpy()).and.callThrough();
+    const fixture = TestBed.createComponent(TestApp);
+    fixture.componentInstance.data = [{lat: 1, lng: 2}, {lat: 3, lng: 4}];
+    fixture.detectChanges();
+
+    expect(latLngConstructor).toHaveBeenCalledWith(1, 2);
+    expect(latLngConstructor).toHaveBeenCalledWith(3, 4);
+    expect(latLngConstructor).toHaveBeenCalledTimes(2);
+  });
+
+});
+
+@Component({
+  selector: 'test-app',
+  template: `
+    <google-map>
+      <map-heatmap-layer [data]="data" [options]="options">
+      </map-heatmap-layer>
+    </google-map>`,
+})
+class TestApp {
+  @ViewChild(MapHeatmapLayer) heatmap: MapHeatmapLayer;
+  options?: Partial<google.maps.visualization.HeatmapLayerOptions>;
+  data?: HeatmapData;
+}
diff --git a/src/google-maps/map-heatmap-layer/map-heatmap-layer.ts b/src/google-maps/map-heatmap-layer/map-heatmap-layer.ts
new file mode 100644
index 000000000000..e0fadd294b4d
--- /dev/null
+++ b/src/google-maps/map-heatmap-layer/map-heatmap-layer.ts
@@ -0,0 +1,169 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+// Workaround for: https://github.com/bazelbuild/rules_nodejs/issues/1265
+/// <reference types="googlemaps" />
+
+import {
+  Input,
+  OnDestroy,
+  OnInit,
+  NgZone,
+  Directive,
+  OnChanges,
+  SimpleChanges,
+} from '@angular/core';
+
+import {GoogleMap} from '../google-map/google-map';
+
+/** Possible data that can be shown on a heatmap layer. */
+export type HeatmapData =
+  google.maps.MVCArray<
+    google.maps.LatLng | google.maps.visualization.WeightedLocation | google.maps.LatLngLiteral> |
+  (google.maps.LatLng | google.maps.visualization.WeightedLocation | google.maps.LatLngLiteral)[];
+
+
+/**
+ * Angular directive that renders a Google Maps heatmap via the Google Maps JavaScript API.
+ *
+ * See: https://developers.google.com/maps/documentation/javascript/reference/visualization
+ */
+@Directive({
+  selector: 'map-heatmap-layer',
+  exportAs: 'mapHeatmapLayer',
+})
+export class MapHeatmapLayer implements OnInit, OnChanges, OnDestroy {
+  /**
+   * Data shown on the heatmap.
+   * See: https://developers.google.com/maps/documentation/javascript/reference/visualization
+   */
+  @Input()
+  set data(data: HeatmapData) {
+    this._data = data;
+  }
+  private _data: HeatmapData;
+
+  /**
+   * Options used to configure the heatmap. See:
+   * developers.google.com/maps/documentation/javascript/reference/visualization#HeatmapLayerOptions
+   */
+  @Input()
+  set options(options: Partial<google.maps.visualization.HeatmapLayerOptions>) {
+    this._options = options;
+  }
+  private _options: Partial<google.maps.visualization.HeatmapLayerOptions>;
+
+  /**
+   * The underlying google.maps.visualization.HeatmapLayer object.
+   *
+   * See: https://developers.google.com/maps/documentation/javascript/reference/visualization
+   */
+  heatmap?: google.maps.visualization.HeatmapLayer;
+
+  constructor(
+    private readonly _googleMap: GoogleMap,
+    private _ngZone: NgZone) {}
+
+  ngOnInit() {
+    if (this._googleMap._isBrowser) {
+      if (!window.google?.maps?.visualization && (typeof ngDevMode === 'undefined' || ngDevMode)) {
+        throw Error(
+            'Namespace `google.maps.visualization` not found, cannot construct heatmap. ' +
+            'Please install the Google Maps JavaScript API with the "visualization" library: ' +
+            'https://developers.google.com/maps/documentation/javascript/visualization');
+      }
+
+      // Create the object outside the zone so its events don't trigger change detection.
+      // We'll bring it back in inside the `MapEventManager` only for the events that the
+      // user has subscribed to.
+      this._ngZone.runOutsideAngular(() => {
+        this.heatmap = new google.maps.visualization.HeatmapLayer(this._combineOptions());
+      });
+      this._assertInitialized();
+      this.heatmap.setMap(this._googleMap.googleMap!);
+    }
+  }
+
+  ngOnChanges(changes: SimpleChanges) {
+    const {_data, heatmap} = this;
+
+    if (heatmap) {
+      if (changes['options']) {
+        heatmap.setOptions(this._combineOptions());
+      }
+
+      if (changes['data'] && _data !== undefined) {
+        heatmap.setData(this._normalizeData(_data));
+      }
+    }
+  }
+
+  ngOnDestroy() {
+    if (this.heatmap) {
+      this.heatmap.setMap(null);
+    }
+  }
+
+  /**
+   * Gets the data that is currently shown on the heatmap.
+   * See: developers.google.com/maps/documentation/javascript/reference/visualization#HeatmapLayer
+   */
+  getData(): HeatmapData {
+    this._assertInitialized();
+    return this.heatmap.getData();
+  }
+
+  /** Creates a combined options object using the passed-in options and the individual inputs. */
+  private _combineOptions(): google.maps.visualization.HeatmapLayerOptions {
+    const options = this._options || {};
+    return {
+      ...options,
+      data: this._normalizeData(this._data || options.data || []),
+      map: this._googleMap.googleMap,
+    };
+  }
+
+  /**
+   * Most Google Maps APIs support both `LatLng` objects and `LatLngLiteral`. The latter is more
+   * convenient to write out, because the Google Maps API doesn't have to have been loaded in order
+   * to construct them. The `HeatmapLayer` appears to be an exception that only allows a `LatLng`
+   * object, or it throws a runtime error. Since it's more convenient and we expect that Angular
+   * users will load the API asynchronously, we allow them to pass in a `LatLngLiteral` and we
+   * convert it to a `LatLng` object before passing it off to Google Maps.
+   */
+  private _normalizeData(data: HeatmapData) {
+    const result: (google.maps.LatLng|google.maps.visualization.WeightedLocation)[] = [];
+
+    data.forEach(item => {
+      result.push(isLatLngLiteral(item) ? new google.maps.LatLng(item.lat, item.lng) : item);
+    });
+
+    return result;
+  }
+
+  /** Asserts that the heatmap object has been initialized. */
+  private _assertInitialized(): asserts this is {heatmap: google.maps.visualization.HeatmapLayer} {
+    if (typeof ngDevMode === 'undefined' || ngDevMode) {
+      if (!this._googleMap.googleMap) {
+        throw Error(
+            'Cannot access Google Map information before the API has been initialized. ' +
+            'Please wait for the API to load before trying to interact with it.');
+      }
+      if (!this.heatmap) {
+        throw Error(
+            'Cannot interact with a Google Map HeatmapLayer before it has been ' +
+            'initialized. Please wait for the heatmap to load before trying to interact with it.');
+      }
+    }
+  }
+}
+
+/** Asserts that an object is a `LatLngLiteral`. */
+function isLatLngLiteral(value: any): value is google.maps.LatLngLiteral {
+  return value && typeof value.lat === 'number' && typeof value.lng === 'number';
+}
diff --git a/src/google-maps/package.json b/src/google-maps/package.json
index d78398deb1f7..61ec6db2d249 100644
--- a/src/google-maps/package.json
+++ b/src/google-maps/package.json
@@ -17,7 +17,7 @@
   },
   "homepage": "https://github.com/angular/components/tree/master/src/google-maps#readme",
   "dependencies": {
-    "@types/googlemaps": "^3.43.0",
+    "@types/googlemaps": "^3.43.1",
     "tslib": "0.0.0-TSLIB"
   },
   "peerDependencies": {
diff --git a/src/google-maps/public-api.ts b/src/google-maps/public-api.ts
index 18785c52189d..9c4d5586bfac 100644
--- a/src/google-maps/public-api.ts
+++ b/src/google-maps/public-api.ts
@@ -24,3 +24,4 @@ export {MapPolyline} from './map-polyline/map-polyline';
 export {MapRectangle} from './map-rectangle/map-rectangle';
 export {MapTrafficLayer} from './map-traffic-layer/map-traffic-layer';
 export {MapTransitLayer} from './map-transit-layer/map-transit-layer';
+export {MapHeatmapLayer, HeatmapData} from './map-heatmap-layer/map-heatmap-layer';
diff --git a/src/google-maps/testing/fake-google-map-utils.ts b/src/google-maps/testing/fake-google-map-utils.ts
index 9a41b377a0e9..020f4981ac61 100644
--- a/src/google-maps/testing/fake-google-map-utils.ts
+++ b/src/google-maps/testing/fake-google-map-utils.ts
@@ -30,6 +30,10 @@ export interface TestingWindow extends Window {
       BicyclingLayer?: jasmine.Spy;
       DirectionsRenderer?: jasmine.Spy;
       DirectionsService?: jasmine.Spy;
+      LatLng?: jasmine.Spy;
+      visualization?: {
+        HeatmapLayer?: jasmine.Spy;
+      }
     };
   };
   MarkerClusterer?: jasmine.Spy;
@@ -500,3 +504,61 @@ export function createDirectionsServiceConstructorSpy(
   }
   return directionsServiceConstructorSpy;
 }
+
+/** Creates a jasmine.SpyObj for a `google.maps.visualization.HeatmapLayer`. */
+export function createHeatmapLayerSpy(): jasmine.SpyObj<google.maps.visualization.HeatmapLayer> {
+  const heatmapLayerSpy = jasmine.createSpyObj('google.maps.visualization.HeatmapLayer', [
+    'setMap', 'setOptions', 'setData', 'getData'
+  ]);
+  return heatmapLayerSpy;
+}
+
+/**
+ * Creates a jasmine.Spy to watch for the constructor
+ * of a `google.maps.visualization.HeatmapLayer`.
+ */
+export function createHeatmapLayerConstructorSpy(
+    heatmapLayerSpy: jasmine.SpyObj<google.maps.visualization.HeatmapLayer>): jasmine.Spy {
+  const heatmapLayerConstructorSpy = jasmine.createSpy('HeatmapLayer constructor', () => {
+    return heatmapLayerSpy;
+  });
+  const testingWindow: TestingWindow = window;
+  if (testingWindow.google && testingWindow.google.maps) {
+    if (!testingWindow.google.maps.visualization) {
+      testingWindow.google.maps.visualization = {};
+    }
+    testingWindow.google.maps.visualization['HeatmapLayer'] = heatmapLayerConstructorSpy;
+  } else {
+    testingWindow.google = {
+      maps: {
+        visualization: {
+          'HeatmapLayer': heatmapLayerConstructorSpy,
+        }
+      },
+    };
+  }
+  return heatmapLayerConstructorSpy;
+}
+
+
+/** Creates a jasmine.SpyObj for a google.maps.LatLng. */
+export function createLatLngSpy(): jasmine.SpyObj<google.maps.LatLng> {
+  return jasmine.createSpyObj('google.maps.LatLng', ['equals', 'lat', 'lng']);
+}
+
+/** Creates a jasmine.Spy to watch for the constructor of a google.maps.LatLng */
+export function createLatLngConstructorSpy(
+  latLngSpy: jasmine.SpyObj<google.maps.LatLng>): jasmine.Spy {
+  const latLngConstructorSpy = jasmine.createSpy('LatLng constructor', () => latLngSpy);
+  const testingWindow: TestingWindow = window;
+  if (testingWindow.google && testingWindow.google.maps) {
+    testingWindow.google.maps['LatLng'] = latLngConstructorSpy;
+  } else {
+    testingWindow.google = {
+      maps: {
+        'LatLng': latLngConstructorSpy,
+      },
+    };
+  }
+  return latLngConstructorSpy;
+}
diff --git a/src/universal-app/kitchen-sink/kitchen-sink.html b/src/universal-app/kitchen-sink/kitchen-sink.html
index 63d325be3ce4..a70ff5be37bb 100644
--- a/src/universal-app/kitchen-sink/kitchen-sink.html
+++ b/src/universal-app/kitchen-sink/kitchen-sink.html
@@ -426,6 +426,11 @@ <h2>Google Map</h2>
     <map-traffic-layer></map-traffic-layer>
     <map-transit-layer></map-transit-layer>
     <map-bicycling-layer></map-bicycling-layer>
+    <map-heatmap-layer [data]="[
+      {lat: 37.782, lng: -122.447},
+      {lat: 37.782, lng: -122.445},
+      {lat: 37.782, lng: -122.443}
+    ]"></map-heatmap-layer>
 
     <map-marker-clusterer imagePath="https://developers.google.com/maps/documentation/javascript/examples/markerclusterer/m">
       <map-marker [position]="{lat: 24, lng: 12}"></map-marker>
diff --git a/tools/public_api_guard/google-maps/google-maps.d.ts b/tools/public_api_guard/google-maps/google-maps.d.ts
index bff9c1b271b8..40bc8c227ec8 100644
--- a/tools/public_api_guard/google-maps/google-maps.d.ts
+++ b/tools/public_api_guard/google-maps/google-maps.d.ts
@@ -52,9 +52,11 @@ export declare class GoogleMap implements OnChanges, OnInit, OnDestroy {
 
 export declare class GoogleMapsModule {
     static ɵinj: i0.ɵɵInjectorDef<GoogleMapsModule>;
-    static ɵmod: i0.ɵɵNgModuleDefWithMeta<GoogleMapsModule, [typeof i1.GoogleMap, typeof i2.MapBaseLayer, typeof i3.MapBicyclingLayer, typeof i4.MapCircle, typeof i5.MapDirectionsRenderer, typeof i6.MapGroundOverlay, typeof i7.MapInfoWindow, typeof i8.MapKmlLayer, typeof i9.MapMarker, typeof i10.MapMarkerClusterer, typeof i11.MapPolygon, typeof i12.MapPolyline, typeof i13.MapRectangle, typeof i14.MapTrafficLayer, typeof i15.MapTransitLayer], never, [typeof i1.GoogleMap, typeof i2.MapBaseLayer, typeof i3.MapBicyclingLayer, typeof i4.MapCircle, typeof i5.MapDirectionsRenderer, typeof i6.MapGroundOverlay, typeof i7.MapInfoWindow, typeof i8.MapKmlLayer, typeof i9.MapMarker, typeof i10.MapMarkerClusterer, typeof i11.MapPolygon, typeof i12.MapPolyline, typeof i13.MapRectangle, typeof i14.MapTrafficLayer, typeof i15.MapTransitLayer]>;
+    static ɵmod: i0.ɵɵNgModuleDefWithMeta<GoogleMapsModule, [typeof i1.GoogleMap, typeof i2.MapBaseLayer, typeof i3.MapBicyclingLayer, typeof i4.MapCircle, typeof i5.MapDirectionsRenderer, typeof i6.MapGroundOverlay, typeof i7.MapInfoWindow, typeof i8.MapKmlLayer, typeof i9.MapMarker, typeof i10.MapMarkerClusterer, typeof i11.MapPolygon, typeof i12.MapPolyline, typeof i13.MapRectangle, typeof i14.MapTrafficLayer, typeof i15.MapTransitLayer, typeof i16.MapHeatmapLayer], never, [typeof i1.GoogleMap, typeof i2.MapBaseLayer, typeof i3.MapBicyclingLayer, typeof i4.MapCircle, typeof i5.MapDirectionsRenderer, typeof i6.MapGroundOverlay, typeof i7.MapInfoWindow, typeof i8.MapKmlLayer, typeof i9.MapMarker, typeof i10.MapMarkerClusterer, typeof i11.MapPolygon, typeof i12.MapPolyline, typeof i13.MapRectangle, typeof i14.MapTrafficLayer, typeof i15.MapTransitLayer, typeof i16.MapHeatmapLayer]>;
 }
 
+export declare type HeatmapData = google.maps.MVCArray<google.maps.LatLng | google.maps.visualization.WeightedLocation | google.maps.LatLngLiteral> | (google.maps.LatLng | google.maps.visualization.WeightedLocation | google.maps.LatLngLiteral)[];
+
 export interface MapAnchorPoint {
     getAnchor(): google.maps.MVCObject;
 }
@@ -154,6 +156,19 @@ export declare class MapGroundOverlay implements OnInit, OnDestroy {
     static ɵfac: i0.ɵɵFactoryDef<MapGroundOverlay, never>;
 }
 
+export declare class MapHeatmapLayer implements OnInit, OnChanges, OnDestroy {
+    set data(data: HeatmapData);
+    heatmap?: google.maps.visualization.HeatmapLayer;
+    set options(options: Partial<google.maps.visualization.HeatmapLayerOptions>);
+    constructor(_googleMap: GoogleMap, _ngZone: NgZone);
+    getData(): HeatmapData;
+    ngOnChanges(changes: SimpleChanges): void;
+    ngOnDestroy(): void;
+    ngOnInit(): void;
+    static ɵdir: i0.ɵɵDirectiveDefWithMeta<MapHeatmapLayer, "map-heatmap-layer", ["mapHeatmapLayer"], { "data": "data"; "options": "options"; }, {}, never>;
+    static ɵfac: i0.ɵɵFactoryDef<MapHeatmapLayer, never>;
+}
+
 export declare class MapInfoWindow implements OnInit, OnDestroy {
     closeclick: Observable<void>;
     contentChanged: Observable<void>;
diff --git a/yarn.lock b/yarn.lock
index bc21e5955e87..b95f622dc322 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -1927,10 +1927,10 @@
     "@types/minimatch" "*"
     "@types/node" "*"
 
-"@types/googlemaps@^3.43.0":
-  version "3.43.2"
-  resolved "https://registry.yarnpkg.com/@types/googlemaps/-/googlemaps-3.43.2.tgz#87db9460337c935de6d78f359d8135b4bda0c1cf"
-  integrity sha512-qiu5rms7+bgLciKAXpRsxVB1P+Z6gbSxuO8tZfdyQV2k5e5L/7GjUI6Z69rMR+7YFmqU9vwOUglLQ6NJyP/K8g==
+"@types/googlemaps@^3.43.1":
+  version "3.43.1"
+  resolved "https://registry.yarnpkg.com/@types/googlemaps/-/googlemaps-3.43.1.tgz#ce8ff7a6fb5db6fa4d46cfda00cc8144a9fbede3"
+  integrity sha512-0fLZrXDMx/spPbn0YVae0YVxwd2tAdWvA4RrjIy4s4k77DEGUJJYks7AAEW8fHGAoTwu0LmGvO3NsJAPjXRAJw==
 
 "@types/gulp@4.0.8":
   version "4.0.8"