\n\n# GeoFireX\n\nRealtime Geolocation with Firestore & 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\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\n\n## :notebook: API\n\n### `query(ref: CollectionReference | Query | string): GeoFireQuery`\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`\n\n```js\nconst query = geoRef.within(center: FirePoint, radius: number, field: string)\n \nquery.subscribe(hits => 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\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\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 < 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 => {\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","readmeFilename":"README.md"}
![](\"https://slackin-pbfjhfxnsa.now.sh/badge.svg\"){kind=icon}
\n\n![](\"https://circleci.com/gh/codediodeio/geofirex.svg?style=svg\")
\n\n