{"id":15485899,"url":"https://github.com/codediodeio/geofirex","last_synced_at":"2025-04-12T14:56:37.479Z","repository":{"id":32699849,"uuid":"140211113","full_name":"codediodeio/geofirex","owner":"codediodeio","description":":globe_with_meridians: :round_pushpin: Geolocation Queries with Firestore \u0026 RxJS ","archived":false,"fork":false,"pushed_at":"2023-01-09T12:00:32.000Z","size":2410,"stargazers_count":483,"open_issues_count":110,"forks_count":107,"subscribers_count":19,"default_branch":"master","last_synced_at":"2025-04-03T14:11:04.645Z","etag":null,"topics":["firebase","firestore","geojson","geolocation","rxjs"],"latest_commit_sha":null,"homepage":"https://geo-test-c92e4.firebaseapp.com/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/codediodeio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-07-08T23:56:50.000Z","updated_at":"2025-04-01T17:17:38.000Z","dependencies_parsed_at":"2023-01-14T21:58:22.820Z","dependency_job_id":null,"html_url":"https://github.com/codediodeio/geofirex","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codediodeio%2Fgeofirex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codediodeio%2Fgeofirex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codediodeio%2Fgeofirex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codediodeio%2Fgeofirex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/codediodeio","download_url":"https://codeload.github.com/codediodeio/geofirex/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248586248,"owners_count":21128996,"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","firestore","geojson","geolocation","rxjs"],"created_at":"2024-10-02T06:04:33.709Z","updated_at":"2025-04-12T14:56:37.460Z","avatar_url":"https://github.com/codediodeio.png","language":"TypeScript","readme":"\u003cp align=\"center\"\u003e\n\n\u003ca href=\"https://slackin-pbfjhfxnsa.now.sh\"\u003e\u003cimg src=\"https://slackin-pbfjhfxnsa.now.sh/badge.svg\"\u003e\u003c/a\u003e\n\n\u003ca href=\"https://circleci.com/gh/codediodeio/geofirex\"\u003e\u003cimg src=\"https://circleci.com/gh/codediodeio/geofirex.svg?style=svg\"\u003e\u003c/a\u003e\n\n\u003c/p\u003e\n\n# GeoFireX\n\nRealtime Geolocation with Firestore \u0026 RxJS. Query geographic points within a radius on the web or Node.js. \n\n- :point_right: [Live Demo](https://geo-test-c92e4.firebaseapp.com)\n- :tv: [Video Tutorial](https://angularfirebase.com/lessons/geolocation-query-in-firestore-realtime/)\n\n## :zap: QuickStart\n\n```shell\nnpm install geofirex rxjs firebase\n```\n\n### Initialize\n\nThe library is a lightweight extension for the Firebase Web and Admin JavaScript SDKs to provide tools for wrangling geolocation data in Firestore.\n\nWeb:\n\n```js\n// Init Firebase\nimport firebase from 'firebase/app';\nfirebase.initializeApp(yourConfig);\n\n// Init GeoFireX\nimport geofirex from 'geofirex';\nconst geo = geofirex.init(firebase);\n```\n\nNode.js with the Firebase Admin SDK:\n\n```js\nconst admin = require('firebase-admin');\nadmin.initializeApp();\n\nconst geo = require('geofirex').init(admin);\n```\n\nWith Typescript:\n\n```ts\nimport * as geofirex from 'geofirex'; \nconst geo = geofirex.init(firebase);\n```\n\n### Write Geolocation Data\n\nNext, add some geolocation data in your database using the main Firebase SDK. You can add multiple points to a single doc. Calling `geo.point(lat, lng)` creates an object with a [geohash string](https://www.movable-type.co.uk/scripts/geohash.html) and a [Firestore GeoPoint](https://firebase.google.com/docs/reference/android/com/google/firebase/firestore/GeoPoint). Data must be saved in this format to be queried.\n\n```ts\nconst cities = firestore().collection('cities');\n\nconst position = geo.point(40, -119);\n\ncities.add({ name: 'Phoenix', position });\n```\n\n\n![](https://firebasestorage.googleapis.com/v0/b/geo-test-c92e4.appspot.com/o/point1.png?alt=media\u0026token=0c833700-3dbd-476a-99a9-41c1143dbe97)\n\n### Query Geo Data\n\nQuery Firestore for _cities.position within 100km radius of a centerpoint_.\n\n```ts\nconst center = geo.point(40.1, -119.1);\nconst radius = 100;\nconst field = 'position';\n\nconst query = geo.query(cities).within(center, radius, field);\n```\n\nEach hit returns a realtime Observable of the document data, plus some useful `hitMetadata` like _distance_ and _bearing_ from the query centerpoint.\n\n```ts\nquery.subscribe(console.log);\n// [{ ...documentData, hitMetadata: { distance: 1.23232, bearing: 230.23 }  }]\n```\n\nYou now have a realtime stream of data to visualize on a map.\n\n![](https://firebasestorage.googleapis.com/v0/b/geo-test-c92e4.appspot.com/o/geoquery-fire2.gif?alt=media\u0026token=487abd17-90a3-4589-a82d-81d172ddeb25)\n\n## :notebook: API\n\n### `query\u003cT\u003e(ref: CollectionReference | Query | string): GeoFireQuery\u003cT\u003e`\n\nCreates reference to a Firestore collection or query that can be used to make geo-queries.\n\nExample:\n\n```ts\nconst geoRef = geo.query('cities');\n\n// OR make a geoquery on top of a firestore query\n\nconst firestoreRef = firestore().collection('cities').where('name', '==', 'Phoenix');\nconst geoRef = geo.query(firestoreRef);\n```\n\n#### `within(center: FirePoint, radius: number, field: string): Observable\u003cT[]\u003e`\n\n```js\nconst query = geoRef.within(center: FirePoint, radius: number, field: string)\n        \nquery.subscribe(hits =\u003e console.log(hits))\n\n// OR fetch as a promise\n\nimport { get } from 'geofirex';\n\nconst hits = await get(query);\n```\n\nQuery the parent Firestore collection by geographic distance. It will return documents that exist within X kilometers of the centerpoint.\n\nEach doc also contains returns _distance_ and _bearing_ calculated on the query on the `hitMetadata` property.\n\n\n\n### `point(latitude: number, longitude: number): FirePoint`\n\nReturns an object with the required geohash format to save to Firestore. \n\nExample: `const point = geo.point(38, -119)`\n\nA point is a plain JS object with two properties.\n\n- `point.geohash` Returns a geohash string at precision 9\n- `point.geopoint` Returns a Firestore GeoPoint \n\n\n## Additional Features\n\nThe goal of this package is to facilitate rapid feature development with tools like MapBox, Google Maps, and D3.js. If you have an idea for a useful feature, open an issue.\n\n### Logging\n\nEach query runs on a set of geohash squares, so you may read more documents than actually exist inside the radius. Use the `log` option to examine the total query size and latency.\n\n```js\nquery.within(center, radius, field, { log: true })\n```\n\n![Logging GeoQueries](https://firebasestorage.googleapis.com/v0/b/geo-test-c92e4.appspot.com/o/geofirex-logging.PNG?alt=media\u0026token=9b8b487d-18b2-4e5f-bb04-564fa6f2996d)\n\n### Geo Calculations\n\nConvenience methods for calculating distance and bearing. \n\n- `geo.distance(geo.point(38, -118), geo.point(40, -115))` Haversine distance \n- `geo.bearing(to, from)` Haversine bearing \n\n### `toGeoJSON` Operator\n\nA custom RxJS operator that transforms a collection into a [GeoJSON FeatureCollection](https://macwright.org/2015/03/23/geojson-second-bite.html#featurecollection). Very useful for tools like [MapBox](https://blog.mapbox.com/real-time-maps-for-live-events-fad0b334e4e) that can use GeoJSON to update a realtime data source.\n\n```ts\nimport { toGeoJSON } from 'geofirex';\n\nconst query = geo.query('cars').within(...)\n\nquery.pipe( toGeoJSON() )\n\n// Emits a single object typed as a FeatureCollection\u003cGeometry\u003e\n{\n  \"type\": \"FeatureCollection\",\n  \"features\": [...]\n}\n```\n\n#### Promises with `get`\n\nDon't need a realtime stream? Convert any query observable to a promise by wrapping it with `get`.\n\n```ts\nimport { get } from 'geofirex';\n\nasync function getCars {\n    const query = geo.query('cars').within(...)\n    const cars = await get(query)\n}\n```\n\n## Tips\n\n### Compound Queries\n\nThe only well-supported type of compound query is `where`. A geoquery combines multiple smaller queries into a unified radius, so  `limit` and pagination operators will not provide predictable results - a better approach is to search a smaller radius and do your sorting client-side. \n\n\nExample:\n\n```ts\n// Make a query like you normally would\nconst users = firestore().collection('users').where('status', '==', 'online');\n\n\nconst nearbyOnlineUsers = geo.query(users).within(center, radius, field);\n```\n\nNote: This query requires a composite index, which you will be prompted to create with an error from Firestore on the first request.\n\n\n### Usage with RxJS \u003c 6.2, or Ionic v3\n\nThis package requires RxJS 6.2, but you can still use it with older versions without blowing up your app by installing rxjs-compat.\n\nExample:\n\n```shell\nnpm i rxjs@latest rxjs-compat\n```\n\n### Make Dynamic Queries the RxJS Way\n\n```ts\nconst radius = new BehaviorSubject(1);\nconst cities = geo.query('cities');\n\nconst points = this.radius.pipe(\n  switchMap(rad =\u003e {\n    return cities.within(center, rad, 'point');\n  })\n);\n\n// Now update your query\nradius.next(23);\n```\n\n### Always Order by `[Latitude, Longitude]`\n\nThe GeoJSON spec formats coords as `[Longitude, Latitude]` to represent an X/Y plane. However, the Firebase GeoPoint uses `[Latitude, Longitude]`. For consistency, this library always requires to use the latter Firebase-style format.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodediodeio%2Fgeofirex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcodediodeio%2Fgeofirex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodediodeio%2Fgeofirex/lists"}