Select platform: [Android](https://developers.google.com/maps/documentation/android-sdk/utility/heatmap.md.txt "View this page for the Android platform docs.") [iOS](https://developers.google.com/maps/documentation/ios-sdk/utility/heatmap.md.txt "View this page for the iOS platform docs.") Heatmaps are useful for representing the distribution and density of data points on a map. ## Introduction The [Maps SDK for Android Utility Library](https://developers.google.com/maps/documentation/android-sdk/utility) 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. [Video](https://www.youtube.com/watch?v=FFm9NmSfjw0) 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. ![A map with a heatmap showing location of police stations](https://developers.google.com/static/maps/documentation/android-sdk/images/utility-heatmap.png) A heatmap on a map > [!NOTE] > **Hint:** You can set your own colors for the heatmap, using the `setGradient()` method. See how to [customize](https://developers.google.com/maps/documentation/android-sdk/utility/heatmap.md.txt#custom) colors and other properties of your heatmap. If you haven't yet set up the Maps SDK for Android Utility library, follow the [setup guide](https://developers.google.com/maps/documentation/android-sdk/utility/setup.md.txt) 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`](http://googlemaps.github.io/android-maps-utils/javadoc/com/google/maps/android/heatmaps/HeatmapTileProvider.html), passing it the collection of `LatLng` objects. Then create a new [`TileOverlay`](https://developers.google.com/android/reference/com/google/android/gms/maps/model/TileOverlay.md.txt), passing it the heatmap tile provider, and add the tile overlay to the map. The utility supplies the `HeatmapTileProvider` class, which implements the [`TileProvider`](https://developers.google.com/android/reference/com/google/android/gms/maps/model/TileProvider.md.txt) interface to supply the tile images for the heatmap. `HeatmapTileProvider` accepts a collection of `LatLng` objects (or [`WeightedLatLng`](http://googlemaps.github.io/android-maps-utils/javadoc/com/google/maps/android/heatmaps/WeightedLatLng.html) objects, as described [below](https://developers.google.com/maps/documentation/android-sdk/utility/heatmap.md.txt#weighted)). It creates the tile images for various zoom levels, based on the radius, gradient and opacity options supplied. You can [change the default values](https://developers.google.com/maps/documentation/android-sdk/utility/heatmap.md.txt#custom) for these options. Looking at the steps in more detail: 1. Use [`HeatmapTileProvider.Builder()`](http://googlemaps.github.io/android-maps-utils/javadoc/com/google/maps/android/heatmaps/HeatmapTileProvider.Builder.html), passing it a collection of `LatLng` objects, to add a new `HeatmapTileProvider`. 2. Create a new [`TileOverlayOptions`](https://developers.google.com/android/reference/com/google/android/gms/maps/model/TileOverlayOptions.md.txt) object with the relevant options, including the `HeatmapTileProvider`. 3. Call [`GoogleMap.addTileOverlay()`](https://developers.google.com/android/reference/com/google/android/gms/maps/GoogleMap.md.txt#addTileOverlay(com.google.android.gms.maps.model.TileOverlayOptions)) to add the overlay to the map. ### Kotlin ```kotlin var latLngs: List? = 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?.filterNotNull() ?: emptyList()) .build() // Add a tile overlay to the map, using the heat map tile provider. val overlay = map.addTileOverlay(TileOverlayOptions().tileProvider(provider)) ``` ### Java ```java List latLngs = new ArrayList<>(); // 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)); ``` 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`](http://googlemaps.github.io/android-maps-utils/javadoc/com/google/maps/android/heatmaps/WeightedLatLng.html) 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()`](https://googlemaps.github.io/android-maps-utils/javadoc/com/google/maps/android/heatmaps/HeatmapTileProvider.Builder.html#weightedData-java.util.Collection-), 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`](http://googlemaps.github.io/android-maps-utils/javadoc/com/google/maps/android/heatmaps/Gradient.html) to set the gradient before adding the heatmap: ### Kotlin ```kotlin // 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), ) ``` ### Java ```java // 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: ### Kotlin ```kotlin provider.setOpacity(0.7) tileOverlay?.clearTileCache() ``` ### Java ```java provider.setOpacity(0.7); tileOverlay.clearTileCache(); ``` ## Change the dataset To change the dataset upon which a heatmap is built, use [`HeatmapTileProvider.setData()`](https://googlemaps.github.io/android-maps-utils/javadoc/com/google/maps/android/heatmaps/HeatmapTileProvider.html#setData-java.util.Collection-), or [`HeatmapTileProvider.setWeightedData()`](https://googlemaps.github.io/android-maps-utils/javadoc/com/google/maps/android/heatmaps/HeatmapTileProvider.html#setWeightedData-java.util.Collection-) 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()`. ### Kotlin ```kotlin val data = latLngs.map { WeightedLatLng(it) } provider.setWeightedData(data) tileOverlay?.clearTileCache() ``` ### Java ```java List data = new ArrayList<>(); for (LatLng latLng : latLngs) { data.add(new WeightedLatLng(latLng)); } provider.setWeightedData(data); tileOverlay.clearTileCache(); ``` ## Remove a heatmap To remove the heatmap, you need to remove the tile overlay: ### Kotlin ```kotlin it.remove() ``` ### Java ```java heatmapTileOverlay.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](https://developers.google.com/maps/documentation/android-sdk/utility/setup.md.txt) shows you how to run the demo app.