• Stars
    star
    3,545
  • Rank 12,518 (Top 0.3 %)
  • Language
    Java
  • License
    Apache License 2.0
  • Created over 11 years ago
  • Updated 2 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Maps SDK for Android Utility Library

Build Status Maven Central GitHub contributors Discord Apache-2.0

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 SDK for Android.

  • Marker clustering — handles the display of a large number of points
  • Marker animation - animates a marker from one position to another
  • 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

The generated reference docs for a full list of classes and their methods.

Written guides for using the utilities are published in Google Maps Platform documentation.

Requirements

Installation

dependencies {
    // Utilities for Maps SDK for Android (requires Google Play Services)
    implementation 'com.google.maps.android:android-maps-utils:3.4.0'
}

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. Open the file local.properties in the root project (this file should NOT be under version control to protect your API key)
  3. Add a single line to local.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 the debug variant for the Maps SDK for Android version
Migration Guide from v0.x to 1.0

Migration Guide from v0.x to 1.0

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 - if you're using multiple maps features, use the constructor that passes in Manager objects (see next section)
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 - if you're using multiple maps features, use the constructor that passes in Manager objects (see next section)
geoJsonLayer.setOnFeatureClickListener(feature -> {
    // Listen for clicks on GeoJson features here
});

// KML
KmlLayer kmlLayer = // Initialize KmlLayer - if you're using multiple maps features, use the constructor that passes in Manager objects (see next section)
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 layer, GeoJson layer, or Clustering, you will have to rely on the Collection specific to add an 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 manage 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 = clusterManager.getMarkerCollection();
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);

Clustering

A bug was fixed in v1 to properly clear and re-add markers via the ClusterManager.

For example, this didn't work pre-v1, but works for v1 and later:

clusterManager.clearItems();
clusterManager.addItems(items);
clusterManager.cluster();

If you're using custom clustering (i.e, if you're extending DefaultClusterRenderer), you must override two additional methods in v1:

  • onClusterItemUpdated() - should be the same* as your onBeforeClusterItemRendered() method
  • onClusterUpdated() - should be the same* as your onBeforeClusterRendered() method

*Note that these methods can't be identical, as you need to use a Marker instead of MarkerOptions

See the CustomMarkerClusteringDemoActivity in the demo app for a complete example.

New

    private class PersonRenderer extends DefaultClusterRenderer<Person> {
        ...
        @Override
        protected void onBeforeClusterItemRendered(Person person, MarkerOptions markerOptions) {
            // Draw a single person - show their profile photo and set the info window to show their name
            markerOptions
                    .icon(getItemIcon(person))
                    .title(person.name);
        }

        /**
         * New in v1
         */
        @Override
        protected void onClusterItemUpdated(Person person, Marker marker) {
            // Same implementation as onBeforeClusterItemRendered() (to update cached markers)
            marker.setIcon(getItemIcon(person));
            marker.setTitle(person.name);
        }

        @Override
        protected void onBeforeClusterRendered(Cluster<Person> cluster, MarkerOptions markerOptions) {
            // Draw multiple people.
            // Note: this method runs on the UI thread. Don't spend too much time in here (like in this example).
            markerOptions.icon(getClusterIcon(cluster));
        }

        /**
         * New in v1
         */
        @Override
        protected void onClusterUpdated(Cluster<Person> cluster, Marker marker) {
            // Same implementation as onBeforeClusterRendered() (to update cached markers)
            marker.setIcon(getClusterIcon(cluster));
        }
        ...
    }

Old

    private class PersonRenderer extends DefaultClusterRenderer<Person> {
        ...
        @Override
        protected void onBeforeClusterItemRendered(Person person, MarkerOptions markerOptions) {
            // Draw a single person - show their profile photo and set the info window to show their name
            markerOptions
                    .icon(getItemIcon(person))
                    .title(person.name);
        }

        @Override
        protected void onBeforeClusterRendered(Cluster<Person> cluster, MarkerOptions markerOptions) {
            // Draw multiple people.
            // Note: this method runs on the UI thread. Don't spend too much time in here (like in this example).
            markerOptions.icon(getClusterIcon(cluster));
        }
        ...
    }

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.

More Repositories

1

google-maps-services-python

Python client library for Google Maps API Web Services
Python
4,501
star
2

google-maps-services-js

Node.js client library for Google Maps API Web Services
TypeScript
2,888
star
3

android-samples

Samples demonstrating how to use Maps SDK for Android
Java
2,351
star
4

google-maps-services-java

Java client library for Google Maps API Web Services
Java
1,708
star
5

android-maps-compose

Jetpack Compose composables for the Maps SDK for Android
Kotlin
1,143
star
6

v3-utility-library

Utility libraries for Google Maps JavaScript API v3
JavaScript
1,097
star
7

js-samples

Samples for the Google Maps JavaScript v3 API
TypeScript
741
star
8

google-maps-services-go

Go client library for Google Maps API Web Services
Go
739
star
9

google-maps-ios-utils

Google Maps SDK for iOS Utility Library
Objective-C
714
star
10

transport-tracker

Applications for tracking moving assets on a live map
JavaScript
570
star
11

react-wrapper

Wrap React components with this libary to load the Google Maps JavaScript API.
TypeScript
369
star
12

js-api-loader

Load the Google Maps JavaScript API script dynamically.
TypeScript
337
star
13

android-maps-ktx

Kotlin extensions (KTX) for the Maps SDK and Utility Library for Android
Kotlin
323
star
14

maps-sdk-for-ios-samples

Samples for the Google Maps and Places SDKs for iOS
Objective-C
259
star
15

js-markerclusterer

Create and manage clusters for large amounts of markers
TypeScript
214
star
16

android-places-demos

Google Places SDK Demos for Android
Java
167
star
17

js-three

Add ThreeJS objects to Google Maps.
TypeScript
152
star
18

extended-component-library

A set of Web Components from Google Maps Platform
TypeScript
125
star
19

roads-api-samples

Sample Android app demonstrating usage of the GMP Roads API
Java
116
star
20

openapi-specification

OpenAPI specification for Google Maps Platform API
TypeScript
100
star
21

js-markerclustererplus

TypeScript
98
star
22

android-places-ktx

Kotlin extensions (KTX) for the Places SDK for Android
Kotlin
95
star
23

js-route-optimization-app

Solve vehicle routing problems with Google Optimization AI Cloud Fleet Routing
TypeScript
90
star
24

property-finder

A turnkey solution for a fictitious real estate business
Python
79
star
25

js-markerwithlabel

Google Maps Marker with Label
TypeScript
75
star
26

deck.gl-demos

Examples showing how to use Google Maps Platform with deck.gl
JavaScript
69
star
27

js-polyline-codec

Polyline encoding and decoding.
TypeScript
57
star
28

last-mile-fleet-solution-samples

Java
56
star
29

ios-maps-sdk

Google Maps SDK for iOS
Swift
52
star
30

url-signing

Samples in various languages that demonstrate how to sign URLs for Google Maps Platform Web Services APIs
HTML
45
star
31

js-jest-mocks

Jest mocks for Google Maps Platform
TypeScript
33
star
32

nyc-subway-station-locator

NYC Subway Station Locator Solution
Go
31
star
33

python-high-volume-address-validation-library

Python
30
star
34

react-native-navigation-sdk

Java
25
star
35

android-on-demand-rides-deliveries-samples

Kotlin
24
star
36

android-maps-rx

RxJava bindings for the Maps and Places SDKs for Android
Kotlin
21
star
37

flutter-navigation-sdk

Dart
21
star
38

js-typescript-guards

TypeScript guards for the Google Maps JavaScript API.
TypeScript
20
star
39

fleet-debugger

JavaScript
20
star
40

gaming-services-samples

Example games that use Google Maps Platform gaming services.
C#
20
star
41

js-map-loader

A simple JavaScript/TypeScript utility for adding a Google Map to webpages programmatically.
TypeScript
19
star
42

ios-on-demand-rides-deliveries-samples

Objective-C
17
star
43

js-markermanager

Marker manager is an interface between the map and the user, designed to manage adding and removing many points when the viewport changes.
TypeScript
16
star
44

on-demand-rides-deliveries-samples

15
star
45

ios-combine

Combine extensions for Maps and Places SDKs for iOS
Swift
15
star
46

js-ogc

Add a WmsMapType to Google Maps
TypeScript
14
star
47

.github

Default configurations for googlemaps repositories
12
star
48

js-adv-markers-utils

TypeScript
11
star
49

java-on-demand-rides-deliveries-stub-provider

Java
11
star
50

android-v3-migration

Migration tool for V3 BETA Maps SDK to Google Play services Maps SDK
Kotlin
11
star
51

react-last-mile-fleet-solution-samples

TypeScript
11
star
52

java-fleetengine-auth

Java
10
star
53

ios-places-sdk

Swift
10
star
54

react-on-demand-rides-deliveries-samples

TypeScript
10
star
55

react-routing-playground

JavaScript
9
star
56

go-routespreferred

Go idiomatic client for Google Maps Platform Routes API.
9
star
57

js-url-signature

Sign a URL for Google Maps Platform requests.
TypeScript
9
star
58

js-types

Automatically generated types for the Google Maps Platform JavaScript API
Starlark
8
star
59

angular-on-demand-rides-deliveries-samples

TypeScript
7
star
60

gmp-firebase-extensions

TypeScript
6
star
61

ios-navigation-sdk

Swift
6
star
62

eslint-plugin-googlemaps

ESLint rules for Google Maps Platform.
TypeScript
6
star
63

fleet-events-reference-solution

Java
6
star
64

semantic-release-config

Shareable configuration for semantic release.
JavaScript
5
star
65

codelab-maps-platform-101-swift

Companion code for the Add a map to your iOS app (Swift) codelab
Swift
5
star
66

codelab-places-101-android-kotlin

Companion code for the Get started with the Places SDK for Android (Kotlin) codelab
Kotlin
4
star
67

playablelocations-proxy

A proxy implementation for the Playable Locations API.
Go
4
star
68

js-region-lookup

TypeScript
4
star
69

js-github-policy-bot

Enforce polices for repositories in the googlemaps organization.
TypeScript
3
star
70

ios-consumer-sdk

Swift
3
star
71

android-places-compose

Kotlin
3
star
72

ios-places-swift-sdk

Swift
3
star
73

go-routespreferred-samples

Routes Preferred Samples in Go
Go
2
star
74

googlemaps.github.io

A page listing Google maintained GMP libraries as well as external ones.
HTML
2
star
75

java-routespreferred-samples

Samples for Routes Preferred
Java
2
star
76

eslint-config-googlemaps

Shareable ESLint style configuration for Google Maps repositories.
TypeScript
1
star
77

ios-driver-sdk

Swift
1
star
78

java-routespreferred

Java idiomatic client for Google Maps Platform Routes Preferred API.
Java
1
star
79

.allstar

1
star