Google Maps Android Utility Library

To display complex data (like KML or GeoJSON) on a GoogleMap, follow this workflow:

1. Initialize the Renderer: Create a Renderer instance and associate it with your GoogleMap object.
2. Parse Data: Use a DataParser (e.g., KmlParser or GeoJsonParser) to parse your data source (such as an InputStream) into a structured in-memory representation.
3. Map to Layers: Pass the parsed data to a Mapper (e.g., KmlMapper or GeoJsonMapper). This converts the format-specific data into a Layer containing generic MapObjects.
4. Add to Renderer: Add the resulting Layer to the Renderer using addLayer(layer).

The Renderer will then automatically handle drawing the MapObjects (such as MarkerObject, PolylineObject, PolygonObject, or CircleObject) onto the map.

Use ClusterManager to manage multiple markers at different zoom levels.

1. Create a class that implements ClusterItem.
2. Initialize a ClusterManager within the onMapReady callback.
3. Link the map's listeners to the manager: map.setOnCameraIdleListener(clusterManager) and map.setOnMarkerClickListener(clusterManager).
4. Add items to the cluster using clusterManager.addItem(item).

Use PolyUtil and SphericalUtil for coordinate manipulation and geometry calculations.

• Decoding: Use PolyUtil.decode(encodedPathString) to convert an encoded string into a list of LatLng points.
• Distance: Use SphericalUtil.computeDistanceBetween(latLng1, latLng2) to calculate the distance between two points.

Import geographic data from raw resource files using GeoJsonLayer or KmlLayer.

• GeoJSON: val layer = GeoJsonLayer(map, R.raw.geojson_file, context); layer.addLayerToMap()
• KML: val layer = KmlLayer(map, R.raw.kml_file, context); layer.addLayerToMap()

// GeoJSON
val layer = GeoJsonLayer(map, R.raw.geojson_file, context)
layer.addLayerToMap()

// KML
val layer = KmlLayer(map, R.raw.kml_file, context)
layer.addLayerToMap()

In v5.x, the ClusterItem interface is written in idiomatic Kotlin. When creating custom cluster item classes (like data classes), you should now use the override keyword directly in the constructor for the properties position, title, snippet, and zIndex. This replaces the need for manual getter method overrides used in v4.x.

// After (v5.x Idiomatic Kotlin)
data class MyItem(
    override val position: LatLng,
    override val title: String?,
    override val snippet: String?,
    override val zIndex: Float?
) : ClusterItem

Represent data point density using HeatmapTileProvider.

1. Prepare a Collection<LatLng> or Collection<WeightedLatLng>.
2. Build the provider: HeatmapTileProvider.Builder().data(list).build().
3. Add the overlay to the map: map.addTileOverlay(TileOverlayOptions().tileProvider(provider)).

The data module provides parsers to convert raw file formats into intermediate objects, which can then be mapped into a unified DataLayer using specific mappers. This allows you to treat different geospatial formats identically once they are in the internal model.

// Load KML
val kml = KmlParser().parse(inputStream)
val kmlLayer = KmlMapper.toLayer(kml)

// Load GeoJSON
val geoJson = GeoJsonParser().parse(inputStream)
val geoJsonLayer = GeoJsonMapper.toLayer(geoJson)

// Load GPX
val gpx = GpxParser().parse(inputStream)
val gpxLayer = GpxMapper.toLayer(gpx)

Add the following dependency to your app-level build.gradle.kts file to use the utility library features.

dependencies {
    // Google Maps Utility Library
    implementation("com.google.maps.android:android-maps-utils:5.0.0")
}

Use MapViewRenderer to render a DataLayer onto a GoogleMap. The renderer handles the lifecycle of adding and removing map elements like Markers, Polylines, Polygons, and GroundOverlays. You can provide an IconProvider (such as UrlIconProvider) to handle asynchronous icon loading via Coroutines.

// Initialize Renderer
val renderer = MapViewRenderer(googleMap, UrlIconProvider(lifecycleScope))

// Add Layer
renderer.addLayer(kmlLayer)

// Remove Layer
renderer.removeLayer(kmlLayer)

// Enable Advanced Markers
renderer.useAdvancedMarkers = true