{"id":13778368,"url":"https://github.com/firebase/geofire-java","last_synced_at":"2025-10-01T22:31:31.099Z","repository":{"id":18585452,"uuid":"21789245","full_name":"firebase/geofire-java","owner":"firebase","description":"GeoFire for Java - Realtime location queries with Firebase","archived":true,"fork":false,"pushed_at":"2020-10-13T06:39:19.000Z","size":694,"stargazers_count":671,"open_issues_count":20,"forks_count":272,"subscribers_count":112,"default_branch":"master","last_synced_at":"2024-09-28T17:01:34.947Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/firebase.png","metadata":{"files":{"readme":"README.md","changelog":"changelog.txt","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-07-13T11:52:36.000Z","updated_at":"2024-08-22T15:24:01.000Z","dependencies_parsed_at":"2022-09-11T19:20:47.398Z","dependency_job_id":null,"html_url":"https://github.com/firebase/geofire-java","commit_stats":null,"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/firebase%2Fgeofire-java","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/firebase%2Fgeofire-java/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/firebase%2Fgeofire-java/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/firebase%2Fgeofire-java/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/firebase","download_url":"https://codeload.github.com/firebase/geofire-java/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":234908980,"owners_count":18905500,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-03T18:00:53.311Z","updated_at":"2025-10-01T22:31:30.789Z","avatar_url":"https://github.com/firebase.png","language":"Java","readme":"# GeoFire for Java — Realtime location queries with Firebase\n\n[![Build Status](https://travis-ci.org/firebase/geofire-java.svg?branch=master)](https://travis-ci.org/firebase/geofire-java?branch=master)\n\n**Note** This library is only for _server side_ Java development. If you want to use GeoFire\nin your Android application, see [`geofire-android`](https://github.com/firebase/geofire-android).\n\nGeoFire is an open-source library for Java that allows you to store and query a\nset of keys based on their geographic location.\n\nAt its heart, GeoFire simply stores locations with string keys. Its main\nbenefit however, is the possibility of querying keys within a given geographic\narea - all in realtime.\n\nGeoFire uses the [Firebase Realtime Database](https://firebase.google.com/products/realtime-database/) database for\ndata storage, allowing query results to be updated in realtime as they change.\nGeoFire *selectively loads only the data near certain locations, keeping your\napplications light and responsive*, even with extremely large datasets.\n\nGeoFire clients are also available for other languages:\n\n  * [Android](https://github.com/firebase/geofire-android)\n  * [Objective-C (iOS)](https://github.com/firebase/geofire-objc)\n  * [JavaScript (Web)](https://github.com/firebase/geofire-js)\n\n### Integrating GeoFire with your data\n\nGeoFire is designed as a lightweight add-on to the Firebase Realtime Database. However, to keep things\nsimple, GeoFire stores data in its own format and its own location within\nyour Firebase database. This allows your existing data format and security rules to\nremain unchanged and for you to add GeoFire as an easy solution for geo queries\nwithout modifying your existing data.\n\n### Example Usage\n\nAssume you are building an app to rate bars and you store all information for a\nbar, e.g. name, business hours and price range, at `/bars/\u003cbar-id\u003e`. Later, you\nwant to add the possibility for users to search for bars in their vicinity. This\nis where GeoFire comes in. You can store the location for each bar using\nGeoFire, using the bar IDs as GeoFire keys. GeoFire then allows you to easily\nquery which bar IDs (the keys) are nearby. To display any additional information\nabout the bars, you can load the information for each bar returned by the query\nat `/bars/\u003cbar-id\u003e`.\n\n\n## Upgrading GeoFire\n\n### Upgrading from GeoFire 1.x to 2.x\n\nGeoFire 2.x is based on the new 3.x release of [Firebase](https://firebase.google.com).\n\n### Upgrading from GeoFire 1.0.x to 1.1.x\n\nWith the release of GeoFire for Android/Java 1.1.0, this library now uses [the new query\nfunctionality found in Firebase 2.0.0](https://www.firebase.com/blog/2014-11-04-firebase-realtime-queries.html).\nAs a result, you will need to upgrade to Firebase 2.x.x and add a new `.indexOn` rule to your\nSecurity and Firebase Rules to get the best performance. You can view [the updated rules\nhere](https://github.com/firebase/geofire-js/blob/master/examples/securityRules/rules.json)\nand [read our docs for more information about indexing your data](https://www.firebase.com/docs/security/guide/indexing-data.html).\n\n\n## Including GeoFire in your Java project\n\nIn order to use GeoFire in your project, you need to [add the Firebase Admin\nSDK](https://firebase.google.com/docs/admin/setup). After that you can include GeoFire with one of the choices below.\n\n### Gradle\n\nAdd a dependency for GeoFire to your `build.gradle` file:\n\n```groovy\ndependencies {\n    implementation 'com.firebase:geofire-java:3.0.0'\n}\n\n```\n\n### Maven\n\nAdd a dependency for GeoFire to your `pom.xml` file:\n\n```xml\n\u003cdependency\u003e\n  \u003cgroupId\u003ecom.firebase\u003c/groupId\u003e\n  \u003cartifactId\u003egeofire-java\u003c/artifactId\u003e\n  \u003cversion\u003e3.0.0\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n## Usage\n\n### GeoFire\n\nA `GeoFire` object is used to read and write geo location data to your Firebase\ndatabase and to create queries. To create a new `GeoFire` instance you need to attach it to a Firebase database\nreference.\n\n```java\nDatabaseReference ref = FirebaseDatabase.getInstance().getReference(\"path/to/geofire\");\nGeoFire geoFire = new GeoFire(ref);\n```\n\nNote that you can point your reference to anywhere in your Firebase database, but don't\nforget to [setup security rules for\nGeoFire](https://github.com/firebase/geofire-js/blob/master/examples/securityRules).\n\n#### Setting location data\n\nIn GeoFire you can set and query locations by string keys. To set a location for\na key simply call the `setLocation` method. The method is passed a key\nas a string and the location as a `GeoLocation` object containing the location's latitude and longitude:\n\n```java\ngeoFire.setLocation(\"firebase-hq\", new GeoLocation(37.7853889, -122.4056973));\n```\n\nTo check if a write was successfully saved on the server, you can add a\n`GeoFire.CompletionListener` to the `setLocation` call:\n\n```java\ngeoFire.setLocation(\"firebase-hq\", new GeoLocation(37.7853889, -122.4056973), new GeoFire.CompletionListener() {\n    @Override\n    public void onComplete(String key, FirebaseError error) {\n        if (error != null) {\n            System.err.println(\"There was an error saving the location to GeoFire: \" + error);\n        } else {\n            System.out.println(\"Location saved on server successfully!\");\n        }\n    }\n});\n```\n\nTo remove a location and delete it from the database simply pass the location's key to `removeLocation`:\n\n```java\ngeoFire.removeLocation(\"firebase-hq\");\n```\n\n#### Retrieving a location\n\nRetrieving a location for a single key in GeoFire happens with callbacks:\n\n```java\ngeoFire.getLocation(\"firebase-hq\", new LocationCallback() {\n    @Override\n    public void onLocationResult(String key, GeoLocation location) {\n        if (location != null) {\n            System.out.println(String.format(\"The location for key %s is [%f,%f]\", key, location.latitude, location.longitude));\n        } else {\n            System.out.println(String.format(\"There is no location for key %s in GeoFire\", key));\n        }\n    }\n\n    @Override\n    public void onCancelled(DatabaseError databaseError) {\n        System.err.println(\"There was an error getting the GeoFire location: \" + databaseError);\n    }\n});\n```\n\n### Geo Queries\n\nGeoFire allows you to query all keys within a geographic area using `GeoQuery`\nobjects. As the locations for keys change, the query is updated in realtime and fires events\nletting you know if any relevant keys have moved. `GeoQuery` parameters can be updated\nlater to change the size and center of the queried area.\n\n```java\n// creates a new query around [37.7832, -122.4056] with a radius of 0.6 kilometers\nGeoQuery geoQuery = geoFire.queryAtLocation(new GeoLocation(37.7832, -122.4056), 0.6);\n```\n\n#### Receiving events for geo queries\n\n##### Key Events\n\nThere are five kinds of \"key\" events that can occur with a geo query:\n\n1. **Key Entered**: The location of a key now matches the query criteria.\n2. **Key Exited**: The location of a key no longer matches the query criteria.\n3. **Key Moved**: The location of a key changed but the location still matches the query criteria.\n4. **Query Ready**: All current data has been loaded from the server and all\n   initial events have been fired.\n5. **Query Error**: There was an error while performing this query, e.g. a\n   violation of security rules.\n\nKey entered events will be fired for all keys initially matching the query as well as any time\nafterwards that a key enters the query. Key moved and key exited events are guaranteed to be\npreceded by a key entered event.\n\nSometimes you want to know when the data for all the initial keys has been\nloaded from the server and the corresponding events for those keys have been\nfired. For example, you may want to hide a loading animation after your data has\nfully loaded. This is what the \"ready\" event is used for.\n\nNote that locations might change while initially loading the data and key moved and key\nexited events might therefore still occur before the ready event is fired.\n\nWhen the query criteria is updated, the existing locations are re-queried and the\nready event is fired again once all events for the updated query have been\nfired. This includes key exited events for keys that no longer match the query.\n\nTo listen for events you must add a `GeoQueryEventListener` to the `GeoQuery`:\n\n```java\ngeoQuery.addGeoQueryEventListener(new GeoQueryEventListener() {\n    @Override\n    public void onKeyEntered(String key, GeoLocation location) {\n        System.out.println(String.format(\"Key %s entered the search area at [%f,%f]\", key, location.latitude, location.longitude));\n    }\n\n    @Override\n    public void onKeyExited(String key) {\n        System.out.println(String.format(\"Key %s is no longer in the search area\", key));\n    }\n\n    @Override\n    public void onKeyMoved(String key, GeoLocation location) {\n        System.out.println(String.format(\"Key %s moved within the search area to [%f,%f]\", key, location.latitude, location.longitude));\n    }\n\n    @Override\n    public void onGeoQueryReady() {\n        System.out.println(\"All initial data has been loaded and events have been fired!\");\n    }\n\n    @Override\n    public void onGeoQueryError(DatabaseError error) {\n        System.err.println(\"There was an error with this query: \" + error);\n    }\n});\n```\n\nYou can call either `removeGeoQueryEventListener` to remove a\nsingle event listener or `removeAllListeners` to remove all event listeners\nfor a `GeoQuery`.\n\n##### Data Events\n\nIf you are storing model data and geo data in the same database location, you may\nwant access to the `DataSnapshot` as part of geo events. In this case, use a\n`GeoQueryDataEventListener` rather than a key listener.\n\nThese \"data event\" listeners have all of the same events as the key listeners with\none additional event type:\n\n  6. **Data Changed**: the underlying `DataSnapshot` has changed. Every \"data moved\"\n     event is followed by a data changed event but you can also get change events without\n     a move if the data changed does not affect the location.\n\nAdding a data event listener is similar to adding a key event listener:\n\n```java\ngeoQuery.addGeoQueryDataEventListener(new GeoQueryDataEventListener() {\n\n  @Override\n  public void onDataEntered(DataSnapshot dataSnapshot, GeoLocation location) {\n    // ...\n  }\n\n  @Override\n  public void onDataExited(DataSnapshot dataSnapshot) {\n    // ...\n  }\n\n  @Override\n  public void onDataMoved(DataSnapshot dataSnapshot, GeoLocation location) {\n    // ...\n  }\n\n  @Override\n  public void onDataChanged(DataSnapshot dataSnapshot, GeoLocation location) {\n    // ...\n  }\n\n  @Override\n  public void onGeoQueryReady() {\n    // ...\n  }\n\n  @Override\n  public void onGeoQueryError(DatabaseError error) {\n    // ...\n  }\n\n});\n\n```\n\n#### Updating the query criteria\n\nThe `GeoQuery` search area can be changed with `setCenter` and `setRadius`. Key\nexited and key entered events will be fired for keys moving in and out of\nthe old and new search area, respectively. No key moved events will be\nfired; however, key moved events might occur independently.\n\nUpdating the search area can be helpful in cases such as when you need to update\nthe query to the new visible map area after a user scrolls.\n\n\n## Deployment\n\n- In your local environment set `$BINTRAY_USER` and `$BINTRAY_KEY` to your\n  Bintray.com username and API key.\n- Checkout and update the master branch.\n- Run `./release.sh` to build and deploy.\n- On bintray.com, publish the draft artifacts.\n```\n","funding_links":[],"categories":["모바일","Helpers"],"sub_categories":["Android"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffirebase%2Fgeofire-java","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffirebase%2Fgeofire-java","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffirebase%2Fgeofire-java/lists"}