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:

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:

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:

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:

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:

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.

Street Addresses

Note: This feature is experimental.

Instead of latitude and longitude, you can provide HeatmapTool with human-readable street addresses and location names. We will attempt to interpret these locations using several geocoding services and display as many of these points as we can.

To enable address mode, set the option address to 'true'. For example:

Here is a live example of the code above. Our example data file is populated with a list of major U.S. cities, but we could have chosen to use street addresses as well. In this case, the data file we provide to HeatmapTool has a slightly different syntax. Instead of comma-separated values of latitude and longitude, each line in the file represents an address or location.

If you wish to use the optional amplitude value at a point, add the value to the end of the line with a "|" separator. For example, this line would set an amplitude of 12 at the White House:

1600 Pennsylvania Ave, Washington, DC 20500|12

Note: Converting addresses and locations to coordinates takes time - about a half second each. However, we will remember the coordinates on the server, so the heat map should load quickly after the first time. This is fine for small sets of data, but it's not practical for very large data sets. If you still wish to use this feature with a large data set, we recommend that you start small and add data points gradually to improve performance.

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:

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
address Use addresses and locations instead of latitudes and longitudes 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