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:
- Key Entered: The location of a key now matches the query criteria.
- Key Exited: The location of a key no longer matches the query criteria.
- Key Moved: The location of a key changed but the location still matches the query criteria.
- Query Ready: All current data has been loaded from the server and all
initial events have been fired.
- 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:
- 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
