prathmesh16 / android-maps-utils

Maps SDK for Android Utility Library

Maps SDK for Android Utility Library

Description

This open-source library contains utilities that are useful for a wide range of applications using the Google Maps Android API.

• Marker clustering — handles the display of a large number of points
• Heat maps — display a large number of points as a heat map
• IconGenerator — display text on your Markers
• Poly decoding and encoding — compact encoding for paths, interoperability with Maps API web services
• Spherical geometry — for example: computeDistance, computeHeading, computeArea
• KML — displays KML data
• GeoJSON — displays and styles GeoJSON data

You can also find Kotlin extensions for this library here.

Developer Documentation

You can view the generated reference docs for a full list of classes and their methods.

Requirements

• Android API level 15+
• Maps SDK via Google Play Services (this library is not yet compatible with the Maps SDK v3.0 BETA library)

Installation

dependencies {
    implementation 'com.google.maps.android:android-maps-utils:1.2.1'
}

Demo App

This repository includes a demo app that illustrates the use of this library.

To run the demo app, you'll have to:

1. Get a Maps API key
2. Create a file in the demo directory called secure.properties (this file should NOT be under version control to protect your API key)
3. Add a single line to demo/secure.properties that looks like MAPS_API_KEY=YOUR_API_KEY, where YOUR_API_KEY is the API key you obtained in the first step
4. Build and run

Migration Guide

Improvements made in version 1.0.0 of the library to support multiple layers on the map caused breaking changes to versions prior to it. These changes also modify behaviors that are documented in the Maps SDK for Android Maps documentation site. This section outlines all those changes and how you can migrate to use this library since version 1.0.0.

Adding Click Events

Click events originate in the layer-specific object that added the marker/ground overlay/polyline/polygon. In each layer, the click handlers are passed to the marker, ground overlay, polyline, or polygon Collection object.

// Clustering
ClusterManager<ClusterItem> clusterManager = // Initialize ClusterManager
clusterManager.setOnClusterItemClickListener(item -> {
    // Listen for clicks on a cluster item here
    return false;
});
clusterManager.setOnClusterClickListener(item -> {
    // Listen for clicks on a cluster here
    return false;
});

// GeoJson
GeoJsonLayer geoJsonLayer = // Initialize GeoJsonLayer
geoJsonLayer.setOnFeatureClickListener(feature -> {
    // Listen for clicks on GeoJson features here
});

// KML
KmlLayer kmlLayer = // Initialize KmlLayer
kmlLayer.setOnFeatureClickListener(feature -> {
    // Listen for clicks on KML features here
});

Using Manager Objects

If you use one of Manager objects in the package com.google.maps.android (e.g. GroundOverlayManager, MarkerManager, etc.), say from adding a KML or GeoJson layer, you will have to rely on the Collection specific to add add object to the map rather than adding that object directly to GoogleMap. This is because each Manager sets itself as a click listener so that it can manager click events coming from multiple layers.

For example, if you have additional GroundOverlay objects:

New

GroundOverlayManager groundOverlayManager = // Initialize 

// Create a new collection first
GroundOverlayManager.Collection groundOverlayCollection = groundOverlayManager.newCollection();

// Add a new ground overlay
GroundOverlayOptions options = // ...
groundOverlayCollection.addGroundOverlay(options);

Old

GroundOverlayOptions options = // ...
googleMap.addGroundOverlay(options);

This same pattern applies for Marker, Circle, Polyline, and Polygon.

Adding a Custom Info Window

If you use MarkerManager, adding an InfoWindowAdapter and/or an OnInfoWindowClickListener should be done on the MarkerManager.Collection object.

New

CustomInfoWindowAdapter adapter = // ...
OnInfoWindowClickListener listener = // ...

// Create a new Collection from a MarkerManager
MarkerManager markerManager = // ...
MarkerManager.Collection collection = markerManager.newCollection();

// Set InfoWindowAdapter and OnInfoWindowClickListener
collection.setInfoWindowAdapter(adapter);
collection.setOnInfoWindowClickListener(listener);

// Alternatively, if you are using clustering
ClusterManager<ClusterItem> clusterManager = // ...
MarkerManager.Collection markerCollection = markerCollection.setInfoWindowAdapter(adapter);
markerCollection.setOnInfoWindowClickListener(listener);

Old

CustomInfoWindowAdapter adapter = // ...
OnInfoWindowClickListener listener = // ...
googleMap.setInfoWindowAdapter(adapter);
googleMap.setOnInfoWindowClickListener(listener);

Adding a Marker Drag Listener

If you use MarkerManager, adding an OnMarkerDragListener should be done on the MarkerManager.Collection object.

New

// Create a new Collection from a MarkerManager
MarkerManager markerManager = // ...
MarkerManager.Collection collection = markerManager.newCollection();

// Add markers to collection
MarkerOptions markerOptions = // ...
collection.addMarker(markerOptions);
// ...

// Set OnMarkerDragListener
GoogleMap.OnMarkerDragListener listener = // ...
collection.setOnMarkerDragListener(listener);

// Alternatively, if you are using clustering
ClusterManager<ClusterItem> clusterManager = // ...
MarkerManager.Collection markerCollection = clusterManager.getMarkerCollection();
markerCollection.setOnMarkerDragListener(listener);

Old

// Add markers
MarkerOptions markerOptions = // ...
googleMap.addMarker(makerOptions);

// Add listener
GoogleMap.OnMarkerDragListener listener = // ...
googleMap.setOnMarkerDragListener(listener);

Support

Encounter an issue while using this library?

If you find a bug or have a feature request, please file an issue. Or, if you'd like to contribute, send us a pull request and refer to our code of conduct.

You can also reach us on our Discord channel.

For more information, check out the detailed guide on the Google Developers site.