PouchDB Geospatial

The PouchDB Geospatial plugin provides spatial querying of GeoJSON objects. GeoJSON objects within a PouchDB database can be queried against an input GeoJSON object to test if they satisfy one of the DE-9IM spatial predicates: contains, coveredby, covers, crosses, disjoint, equals, intersects, overlaps, touches, within.

Any GeoJSON object inserted into the database via the the plugin API is spatially indexed using an R-Tree. Spatial queries are then processed by querying the R-Tree for candidate geometries and the final query results are returned after the candidates are filtered by the appropriate spatial predicate. The spatial indexing is performed by RBush and geospatial predicates are computed with de9im.

A sample of how to use the plugin is available at the examples page. The API is described below and at the documentation page.

USAGE

In browser

To use this plugin, include it after pouchdb.js in your HTML page. This plugin has two dependencies not bundled with it that must be included Turf and de9im.

<script src="https://unpkg.com/pouchdb/dist/pouchdb.min.js"></script>
<script src="https://unpkg.com/@turf/turf"></script>
<script src="https://unpkg.com/de9im"></script>
<script src="https://unpkg.com/pouchdb-geospatial"></script>

In Node

To use it in Node, install it

npm install pouchdb-geospatial

then attach it to the PouchDB object:

import PouchDB from 'pouchdb';
import PouchDBGeospatial from 'pouchdb-geospatial';
PouchDB.plugin(PouchDBGeospatial);

Create database

The plugin methods are exposed via an object API. All methods return promises.

const db = new PouchDB('dbname');
const api = db.geospatial();

API

Database methods

The database methods accept the same options and return a promise with the same response returned by their corresponding PouchDB methods: put, post, bulkDocs, and remove.

api.add(geojson, options);
api.load([geojson, ...], options);
api.remove(id);

Indexing methods

The underlying R-Tree can be accessed using the tree attribute. It returns an GeospatialTree which allows a user to directly use it's methods to add, load, remove, and query the tree. However, care should be used when modifying the tree directly since the tree and database can become out-of-sync. The primary use of directly accessing the tree is to reload data from disk after a page reload or application restart. Otherwise, it is preferable to directly use the database methods to add data.

api.tree.add(geojson, id);
api.tree.load([{id, geojson}, ...]);
api.tree.remove({id, geojson});
api.tree.query(geojson);

Query methods

The query methods accept a GeoJSON and return a promise with an array of database document IDs that satisfy the spatial predicate. For example,

api.contains(geojson).then((ids) => {
  // Do something with document ids.
});

The following spatial predicates are available:

contains
coveredby
covers
crosses
disjoint
equals
intersects
overlaps
touches
within

Each predicate takes one GeoJSON argument. The predicate should be interpreted as the database GeoJSON operating on the argument GeoJSON. For example,

api.within(polygon)

should be read as

any database GeoJSON within polygon?

BUILD

To build and test the library locally:

npm install
npm test

After installation, the bundled plugin is at pouchdb-geospatial.min.js.

LICENSE

Copyright (c) 2019 Daniel Pulido mailto:[email protected]

Source code is released under the Apache 2.0 license