The Heatmap Layer provides client side rendering of heatmaps.
Overview
A heatmap is a visualization used to depict the intensity of data at geographical points. When the Heatmap Layer is enabled, a colored overlay will appear on top of the map. By default, areas of higher intensity will be colored red, and areas of lower intensity will appear green.
The Maps JavaScript API can either render heatmap data client-side via the Heatmap Layer, or server-side via a Fusion Table. Some of the key differences between the two methods include:
| Heatmap Layer | Fusion Table Layer |
|---|---|
| A large number of data points may result in reduced performance. | More data points will have little impact on performance. |
| Able to customize the appearance of the heatmap by changing such options as: the color gradient, the radius of data points, and the intensity of each data point. | No ability to customize the appearance of the heatmap. |
| Able to control whether heatmap data dissipates at higher zoom levels or not. | All heatmap data will dissipate as you zoom in. |
| Data can be stored with your HTML, stored on a server, or calculated on the fly. Data can be changed at runtime. | All data must be stored in a Fusion Table. Data cannot be easily changed at runtime. |
Load the visualization library
The Heatmap Layer is part of the google.maps.visualization library, and is not
loaded by default. The Visualization classes are a self-contained library,
separate from the main Maps JavaScript API code. To use the functionality
contained within this library, you must first load it using the libraries
parameter in the Maps JavaScript API bootstrap URL:
<script type="text/javascript"
src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=visualization">
</script>
Add a Heatmap Layer
To add a Heatmap Layer, you must first create a new HeatmapLayer
object, and provide it with some geographic data in the form of an array or an
MVCArray[] object. The data may be either a
LatLng
object or a
WeightedLocation
object. After instantiating the HeatmapLayer object, add it to the
map by calling the setMap() method.
The following example adds 14 data points to a map of San Francisco.
/* Data points defined as an array of LatLng objects */
var heatmapData = [
new google.maps.LatLng(37.782, -122.447),
new google.maps.LatLng(37.782, -122.445),
new google.maps.LatLng(37.782, -122.443),
new google.maps.LatLng(37.782, -122.441),
new google.maps.LatLng(37.782, -122.439),
new google.maps.LatLng(37.782, -122.437),
new google.maps.LatLng(37.782, -122.435),
new google.maps.LatLng(37.785, -122.447),
new google.maps.LatLng(37.785, -122.445),
new google.maps.LatLng(37.785, -122.443),
new google.maps.LatLng(37.785, -122.441),
new google.maps.LatLng(37.785, -122.439),
new google.maps.LatLng(37.785, -122.437),
new google.maps.LatLng(37.785, -122.435)
];
var sanFrancisco = new google.maps.LatLng(37.774546, -122.433523);
map = new google.maps.Map(document.getElementById('map'), {
center: sanFrancisco,
zoom: 13,
mapTypeId: 'satellite'
});
var heatmap = new google.maps.visualization.HeatmapLayer({
data: heatmapData
});
heatmap.setMap(map);
Add Weighted Data Points
A heatmap can render either
LatLng or
WeightedLocation
objects, or a combination of the two. Both objects represent a single data
point on a map, but a WeightedLocation object allows you to additionally
specify a weight for that data point. Applying a weight to a data point will
cause the WeightedLocation to be rendered with a greater intensity than a
simple LatLng object. The weight is a linear scale, in which each LatLng
object has an implicit weight of 1 — adding a single WeightedLocation
of {location: new google.maps.LatLng(37.782, -122.441), weight: 3} will have
the same effect as adding google.maps.LatLng(37.782, -122.441) three times.
You can mix weightedLocation and LatLng objects in a single array.
Using a WeightedLocation object in place of a LatLng can be useful when:
- Adding large amounts of data at a single location. Rendering a single
WeightedLocationobject with a weight of 1000 will be faster than rendering 1000LatLngobjects. - Applying an emphasis to your data based upon arbitrary values. For example,
you can use
LatLngobjects when plotting earthquake data, but you may want to use aWeightedLocationto measure the magnitude of each earthquake on the richter scale.
/* Data points defined as a mixture of WeightedLocation and LatLng objects */
var heatMapData = [
{location: new google.maps.LatLng(37.782, -122.447), weight: 0.5},
new google.maps.LatLng(37.782, -122.445),
{location: new google.maps.LatLng(37.782, -122.443), weight: 2},
{location: new google.maps.LatLng(37.782, -122.441), weight: 3},
{location: new google.maps.LatLng(37.782, -122.439), weight: 2},
new google.maps.LatLng(37.782, -122.437),
{location: new google.maps.LatLng(37.782, -122.435), weight: 0.5},
{location: new google.maps.LatLng(37.785, -122.447), weight: 3},
{location: new google.maps.LatLng(37.785, -122.445), weight: 2},
new google.maps.LatLng(37.785, -122.443),
{location: new google.maps.LatLng(37.785, -122.441), weight: 0.5},
new google.maps.LatLng(37.785, -122.439),
{location: new google.maps.LatLng(37.785, -122.437), weight: 2},
{location: new google.maps.LatLng(37.785, -122.435), weight: 3}
];
var sanFrancisco = new google.maps.LatLng(37.774546, -122.433523);
map = new google.maps.Map(document.getElementById('map'), {
center: sanFrancisco,
zoom: 13,
mapTypeId: 'satellite'
});
var heatmap = new google.maps.visualization.HeatmapLayer({
data: heatMapData
});
heatmap.setMap(map);
Customize a Heatmap Layer
You can customize how your heatmap will be rendered with the following heatmap
options. See the
HeatmapLayerOptions documentation for more information.
dissipating: Specifies whether heatmaps dissipate on zoom. When dissipating is false the radius of influence increases with zoom level to ensure that the color intensity is preserved at any given geographic location. Defaults to true.gradient: The color gradient of the heatmap, specified as an array of CSS color strings. All CSS3 colors — including RGBA — are supported except for extended named colors and HSL(A) values.maxIntensity: The maximum intensity of the heatmap. By default, heatmap colors are dynamically scaled according to the greatest concentration of points at any particular pixel on the map. This property allows you to specify a fixed maximum. Setting the maximum intensity can be helpful when your dataset contains a few outliers with an unusually high intensity.radius: The radius of influence for each data point, in pixels.opacity: The opacity of the heatmap, expressed as a number between 0 and 1.
The below example shows some of the customization options available.