Q3-Fence

A polygon geofencing library

Requirements

For development, you will only need Node.js and a node global package, NPM, installed in your environement.

Install

  $ npm install q3-fence

Usage

   const { init } = require("q3-fence");
   
   let mongoDBUrl = "...";
   
   await init(mongoDBUrl);

This should be called when your program/app starts.

Create new geofence

Geofences are created using the addGeofence function the type paramer value can be one of "area" or "region". In the coordinates array, longitudes should come first before latitudes. Any other data in the payload will be added to the metadata field.

const {
    init,
    updateGeofenceDoc,
    removeGeofenceDoc,
    allUsersInGeofence,
    allGeofence,
    allGeofenceForUser,
    deleteGeofence,
    updateGeofence,
    addGeofence,
    addGeofenceDoc,
    serializeUser,
    findGeofenceDocForUser} = require("q3-fence"); // import the ones you need

const payload = {"areas":[{"coordinates":[
    [3.5826842486858372,6.513636165419227],
    [3.574883043766022,6.505586785393162],
    [3.5806953907012944,6.496937655454424],
    [3.5889177024364476,6.499954407858632],
    [3.590706735849381,6.509557526975297],
    [3.5826842486858372,6.513636165419227]]}],
    "name":"Geofence name",
    "description":"geofence description","type":"area"};

addGeofence(payload)

Delete a geofence

const payload = {id: geofenceId};
deleteGeofence(payload);

Add a document to geofence

Once a geofence has been created, documents can be add to it. To add a document to a geofence, use the function addGeofenceDoc. areaId is the id of the geofence the document will be added.

const doc = {
    "areaId": "62334ab836017f4970c38446",
    "name": "Unity Bank",
    "age": {
        "max": 60,
        "min": 18
    },
    "start": "2022-03-11T09:42:36.185Z",
    "end": "2022-03-16T10:05:01.548Z",
    "time": {
        "max": 12345,
        "min": 1234
    },
    "gender": ["male", "all"],
    "approval_status": true
};

addGeofenceDoc(payload)

Remove document from a geofence

To remove a document from a geofence/area, call the removeGeofenceDoc with an object containing the areaId and document id

const query = {areaId: "563uqad...", docId:"12e6ioisda..."}
removeGeofenceDoc(query);

Update document in a geofence

To update a document in a geofence, supply an object that has the same with the document in the geofence but with the updated value. If the new key value pairs were not in the existing document, it will be added

const payload = {areaId: "563uqad...", docId:"12e6ioisda...", ...data}
updateGeofenceDoc(payload);

Serialize User

Add user data to the collection the proper way, setting longitude and latitude

const user = {long: longitudeValue, lat: latitudeValue, ...} // user data
serializeUser(user)

All users in a geofence

To get all users in a particular geofence, use allUsersInGeofence, and pass an object that has either the area id or lat and lng

const query = {lng: longitudeValue, lat: latitudeValue, ...} // user data
allUsersInGeofence(query);

or

const query = {areaId: areaIdValue}
allUsersInGeofence(query);

Features

init
addGeofence
updateGeofence
deleteGeofence
allGeofence

addGeofenceDoc
updateGeofenceDoc
removeGeofenceDoc

allUsersInGeofence
allGeofenceForUser

serializeUser
findGeofenceDocForUser