HeatmapTool.com | Documentation

Basic Map Overlay

This guide will help you create a basic HeatmapTool overlay on a Google Map.

Step 1: If you haven't done so already, get a registration key.

Step 2: Create an HTML file with the following code as a starting point:

<!DOCTYPE html>
<html>
<head>
	<script type="text/javascript" src="https://maps.googleapis.com/maps/api/js"></script>
	<script type="text/javascript" src="https://www.heatmaptool.com/js/heatmap.js"></script>
	<script type="text/javascript">

		function initialize() {

			// Creates and inserts Google Map

			var mapOptions = {
				zoom: 4,
				center: new google.maps.LatLng(38, -97),
				mapTypeId: google.maps.MapTypeId.SATELLITE
			};

			var map = new google.maps.Map(document.getElementById('map_canvas'), mapOptions);

			// Constructs a heat map overlay

			var heatMap = new HeatMap({
				key: 'fc53bd0fe8f2aae0cab19974ba755713',
				data: 'https://www.heatmaptool.com/data/mcdonalds.csv',
				gradient: 'fire',
				scale_dimming: 0.5,
				radius: 5
			});

			// Adds heat map to Google Map

			heatMap.addTo(map);

		}

	</script>
</head>
<body onload="initialize();">
	<div id="map_canvas" style="position: absolute; top: 0; right: 0; bottom: 0; left: 0;"></div>
</body>
</html>

Step 3: Change the values in mapOptions to configure the Google Map with options such as latitude, longitude, and zoom. Google describes the full list of options in the Google Maps API Documentation. In this example code, the zoom level is 4, the latitude is 38, and the longitude is -97. The map is being placed in the "map_canvas" div.

Step 4: Change the values in the heat map overlay constructor to tell HeatmapTool how to create your heat map overlay. The following two values are required:

key: Your registration key from Step 1
data: The URL to your comma separated values (CSV) data file

HeatmapTool will only read CSV data from the domain your registration key is associated with. Your CSV data should contain one data point per line, with latitude, longitude, and (optionally) amplitude separated by commas and in that order. For example:

51.74,-89.76,89
24.2,-153.23,69
32.78,-145.96,95
73.48,-107.13,79
66.29,-170.42,39
74.29,-64.95,50
65.93,-175.71,100
39.34,-151.86,55
27.23,-72.6,77
14.63,-168.45,57

The example HTML code also shows a few optional parameters being set: the gradient has been set to "fire," the scale dimming is at 0.5, and the spot radius is at 5. You can remove these options, adjust them, or add your own. All of the options are described here. Note that there is no trailing comma after the last options in both mapOptions and the heat map overlay constructor.

Your HTML document should now produce a Google Map with a HeatmapTool overlay. Here is a live example of the code above.

Multiple Overlays

HeatmapTool can add multiple overlays to a single Google Map, each with its own individual options. To do this, simply construct two different heat map overlays and use the addTo method on each overlay. For example:

<!DOCTYPE html>
<html>
<head>
	<script type="text/javascript" src="https://maps.googleapis.com/maps/api/js"></script>
	<script type="text/javascript" src="https://www.heatmaptool.com/js/heatmap.js"></script>
	<script type="text/javascript">

		function initialize() {

			// Creates and inserts Google Map

			var mapOptions = {
				zoom: 4,
				center: new google.maps.LatLng(38, -97),
				mapTypeId: google.maps.MapTypeId.SATELLITE
			};

			var map = new google.maps.Map(document.getElementById('map_canvas'), mapOptions);

			// Constructs two different heat map overlays

			var heatMap1 = new HeatMap({
				key: 'fc53bd0fe8f2aae0cab19974ba755713',
				data: 'https://www.heatmaptool.com/data/walmart.csv',
				gradient: 'cobalt',
				scale_dimming: 0.5,
				radius: 5,
				heatmap_opacity: 0.5
			});

			var heatMap2 = new HeatMap({
				key: 'fc53bd0fe8f2aae0cab19974ba755713',
				data: 'https://www.heatmaptool.com/data/mcdonalds.csv',
				gradient: 'gold',
				scale_dimming: 0.5,
				radius: 5,
				heatmap_opacity: 0.5
			});

			// Adds each heat map overlay to Google Map

			heatMap1.addTo(map);
			heatMap2.addTo(map);

		}

	</script>
</head>
<body onload="initialize();">
	<div id="map_canvas" style="position: absolute; top: 0; right: 0; bottom: 0; left: 0;"></div>
</body>
</html>

This example creates two overlays: a "cobalt" heat map of Walmart store locations, and a "gold" heat map of McDonald's restaurant locations. When adding several overlays, we recommend adjusting the heatmap_opacity parameter to avoid covering one heat map with the other. Here is a live example of the code above.

Removing Overlays

Just as heat map overlays are added with the addTo method, they can be removed with the removeFrom method. When called, the heat map will be removed from the specified map. For example:

<!DOCTYPE html>
<html>
<head>
	<script type="text/javascript" src="https://maps.googleapis.com/maps/api/js"></script>
	<script type="text/javascript" src="https://www.heatmaptool.com/js/heatmap.js"></script>
	<script type="text/javascript">

		function initialize() {

			// Creates and inserts Google Map

			var mapOptions = {
				zoom: 4,
				center: new google.maps.LatLng(38, -97),
				mapTypeId: google.maps.MapTypeId.SATELLITE
			};

			var map = new google.maps.Map(document.getElementById('map_canvas'), mapOptions);

			// Constructs a heat map overlay

			var heatMap = new HeatMap({
				key: 'fc53bd0fe8f2aae0cab19974ba755713',
				data: 'https://www.heatmaptool.com/data/mcdonalds.csv',
				gradient: 'fire',
				scale_dimming: 0.5,
				radius: 5
			});

			// Adds heat map to Google Map

			heatMap.addTo(map);

			// Removes heat map when map is clicked

			google.maps.event.addListener(map, 'click', function () {
				heatMap.removeFrom(map);
			});

		}

	</script>
</head>
<body onload="initialize();">
	<div id="map_canvas" style="position: absolute; top: 0; right: 0; bottom: 0; left: 0;"></div>
</body>
</html>

This example will remove the heat map overlay when the map is clicked. Here is a live example of the code above.

Radius Scaling

Sometimes, it is desirable to have the radius of heat map spots change to match the scale of the map as the user zooms in and out. By setting the optional radius_scale parameter to an integer between 0 and 22, the radius of heat map spots will be fixed at that zoom level. Zooming in and out from that zoom level results in the appropriate scaling up or down to match the map dimensions.

Here is an example which has the radius fixed at 5 pixels at a zoom level of 4.

Standalone Image

HeatmapTool can also be used to create standalone heat map images, with no javascript required. The URL for generating individual heat map images is:

http://www.heatmaptool.com/heatmap/?key=yourkey&data=yourdata

Change yourkey to your registration key and yourdata to the URL of your CSV data file. In this mode, each line of your CSV data file should provide the x-coordinate and y-coordinate (measured in pixels from the top left of the image), and optionally the amplitude.

The image dimensions are 256 by 256 pixels by default, but you can choose to change the height and width of the image to any value between 1 and 1024 pixels. To change these options or any of the other standard options, add them to the URL. For example, this will create a 512 by 512 pixel image:

http://www.heatmaptool.com/heatmap/?key=yourkey&data=yourdata&height=512&width=512

To embed this image on an HTML page, use the standard image tag:

<img src="http://www.heatmaptool.com/heatmap/?key=yourkey&data=yourdata&height=512&width=512" />

Here is a live example of a 512 by 512 pixel standalone image, using the "cobalt" gradient.

Options

Required Parameters

Name	Description
key	Your 32-character registration key (e.g. fc53bd0fe8f2aae0cab19974ba755713)
data	The full, valid URL to your comma separated values (CSV) data file (e.g. http://heatmaptool.com/data/mcdonalds.csv)

Gradient Options

Name	Description	Values	Default
gradient	Selects the color gradient from one of the built-in options or a custom one	fire, classic, cobalt, copper, emerald, gold, stoplight, sunset, custom	fire
gradient_min	If gradient is set to custom, selects the starting gradient color (for the lowest values)	color value in HEX format (e.g. CCCCCC, 006699, FFCC99)	000000
gradient_max	If gradient is set to custom, selects the ending gradient color (for the highest values)	color value in HEX format (e.g. CCCCCC, 006699, FFCC99)	FFFFFF
gradient_tiers	Optionally shows heat map colors as the specified number of solid regions	false, or an integer between 1 and 256	false

Heat Map Options

Name	Description	Values	Default
radius	Sets how far to draw the spot for each data point, in pixels	integer between 1 and 256	25
radius_scale	When creating map tiles, fixes the radius at the given zoom level (provided by Google Maps API) and scales the radius at other zoom levels	integer between 0 and 22	false
scale_min	Sets the minimum amplitude scale value, or lets HeatmapTool decide automatically	auto, or a number	auto
scale_max	Sets the maximum amplitude scale value, or lets HeatmapTool decide automatically	auto, or a number	auto
scale_dimming	Lowers the overall amplitude levels of the heat map	decimal number between 0 and 1	0
heatmap_feathering	Softens the edges of the heat map	decimal number between 0 and 1	0.5
heatmap_opacity	Sets the heat map opacity	decimal number between 0 and 1	1

Image Options

Name	Description	Values	Default
height	If map is set to false, sets the image height, in pixels	integer between 1 and 1024	256
width	If map is set to false, sets the image width, in pixels	integer between 1 and 1024	256
bg_color	Sets the background color	color value in HEX format (e.g. CCCCCC, 006699, FFCC99)	000000
bg_opacity	Sets the background opacity	decimal number between 0 and 1	0

Map Options

Note: You should not have to manually adjust these values if using HeatmapTool with the Google Maps API.

Name	Description	Values	Default
map	Reads CSV file as coordinates and outputs map tiles	true or false	false
map_x	If map is set to true, the map tile x-coordinate (provided by Google Maps API)	integer
map_y	If map is set to true, the map tile y-coordinate (provided by Google Maps API)	integer
map_zoom	If map is set to true, the map tile zoom level (provided by Google Maps API)	integer