• Stars
    star
    133
  • Rank 272,600 (Top 6 %)
  • Language
    Java
  • License
    Apache License 2.0
  • Created over 5 years ago
  • Updated about 1 year ago

Reviews

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

Repository Details

GeoFire for Android apps

GeoFire for Android β€” Realtime location queries with Firebase

Actions Status

GeoFire is an open-source library for Android that allows you to store and query a set of keys based on their geographic location.

At its heart, GeoFire simply stores locations with string keys. Its main benefit however, is the possibility of querying keys within a given geographic area - all in realtime.

GeoFire uses the Firebase Realtime Database for data storage, allowing query results to be updated in realtime as they change. GeoFire selectively loads only the data near certain locations, keeping your applications light and responsive, even with extremely large datasets.

GeoFire clients are also available for other languages:

Integrating GeoFire with your data

GeoFire is designed as a lightweight add-on to the Firebase Realtime Database. However, to keep things simple, GeoFire stores data in its own format and its own location within your Firebase database. This allows your existing data format and security rules to remain unchanged and for you to add GeoFire as an easy solution for geo queries without modifying your existing data.

Example Usage

Assume you are building an app to rate bars and you store all information for a bar, e.g. name, business hours and price range, at /bars/<bar-id>. Later, you want to add the possibility for users to search for bars in their vicinity. This is where GeoFire comes in. You can store the location for each bar using GeoFire, using the bar IDs as GeoFire keys. GeoFire then allows you to easily query which bar IDs (the keys) are nearby. To display any additional information about the bars, you can load the information for each bar returned by the query at /bars/<bar-id>.

Including GeoFire in your Android project

In order to use GeoFire in your project, you need to add the Firebase Android SDK. After that you can include GeoFire with one of the choices below.

Add a dependency for GeoFire to your app's build.gradle file.

dependencies {
    // Full GeoFire library for Realtime Database users
    implementation 'com.firebase:geofire-android:3.2.0'

    // GeoFire utililty functions for Cloud Firestore users who
    // want to implement their own geo solution, see:
    // https://firebase.google.com/docs/firestore/solutions/geoqueries
    implementation 'com.firebase:geofire-android-common:3.2.0'
}

Usage

There are two ways to use GeoFire:

  • GeoFire - an end-to-end solution for adding simple geo queries to apps using Firebase Realtime Database.
  • GeoFireUtils - a set of utilities that make it simple to build a geo query solution for any app, such as those using Cloud Firestore.

GeoFire

A GeoFire object is used to read and write geo location data to your Firebase database and to create queries. To create a new GeoFire instance you need to attach it to a Firebase database reference.

DatabaseReference ref = FirebaseDatabase.getInstance().getReference("path/to/geofire");
GeoFire geoFire = new GeoFire(ref);

Note that you can point your reference to anywhere in your Firebase database, but don't forget to setup security rules for GeoFire.

Setting location data

In GeoFire you can set and query locations by string keys. To set a location for a key simply call the setLocation method. The method is passed a key as a string and the location as a GeoLocation object containing the location's latitude and longitude:

geoFire.setLocation("firebase-hq", new GeoLocation(37.7853889, -122.4056973));

To check if a write was successfully saved on the server, you can add a GeoFire.CompletionListener to the setLocation call:

geoFire.setLocation("firebase-hq", new GeoLocation(37.7853889, -122.4056973), new GeoFire.CompletionListener() {
    @Override
    public void onComplete(String key, FirebaseError error) {
        if (error != null) {
            System.err.println("There was an error saving the location to GeoFire: " + error);
        } else {
            System.out.println("Location saved on server successfully!");
        }
    }
});

To remove a location and delete it from the database simply pass the location's key to removeLocation:

geoFire.removeLocation("firebase-hq");

Retrieving a location

Retrieving a location for a single key in GeoFire happens with callbacks:

geoFire.getLocation("firebase-hq", new LocationCallback() {
    @Override
    public void onLocationResult(String key, GeoLocation location) {
        if (location != null) {
            System.out.println(String.format("The location for key %s is [%f,%f]", key, location.latitude, location.longitude));
        } else {
            System.out.println(String.format("There is no location for key %s in GeoFire", key));
        }
    }

    @Override
    public void onCancelled(DatabaseError databaseError) {
        System.err.println("There was an error getting the GeoFire location: " + databaseError);
    }
});

Geo Queries

GeoFire allows you to query all keys within a geographic area using GeoQuery objects. As the locations for keys change, the query is updated in realtime and fires events letting you know if any relevant keys have moved. GeoQuery parameters can be updated later to change the size and center of the queried area.

// creates a new query around [37.7832, -122.4056] with a radius of 0.6 kilometers
GeoQuery geoQuery = geoFire.queryAtLocation(new GeoLocation(37.7832, -122.4056), 0.6);

Receiving events for geo queries

Key Events

There are five kinds of "key" events that can occur with a geo query:

  1. Key Entered: The location of a key now matches the query criteria.
  2. Key Exited: The location of a key no longer matches the query criteria.
  3. Key Moved: The location of a key changed but the location still matches the query criteria.
  4. Query Ready: All current data has been loaded from the server and all initial events have been fired.
  5. Query Error: There was an error while performing this query, e.g. a violation of security rules.

Key entered events will be fired for all keys initially matching the query as well as any time afterwards that a key enters the query. Key moved and key exited events are guaranteed to be preceded by a key entered event.

Sometimes you want to know when the data for all the initial keys has been loaded from the server and the corresponding events for those keys have been fired. For example, you may want to hide a loading animation after your data has fully loaded. This is what the "ready" event is used for.

Note that locations might change while initially loading the data and key moved and key exited events might therefore still occur before the ready event is fired.

When the query criteria is updated, the existing locations are re-queried and the ready event is fired again once all events for the updated query have been fired. This includes key exited events for keys that no longer match the query.

To listen for events you must add a GeoQueryEventListener to the GeoQuery:

geoQuery.addGeoQueryEventListener(new GeoQueryEventListener() {
    @Override
    public void onKeyEntered(String key, GeoLocation location) {
        System.out.println(String.format("Key %s entered the search area at [%f,%f]", key, location.latitude, location.longitude));
    }

    @Override
    public void onKeyExited(String key) {
        System.out.println(String.format("Key %s is no longer in the search area", key));
    }

    @Override
    public void onKeyMoved(String key, GeoLocation location) {
        System.out.println(String.format("Key %s moved within the search area to [%f,%f]", key, location.latitude, location.longitude));
    }

    @Override
    public void onGeoQueryReady() {
        System.out.println("All initial data has been loaded and events have been fired!");
    }

    @Override
    public void onGeoQueryError(DatabaseError error) {
        System.err.println("There was an error with this query: " + error);
    }
});

You can call either removeGeoQueryEventListener to remove a single event listener or removeAllListeners to remove all event listeners for a GeoQuery.

Data Events

If you are storing model data and geo data in the same database location, you may want access to the DataSnapshot as part of geo events. In this case, use a GeoQueryDataEventListener rather than a key listener.

These "data event" listeners have all of the same events as the key listeners with one additional event type:

  1. Data Changed: the underlying DataSnapshot has changed. Every "data moved" event is followed by a data changed event but you can also get change events without a move if the data changed does not affect the location.

Adding a data event listener is similar to adding a key event listener:

geoQuery.addGeoQueryDataEventListener(new GeoQueryDataEventListener() {

  @Override
  public void onDataEntered(DataSnapshot dataSnapshot, GeoLocation location) {
    // ...
  }

  @Override
  public void onDataExited(DataSnapshot dataSnapshot) {
    // ...
  }

  @Override
  public void onDataMoved(DataSnapshot dataSnapshot, GeoLocation location) {
    // ...
  }

  @Override
  public void onDataChanged(DataSnapshot dataSnapshot, GeoLocation location) {
    // ...
  }

  @Override
  public void onGeoQueryReady() {
    // ...
  }

  @Override
  public void onGeoQueryError(DatabaseError error) {
    // ...
  }

});

Updating the query criteria

The GeoQuery search area can be changed with setCenter and setRadius. Key exited and key entered events will be fired for keys moving in and out of the old and new search area, respectively. No key moved events will be fired; however, key moved events might occur independently.

Updating the search area can be helpful in cases such as when you need to update the query to the new visible map area after a user scrolls.

GeoFireUtils

The geofire-android-common library provides the GeoFireUtils class which contains utilities for working with geohashes but has no dependency on or integration with a specific database. The GeoFireUtils class contains the following utility methods:

  • String getGeoHashForLocation(@NonNull GeoLocation location) - compute the geohash string for a given (lat,lng) par with default precision.
  • String getGeoHashForLocation(@NonNull GeoLocation location, int precision) - compute the geohash string for a given (lat, lng) pair with custom precision.
  • double getDistanceBetween(@NonNull GeoLocation a, @NonNull GeoLocation b) - compute the distance, in kilometers, between two locations.
  • List<GeoQueryBounds> getGeoHashQueryBounds(@NonNull GeoLocation location, double radius) - given a center point and a radius distance, compute a set of query bounds that can be joined to find all points within the radius distance of the center.

For a detailed guide on how to use these utilities to add geo querying capabilities to your Cloud Firestore app, see: https://firebase.google.com/docs/firestore/solutions/geoqueries

Publishing

Versioning

We use SemVer in this project.

When you bump a version, be sure to update:

Credentials

The library is published to Maven Central by the firebase-sonatype account, Googlers can find the password for this account in Valentine

GPG Key

You will need to create a private GPG keyring on your machine, if you don't have one do the following steps:

  1. Run gpg --full-generate-key
  2. Choose RSA and RSA for the key type
  3. Use 4096 for the key size
  4. Use 0 for the expiration (never)
  5. Use any name, email address, and password

This creates your key in ~/.gnupg/openpgp-revocs.d/ with .rev format. The last 8 characters before the .rev extension are your Key ID.

To export the key, run:

gpg --export-secret-keys -o $HOME/sonatype.gpg

Finally upload your key to the keyserver:

gpg --keyserver hkp://keys.openpgp.org --send-keys <YOUR KEY ID>

Local Properties

Open your $HOME/.gradle/gradle.properties file at and fill in the values:

signing.keyId=<KEY ID>
signing.password=<PASSWORD YOU CHOSE>
signing.secretKeyRingFile=<FULL PATH TO YOUR GPG FILE>
mavenCentralRepositoryUsername=firebase-sonatype
mavenCentralRepositoryPassword=<PASSWORD FROM VALENTINE>

Publish

To publish, run:

./gradlew publish

Release

Follow the instructions here:

  1. Navigate to https://oss.sonatype.org/ and Log In
  2. On the left side menu, click Staging Repositories (under Build Promotion) and look for the com.firebase repo
  3. You should see it with the Open status. Click Close and wait a few minutes (you can check status by clicking Refresh)
  4. Once the status changes to Closed, click Release

More Repositories

1

functions-samples

Collection of sample apps showcasing popular use cases using Cloud Functions for Firebase
JavaScript
12,063
star
2

flutterfire

πŸ”₯ A collection of Firebase plugins for Flutter apps.
Dart
8,671
star
3

quickstart-android

Firebase Quickstart Samples for Android
Java
8,563
star
4

firebase-js-sdk

Firebase Javascript SDK
TypeScript
4,830
star
5

quickstart-js

Firebase Quickstart Samples for Web
HTML
4,818
star
6

FirebaseUI-Android

Optimized UI components for Firebase
Java
4,628
star
7

firebaseui-web

FirebaseUI is an open-source JavaScript library for Web that provides simple, customizable UI bindings on top of Firebase SDKs to eliminate boilerplate code and promote best practices.
JavaScript
4,558
star
8

firebase-tools

The Firebase Command Line Tools
TypeScript
3,994
star
9

firebase-ios-sdk

Firebase iOS SDK
Objective-C
3,583
star
10

quickstart-ios

Firebase Quickstart Samples for iOS
Swift
2,773
star
11

firebase-android-sdk

Firebase Android SDK
Java
2,244
star
12

codelab-friendlychat-web

The source for the Firebase codelab for building a cross-platform chat app
JavaScript
1,749
star
13

firebase-admin-node

Firebase Admin Node.js SDK
TypeScript
1,621
star
14

FirebaseUI-iOS

iOS UI bindings for Firebase.
Objective-C
1,507
star
15

geofire-js

GeoFire for JavaScript - Realtime location queries with Firebase
TypeScript
1,443
star
16

firebaseui-web-react

React Wrapper for firebaseUI Web
JavaScript
1,262
star
17

firebase-admin-go

Firebase Admin Go SDK
Go
1,142
star
18

superstatic

Superstatic: a static file server for fancy apps.
JavaScript
1,097
star
19

firebase-functions

Firebase SDK for Cloud Functions
TypeScript
1,024
star
20

firebase-admin-python

Firebase Admin Python SDK
Python
1,019
star
21

quickstart-nodejs

JavaScript
895
star
22

extensions

Source code for official Firebase extensions
TypeScript
892
star
23

quickstart-unity

Firebase Quickstart Samples for Unity
C#
775
star
24

snippets-android

Android snippets for firebase.google.com
Java
762
star
25

snippets-web

Web snippets for firebase.google.com
JavaScript
749
star
26

genkit

An open source framework for building AI-powered apps with familiar code-centric patterns. Genkit makes it easy to develop, integrate, and test AI features with observability and evaluations. Genkit works with various models and platforms.
TypeScript
701
star
27

geofire-java

GeoFire for Java - Realtime location queries with Firebase
Java
671
star
28

firebase-admin-java

Firebase Admin Java SDK
Java
527
star
29

friendlyeats-web

JavaScript
467
star
30

geofire-objc

GeoFire for Objective-C - Realtime location queries with Firebase
Objective-C
440
star
31

snippets-node

Node.js snippets for firebase.google.com
JavaScript
369
star
32

firebase-admin-dotnet

Firebase Admin .NET SDK
C#
367
star
33

quickstart-testing

Samples demonstrating how to test your Firebase app
TypeScript
335
star
34

firebase-tools-ui

A local-first UI for Firebase Emulator Suite.
TypeScript
269
star
35

friendlyeats-android

Cloud Firestore Android codelab
Kotlin
261
star
36

codelab-friendlychat-android

Firebase FriendlyChat codelab
Kotlin
243
star
37

firebase-cpp-sdk

Firebase C++ SDK
C++
230
star
38

quickstart-java

Quickstart samples for Firebase Java Admin SDK
Java
224
star
39

firebase-functions-test

TypeScript
211
star
40

quickstart-cpp

Firebase Quickstart Samples for C++
C++
190
star
41

fastlane-plugin-firebase_app_distribution

fastlane plugin for Firebase App Distribution. https://firebase.google.com/docs/app-distribution
Ruby
166
star
42

friendlypix-ios

Friendly Pix iOS is a sample app demonstrating how to build an iOS app with the Firebase Platform.
Swift
166
star
43

quickstart-flutter

Dart
138
star
44

firebase-functions-python

Python
136
star
45

firebase-unity-sdk

The Firebase SDK for Unity
C#
128
star
46

friendlyeats-ios

Swift
127
star
47

snippets-ios

iOS snippets used in firebase.google.com
Objective-C
121
star
48

firebaseopensource.com

Source for firebase open source site
TypeScript
118
star
49

quickstart-python

Jupyter Notebook
115
star
50

FirebaseUI-Flutter

Dart
102
star
51

codelab-friendlychat-ios

Swift
68
star
52

snippets-rules

Snippets for security rules on firebase.google.com
TypeScript
45
star
53

emulators-codelab

JavaScript
44
star
54

oss-bot

Robot friend for open source repositories
TypeScript
36
star
55

firebase-bower

Firebase Web Client
JavaScript
35
star
56

snippets-flutter

Dart
30
star
57

snippets-go

Golang snippets for firebase docs
Go
24
star
58

snippets-java

Java snippets for firebase.google.com
Java
17
star
59

firebase-docs

TypeScript
16
star
60

abseil-cpp-SwiftPM

C++
13
star
61

firebase-testlab-instr-lib

Java
13
star
62

snippets-cpp

C++ snippets for firebase.google.com
C++
12
star
63

SpecsStaging

SpecsStaging
11
star
64

SpecsTesting

Ruby
11
star
65

rtdb-to-csv

JavaScript
11
star
66

appquality-codelab-ios

Firebase iOS App Quality Codelab
Objective-C
11
star
67

level-up-with-firebase

C#
9
star
68

boringSSL-SwiftPM

C++
8
star
69

firestore-bundle-builder

TypeScript
7
star
70

.github

Default configuration for Firebase repos
6
star
71

nginx

This repo is a PUBLIC FORK
C
6
star
72

SpecsDev

6
star
73

snippets-python

Python snippets for firebase.google.com
4
star
74

firebase-release-dashboard

JavaScript
4
star
75

ok

HTTPS CDN Proxy Healthy Check
4
star
76

grpc-SwiftPM

C++
3
star
77

crashlytics-testapps

Java
2
star
78

data-connect-ios-sdk

Swift
2
star
79

.allstar

1
star