{"id":13798660,"url":"https://github.com/MichaelSolati/geofirestore-js","last_synced_at":"2025-05-13T06:31:30.004Z","repository":{"id":38637194,"uuid":"124734843","full_name":"MichaelSolati/geofirestore-js","owner":"MichaelSolati","description":"Location-based querying and filtering using Firebase Firestore.","archived":false,"fork":false,"pushed_at":"2023-11-10T23:38:26.000Z","size":7402,"stargazers_count":506,"open_issues_count":11,"forks_count":58,"subscribers_count":15,"default_branch":"main","last_synced_at":"2025-05-07T17:36:50.060Z","etag":null,"topics":["firebase","firebase-firestore","firestore","geofire","geofirestore","geohashing","geolocation","geoquery","hacktoberfest"],"latest_commit_sha":null,"homepage":"https://geofirestore.com","language":"TypeScript","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/MichaelSolati.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2018-03-11T07:49:32.000Z","updated_at":"2025-04-25T12:33:59.000Z","dependencies_parsed_at":"2023-12-13T05:32:30.041Z","dependency_job_id":"89d8e323-9ffa-49f1-9aaa-a7720b6bfaaf","html_url":"https://github.com/MichaelSolati/geofirestore-js","commit_stats":{"total_commits":735,"total_committers":34,"mean_commits":21.61764705882353,"dds":0.5850340136054422,"last_synced_commit":"97dfb75d9a9173d75cb18aa27bf9be243e01840f"},"previous_names":["geofirestore/geofirestore","geofirestore/geofirestore-js","michaelsolati/geofirestore"],"tags_count":47,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MichaelSolati%2Fgeofirestore-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MichaelSolati%2Fgeofirestore-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MichaelSolati%2Fgeofirestore-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MichaelSolati%2Fgeofirestore-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MichaelSolati","download_url":"https://codeload.github.com/MichaelSolati/geofirestore-js/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253888826,"owners_count":21979511,"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":["firebase","firebase-firestore","firestore","geofire","geofirestore","geohashing","geolocation","geoquery","hacktoberfest"],"created_at":"2024-08-04T00:00:48.994Z","updated_at":"2025-05-13T06:31:29.581Z","avatar_url":"https://github.com/MichaelSolati.png","language":"TypeScript","funding_links":[],"categories":["특집 (신간)"],"sub_categories":[],"readme":"# geofirestore\n\n[![npm](https://img.shields.io/npm/v/geofirestore)](https://www.npmjs.com/package/geofirestore)\n[![npm bundle size](https://img.shields.io/bundlephobia/minzip/geofirestore)](https://bundlephobia.com/result?p=geofirestore)\n[![Release CI](https://github.com/MichaelSolati/geofirestore-js/workflows/Release%20CI/badge.svg)](https://github.com/MichaelSolati/geofirestore-js/actions?query=workflow%3A%22Release+CI%22)\n[![Coveralls github](https://img.shields.io/coveralls/github/MichaelSolati/geofirestore-js)](https://coveralls.io/github/MichaelSolati/geofirestore-js)\n[![GitHub stars](https://img.shields.io/github/stars/MichaelSolati/geofirestore-js)](https://github.com/MichaelSolati/geofirestore-js/stargazers)\n[![GitHub forks](https://img.shields.io/github/forks/MichaelSolati/geofirestore-js)](https://github.com/MichaelSolati/geofirestore-js/network/members)\n\nFull documentation is available at [https://geofirestore.com](https://geofirestore.com).\n\nGeoFirestore is an open-source library that extends the Firestore library in order to store and query documents based on their geographic location. At its heart, GeoFirestore is just a wrapper for the Firestore library, exposing many of the same functions and features of Firestore. Its main benefit, however, is the possibility of retrieving only those documents within a given geographic area - all in realtime.\n\nGeoFirestore uses the [Firebase Cloud Firestore](https://firebase.google.com/docs/firestore/) for data storage, allowing query results to be updated in realtime as they change. GeoFirestore _selectively loads only the data near certain locations, keeping your applications light and responsive_, even with extremely large datasets.\n\nGeoFirestore is designed as a lightweight add-on to Firebase. To keep things simple, GeoFirestore stores data in its own format and its own location within your Firestore database.\n\n## Table of Contents\n\n- [Downloading GeoFirestore](#downloading-geofirestore)\n  - [Firebase Dependencies](#firebase-dependencies)\n- [Example Usage](#example-usage)\n- [Documentation](#documentation)\n- [Limitations \u0026 Considerations](#limitations--considerations)\n  - [Compound Queries](#compound-queries)\n  - [Data Structure](#data-structure)\n    - [Security Rules](#security-rules)\n  - [`limit()`](#limit)\n- [Upgrading](#upgrading)\n- [Contributing](#contributing)\n\n## Downloading GeoFirestore\n\nYou can install GeoFirestore via npm:\n\n```bash\nnpm install geofirestore\n```\n\nOr you can use GeoFirestore via CDN:\n\n```HTML\n\u003cscript src=\"https://unpkg.com/geofirestore/dist/geofirestore.js\"\u003e\u003c/script\u003e\n```\n\n### Firebase Dependencies\n\nIf using this library in a Node.js environment, please install `@google-cloud/firestore` with a version \u003e= 5.0.0 and a version \u003c 6.0.0.\n\nIf using this library in a browser environment, please install `firebase` with a version \u003e= 9.0.0 and a version \u003c 10.0.0. Currently this library only works with the Firebase Compat library. Support for the Firebase Modular library is coming down the road.\n\n## Example Usage\n\nAssume you are building an app to rate bars and you store all information for a bar, e.g. name, business hours and price range, and you want to add the possibility for users to search for bars in their vicinity. This is where GeoFirestore comes in. You can store each bar using GeoFirestore, using the location to build an easily queryable document. GeoFirestore then allows you to easily query which bars are nearby in a simalar fashion as `geofire` but will also return the bar information (not just the key or location).\n\n### Examples\n\nYou can find a full list of our demos and view the code for each of them in the [examples directory](examples/) of this repository. The examples cover some of the common use cases for GeoFirestore.\n\n## Documentation\n\nFull documentation is available at [https://geofirestore.com](https://geofirestore.com). It mostly provides the same functionality as the Firestore library, in almost the same way as the Firestore library. Many questions can be addressed by looking at the [Firestore docs](https://firebase.google.com/docs/firestore/). However there are a few differences, and below is a little example of how to make a location based query.\n\n```TypeScript\nimport firebase from 'firebase/compat/app';\nimport 'firebase/compat/firestore';\nimport * as geofirestore from 'geofirestore';\n\n\n// Initialize the Firebase SDK\nfirebase.initializeApp({\n  // ...\n});\n\n// Create a Firestore reference\nconst firestore = firebase.firestore();\n\n// Create a GeoFirestore reference\nconst GeoFirestore = geofirestore.initializeApp(firestore);\n\n// Create a GeoCollection reference\nconst geocollection = GeoFirestore.collection('restaurants');\n\n// Add a GeoDocument to a GeoCollection\ngeocollection.add({\n  name: 'Geofirestore',\n  score: 100,\n  // The coordinates field must be a GeoPoint!\n  coordinates: new firebase.firestore.GeoPoint(40.7589, -73.9851)\n})\n\n// Create a GeoQuery based on a location\nconst query = geocollection.near({ center: new firebase.firestore.GeoPoint(40.7589, -73.9851), radius: 1000 });\n\n// Get query (as Promise)\nquery.get().then((value) =\u003e {\n  // All GeoDocument returned by GeoQuery, like the GeoDocument added above\n  console.log(value.docs);\n});\n```\n\nSimple. Easy. And very similar with how Firestore handles a `get` from a Firestore `Query`. The difference being the added ability to say query `near` a `center` point, with a set `radius` in kilometers.\n\n## Limitations \u0026 Considerations\n\n### Compound Queries\n\nInternally GeoFirestore creates multiple geohashes around a requested area. It then makes multiple inequality (`\u003c`, `\u003c=`, `\u003e`, `\u003e=`) queries and joins them together into one response. Unfortunately compound queries with inequalities or additional filtering methods such as `orderBy`, `startAt` and `endAt` are impossible with Firestore. To better understand this limitation, see the [Firestore docs here.](https://firebase.google.com/docs/firestore/query-data/queries#compound_queries)\n\n### Data Structure\n\nDocuments generated and stored in your Firestore collection by GeoFirestore are typed/structured as:\n\n```TypeScript\ninterface GeoDocumentData {\n  g: {\n    geohash: string;\n    geopoint: GeoPoint;\n  };\n  [field: string]: any;\n  }\n```\n\n- `g.geohash` is the geohash generated by the library, and is required in order to make the geoqery.\n- `g.geopoint` is the GeoPoint used to generate the `g.geohash` field.\n\nData must be structured this way in order to work, and is why you should use the GeoFirestore library to insert data in order to be able to query it.\n\n#### Security Rules\n\nBecause GeoFirestore adds the `g` field and expects a `coordinates` field, be sure to update your [Firebase Security Rules](https://firebase.google.com/docs/rules) to reflect the new fields. While not necessary for all applications, the rules below are an example of how you'd check for GeoFirestore specific fields.\n\n```CEL\nmatch /collection/{key} {\n  allow write: // Your previous rules here...\n               \u0026\u0026 request.resource.data.g.size() == 2\n               \u0026\u0026 request.resource.data.g.geohash is string\n               \u0026\u0026 request.resource.data.g.geopoint is latlng\n               \u0026\u0026 request.resource.data.coordinates is latlng\n}\n```\n\n### `limit()`\n\nThe `limit` filtering method is exposed through GeoFirestore, however there are some unique considerations when using it. Limits on geoqueries are applied based on the distance from the center. Geoqueries require an aggregation of queries. When performing a geoquery the library applies the limit on the client. This may mean you are loading to the client more documents then you intended. Use with this performance limitation in mind.\n\n## Contributing\n\nAll code should pass tests, as well as be well documented. Please open PRs into the `dev` branch. [Please also see the Commit Message Guidelines](CONTRIBUTING.md) for how commit messages should be structured.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMichaelSolati%2Fgeofirestore-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FMichaelSolati%2Fgeofirestore-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMichaelSolati%2Fgeofirestore-js/lists"}