Google Maps Android Heatmap Utility

Heatmaps are useful for representing the distribution and density of data points on a map.

Introduction

The Maps SDK for Android Utility Library includes a heatmap utility, which you can use to add one or more heatmaps to a Google map in your application.

This video discusses the use of heatmaps as an alternative to markers, when your data requires a large number of data points on the map.

Heatmaps make it easy for viewers to understand the distribution and relative intensity of data points on a map. Rather than placing a marker at each location, heatmaps use color to represent the distribution of the data.

In the example below, red represents areas of high concentration of police stations in Victoria, Australia.

If you haven't yet set up the Maps SDK for Android Utility library, follow the setup guide before reading the rest of this page.

Add a simple heatmap

To add a heatmap to your map, you will need a dataset consisting of the coordinates for each location of interest. First create a HeatmapTileProvider , passing it the collection of LatLng objects. Then create a new TileOverlay , passing it the heatmap tile provider, and add the tile overlay to the map.

The utility supplies the HeatmapTileProvider class, which implements the TileProvider interface to supply the tile images for the heatmap. HeatmapTileProvider accepts a collection of LatLng objects (or WeightedLatLng objects, as described below ). It creates the tile images for various zoom levels, based on the radius, gradient and opacity options supplied. You can change the default values for these options.

Looking at the steps in more detail:

1. Use HeatmapTileProvider.Builder() , passing it a collection of LatLng objects, to add a new HeatmapTileProvider .
2. Create a new TileOverlayOptions object with the relevant options, including the HeatmapTileProvider .
3. Call GoogleMap.addTileOverlay() to add the overlay to the map.

 private 
  
 fun 
  
 addHeatMap 
 () 
  
 { 
  
 var 
  
 latLngs 
 : 
  
 List<LatLng?>? 
  
 = 
  
 null 
  
 // Get the data: latitude/longitude positions of police stations. 
  
 try 
  
 { 
  
 latLngs 
  
 = 
  
 readItems 
 ( 
 R 
 . 
 raw 
 . 
 police_stations 
 ) 
  
 } 
  
 catch 
  
 ( 
 e 
 : 
  
 JSONException 
 ) 
  
 { 
  
 Toast 
 . 
 makeText 
 ( 
 context 
 , 
  
 "Problem reading list of locations." 
 , 
  
 Toast 
 . 
 LENGTH_LONG 
 ) 
  
 . 
 show 
 () 
  
 } 
  
 // Create a heat map tile provider, passing it the latlngs of the police stations. 
  
 val 
  
 provider 
  
 = 
  
 HeatmapTileProvider 
 . 
 Builder 
 () 
  
 . 
 data 
 ( 
 latLngs 
 ) 
  
 . 
 build 
 () 
  
 // Add a tile overlay to the map, using the heat map tile provider. 
  
 val 
  
 overlay 
  
 = 
  
 map 
 . 
 addTileOverlay 
 ( 
 TileOverlayOptions 
 (). 
 tileProvider 
 ( 
 provider 
 )) 
 } 
 @Throws 
 ( 
 JSONException 
 :: 
 class 
 ) 
 private 
  
 fun 
  
 readItems 
 ( 
 @RawRes 
  
 resource 
 : 
  
 Int 
 ): 
  
 List<LatLng?> 
 { 
  
 val 
  
 result 
 : 
  
 MutableList<LatLng?> 
 = 
  
 ArrayList 
 () 
  
 val 
  
 inputStream 
  
 = 
  
 context 
 . 
 resources 
 . 
 openRawResource 
 ( 
 resource 
 ) 
  
 val 
  
 json 
  
 = 
  
 Scanner 
 ( 
 inputStream 
 ). 
 useDelimiter 
 ( 
 "\\A" 
 ). 
 next 
 () 
  
 val 
  
 array 
  
 = 
  
 JSONArray 
 ( 
 json 
 ) 
  
 for 
  
 ( 
 i 
  
 in 
  
 0 
  
 until 
  
 array 
 . 
 length 
 ()) 
  
 { 
  
 val 
  
 `object` 
  
 = 
  
 array 
 . 
 getJSONObject 
 ( 
 i 
 ) 
  
 val 
  
 lat 
  
 = 
  
 `object` 
 . 
 getDouble 
 ( 
 "lat" 
 ) 
  
 val 
  
 lng 
  
 = 
  
 `object` 
 . 
 getDouble 
 ( 
 "lng" 
 ) 
  
 result 
 . 
 add 
 ( 
 LatLng 
 ( 
 lat 
 , 
  
 lng 
 )) 
  
 } 
  
 return 
  
 result 
 } 
  

 private 
  
 void 
  
 addHeatMap 
 () 
  
 { 
  
 List<LatLng> 
  
 latLngs 
  
 = 
  
 null 
 ; 
  
 // Get the data: latitude/longitude positions of police stations. 
  
 try 
  
 { 
  
 latLngs 
  
 = 
  
 readItems 
 ( 
 R 
 . 
 raw 
 . 
 police_stations 
 ); 
  
 } 
  
 catch 
  
 ( 
 JSONException 
  
 e 
 ) 
  
 { 
  
 Toast 
 . 
 makeText 
 ( 
 context 
 , 
  
 "Problem reading list of locations." 
 , 
  
 Toast 
 . 
 LENGTH_LONG 
 ). 
 show 
 (); 
  
 } 
  
 // Create a heat map tile provider, passing it the latlngs of the police stations. 
  
 HeatmapTileProvider 
  
 provider 
  
 = 
  
 new 
  
 HeatmapTileProvider 
 . 
 Builder 
 () 
  
 . 
 data 
 ( 
 latLngs 
 ) 
  
 . 
 build 
 (); 
  
 // Add a tile overlay to the map, using the heat map tile provider. 
  
 TileOverlay 
  
 overlay 
  
 = 
  
 map 
 . 
 addTileOverlay 
 ( 
 new 
  
 TileOverlayOptions 
 (). 
 tileProvider 
 ( 
 provider 
 )); 
 } 
 private 
  
 List<LatLng> 
  
 readItems 
 ( 
 @RawRes 
  
 int 
  
 resource 
 ) 
  
 throws 
  
 JSONException 
  
 { 
  
 List<LatLng> 
  
 result 
  
 = 
  
 new 
  
 ArrayList 
<> (); 
  
 InputStream 
  
 inputStream 
  
 = 
  
 context 
 . 
 getResources 
 (). 
 openRawResource 
 ( 
 resource 
 ); 
  
 String 
  
 json 
  
 = 
  
 new 
  
 Scanner 
 ( 
 inputStream 
 ). 
 useDelimiter 
 ( 
 "\\A" 
 ). 
 next 
 (); 
  
 JSONArray 
  
 array 
  
 = 
  
 new 
  
 JSONArray 
 ( 
 json 
 ); 
  
 for 
  
 ( 
 int 
  
 i 
  
 = 
  
 0 
 ; 
  
 i 
 < 
 array 
 . 
 length 
 (); 
  
 i 
 ++ 
 ) 
  
 { 
  
 JSONObject 
  
 object 
  
 = 
  
 array 
 . 
 getJSONObject 
 ( 
 i 
 ); 
  
 double 
  
 lat 
  
 = 
  
 object 
 . 
 getDouble 
 ( 
 "lat" 
 ); 
  
 double 
  
 lng 
  
 = 
  
 object 
 . 
 getDouble 
 ( 
 "lng" 
 ); 
  
 result 
 . 
 add 
 ( 
 new 
  
 LatLng 
 ( 
 lat 
 , 
  
 lng 
 )); 
  
 } 
  
 return 
  
 result 
 ; 
 } 
  

For this example, the data is stored in a JSON file, police_stations.json . Here is an extract from the file:

[
{"lat" : -37.1886, "lng" : 145.708 } ,
{"lat" : -37.8361, "lng" : 144.845 } ,
{"lat" : -38.4034, "lng" : 144.192 } ,
{"lat" : -38.7597, "lng" : 143.67 } ,
{"lat" : -36.9672, "lng" : 141.083 }
]

Use weighted latitude/longitude points

When creating a HeatmapTileProvider , you can pass it a collection of weighted latitude/longitude coordinates. This is useful if you want to illustrate the importance of a particular set of locations.

To apply weighting to specific locations:

1. Create a new WeightedLatLng for each location that requires weighting. Pass in the LatLng and a double representing the intensity required. The intensity indicates the relative importance, or value, of this location. A higher value will result in a higher-intensity color in the heatmap gradient. By default, the highest-intensity color is red.

2. Call HeatmapTileProvider.Builder().weightedData() , instead of HeatmapTileProvider.Builder().data() , to create the heatmap.

Customize the heatmap

A number of properties of the heatmap are customizable. You can set the options at time of creation, via Builder functions. Alternatively, change an option at any time by calling the relevant setter on the HeatmapTileProvider , and then clear the overlay's tile cache so that it redraws all the tiles with the new options.

The following options are available:

1. Radius: The size of the Gaussian blur applied to the heatmap, expressed in pixels. The default is 20. Must be between 10 and 50. Use the Builder's radius() to set the value when creating the heatmap, or change the value later with setRadius() .
2. Gradient: A range of colors that the heatmap uses to generate its color map, ranging from lowest to highest intensity. A gradient is created using two arrays: an integer array containing the colors, and a float array indicating the starting point for each color, given as a percentage of the maximum intensity, and expressed as a fraction from 0 to 1. You need to specify only one color for a single-colored gradient, or a minimum of two colors for a multi-colored gradient. The color map is generated using interpolation between those colors. The default gradient has two colors. Use the Builder's gradient() to set the value when creating the heatmap, or change the value later with setGradient() .
3. Opacity: This is the opacity of the entire heatmap layer, and ranges from 0 to 1. The default is 0.7. Use the Builder's opacity() to set the value when creating the heatmap, or change the value later with setOpacity() .

For example, create a Gradient to set the gradient before adding the heatmap:

 // Create the gradient. 
 val 
  
 colors 
  
 = 
  
 intArrayOf 
 ( 
  
 Color 
 . 
 rgb 
 ( 
 102 
 , 
  
 225 
 , 
  
 0 
 ), 
  
 // green 
  
 Color 
 . 
 rgb 
 ( 
 255 
 , 
  
 0 
 , 
  
 0 
 ) 
  
 // red 
 ) 
 val 
  
 startPoints 
  
 = 
  
 floatArrayOf 
 ( 
 0.2f 
 , 
  
 1f 
 ) 
 val 
  
 gradient 
  
 = 
  
 Gradient 
 ( 
 colors 
 , 
  
 startPoints 
 ) 
 // Create the tile provider. 
 val 
  
 provider 
  
 = 
  
 HeatmapTileProvider 
 . 
 Builder 
 () 
  
 . 
 data 
 ( 
 latLngs 
 ) 
  
 . 
 gradient 
 ( 
 gradient 
 ) 
  
 . 
 build 
 () 
 // Add the tile overlay to the map. 
 val 
  
 tileOverlay 
  
 = 
  
 map 
 . 
 addTileOverlay 
 ( 
  
 TileOverlayOptions 
 () 
  
 . 
 tileProvider 
 ( 
 provider 
 ) 
 ) 
  

 // Create the gradient. 
 int 
 [] 
  
 colors 
  
 = 
  
 { 
  
 Color 
 . 
 rgb 
 ( 
 102 
 , 
  
 225 
 , 
  
 0 
 ), 
  
 // green 
  
 Color 
 . 
 rgb 
 ( 
 255 
 , 
  
 0 
 , 
  
 0 
 ) 
  
 // red 
 }; 
 float 
 [] 
  
 startPoints 
  
 = 
  
 { 
  
 0.2f 
 , 
  
 1f 
 }; 
 Gradient 
  
 gradient 
  
 = 
  
 new 
  
 Gradient 
 ( 
 colors 
 , 
  
 startPoints 
 ); 
 // Create the tile provider. 
 HeatmapTileProvider 
  
 provider 
  
 = 
  
 new 
  
 HeatmapTileProvider 
 . 
 Builder 
 () 
  
 . 
 data 
 ( 
 latLngs 
 ) 
  
 . 
 gradient 
 ( 
 gradient 
 ) 
  
 . 
 build 
 (); 
 // Add the tile overlay to the map. 
 TileOverlay 
  
 tileOverlay 
  
 = 
  
 map 
 . 
 addTileOverlay 
 ( 
 new 
  
 TileOverlayOptions 
 (). 
 tileProvider 
 ( 
 provider 
 )); 
  

To change the opacity of an existing heatmap:

 provider 
 . 
 setOpacity 
 ( 
 0.7 
 ) 
 tileOverlay 
 ?. 
 clearTileCache 
 () 
  

 provider 
 . 
 setOpacity 
 ( 
 0.7 
 ); 
 tileOverlay 
 . 
 clearTileCache 
 (); 
  

Change the dataset

To change the dataset upon which a heatmap is built, use HeatmapTileProvider.setData() , or HeatmapTileProvider.setWeightedData() for WeightedLatLng points. Note: If you want to add points to the heatmap, or remove points from the heatmap, update your data collection and then use setData() or setWeightedData() .

 val 
  
 data 
 : 
  
 List<WeightedLatLng> 
  
 = 
  
 ArrayList 
 () 
 provider 
 . 
 setWeightedData 
 ( 
 data 
 ) 
 tileOverlay 
 ?. 
 clearTileCache 
 () 
  

 List<WeightedLatLng> 
  
 data 
  
 = 
  
 new 
  
 ArrayList 
<> (); 
 provider 
 . 
 setWeightedData 
 ( 
 data 
 ); 
 tileOverlay 
 . 
 clearTileCache 
 (); 
  

Remove a heatmap

To remove the heatmap, you need to remove the tile overlay:

 tileOverlay 
 ?. 
 remove 
 () 
  

 tileOverlay 
 . 
 remove 
 (); 
  

See the demo app

For another example of a heatmap implementation, take a look at the HeatmapsDemoActivity in the demo app that ships with the utility library. The setup guide shows you how to run the demo app.