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:
- 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:
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.
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 |
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 |