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.
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.
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.
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.
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.
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:
To embed this image on an HTML page, use the standard image tag:
|key||Your 32-character registration key (e.g. fc53bd0fe8f2aae0cab19974ba755713)|
|data||The full, valid URL to your comma separated values (CSV) data file
|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
|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|
|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|
Note: You should not have to manually adjust these values if using HeatmapTool with the Google Maps API.
|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|