Geofence

With geofences we let you define rules that are important for your business. E.g. Tom has reached a warehouse or Jill is at a rental property for over 2 hours. You define the rules by creating a Geofence record. When these rules are satisfied we trigger a geofence and send you a notification through the Event object. You can receive these Events on your server via webhooks or a communication platform like Slack, along with all the important details (when, where, how long etc).

Currently we support two types of Geofences:

  • Location-based geofence - We notify you when user reaches or leaves any point of interest that you define.
  • Time-based geofence - We notify you when user spends certain amount of time at any place. You specify the time range.

Some example geofences that you can set are:

  • Notify when a User is at a given address.
  • Notify when a User is at a given latitude-longitude.
  • Notify when a User stops at any place for more than 30 minutes and less than 2 hours
  • Notify when a User has visited a place more than 3 times in a week.

If these geofence types don't satisfy your use case, please write to us.

The Geofence object

Property Type Description
id uuid string Unique identifier for the object
user_id string User id for which this geofence is created
type string Type of geofence, currently one of [location, time]
place JSON The place object for which you want to set the geofence (for location-based geofences). You can specify lat-long or address or both using the Place json.
min_duration integer Minimum duration (in seconds) beyond which you want to trigger the Geofence (for time-based geofence)
max_duration integer Maximum duration (in seconds) before which you want to trigger the Geofence (for time-based geofence)
expire_at ISO datetime string Timestamp until which you want the geofence to be active, defaults to 1 month from time of creation
created_at ISO datetime string Timestamp of when geofence was created
modified_at ISO datetime string Timestamp of when geofence was modified

Create a Geofence

Creates a new Geofence object.

HTTP Request

POST https://api.hypertrack.com/api/v1/geofences/

Returns

Returns a Geofence object if the call succeeded.

Parameters

Parameter Required Description
user_id Yes User for whom you want to set the geofence
type Yes Type of geofence, one of [location, time]
place Mandatory for location-based geofence Place at which you want to set the location-based geofence
min_duration at least on of min_duration and max_duration is mandatory for time-based geofence Minimum duration (in seconds) beyond which you want to trigger the Geofence (for time-based geofence)
max_duration at least on of min_duration and max_duration is mandatory for time-based geofence Minimum duration (in seconds) beyond which you want to trigger the Geofence (for time-based geofence)
expire_at No Timestamp until which you want the geofence to be active, defaults to 1 month from time of creation
# Create location-based geofence with Lat-long
curl -H "Authorization: token YOUR_SK_TOKEN" \
     -H "Content-Type: application/json" \
     -X POST \
     -d "{\"user_id\":\"DD7565B2-E0A6-4710-8E0B-FD7EEB702A07\",
          \"type\": \"location\",
          \"place\": {\"type\": \"Point\", \"coordinates\": [-122.40661, 37.78739]}}" \
     https://api.hypertrack.com/api/v1/geofences/


# Create location-based geofence with address
curl -H "Authorization: token YOUR_SK_TOKEN" \
     -H "Content-Type: application/json" \
     -X POST \
     -d "{\"user_id\":\"DD7565B2-E0A6-4710-8E0B-FD7EEB702A07\",
          \"type\": \"location\",
          \"place\": {\"address\": \"2200 Sand Hill Road Menlo Park CA USA 94025\"} \
     https://api.hypertrack.com/api/v1/geofences/


# Create time-based geofence with min and max duration
curl -H "Authorization: token YOUR_SK_TOKEN" \
     -H "Content-Type: application/json" \
     -X POST \
     -d "{\"user_id\":\"DD7565B2-E0A6-4710-8E0B-FD7EEB702A07\",
          \"type\": \"time\",
          \"min_duration\": 1800,
          \"max_duration\": 7200} \
     https://api.hypertrack.com/api/v1/geofences/
// Create location-based geofence with Lat-long
hypertrack.geofence
    .create({
        "user_id": "DD7565B2-E0A6-4710-8E0B-FD7EEB702A07",
        "type": "location",
        "place": {
            "type": "Point",
            "coordinates": [-122.40661, 37.78739]
        }
    });

// Create location-based geofence with address
hypertrack.geofence
    .create({
        "user_id": "DD7565B2-E0A6-4710-8E0B-FD7EEB702A07",
        "type": "location",
        "place": {
            "address": "2200 Sand Hill Road Menlo Park CA USA 94025"
        }
    });

// Create time-based geofence with min and max duration
hypertrack.geofence
    .create({
        "user_id": "DD7565B2-E0A6-4710-8E0B-FD7EEB702A07",
        "type": "time",
        "min_duration": 1800,
        "max_duration": 7200
    });

Retrieve a Geofence

Retrieves the details of an existing geofence.

HTTP Request

GET https://api.hypertrack.com/api/v1/geofences/<id>/

Returns

Returns a geofence object if a valid identifier was provided.

curl -H "Authorization: token YOUR_PK_TOKEN" \
     https://api.hypertrack.com/api/v1/geofences/15ce9cdc-1409-4976-a260-dc0e5b2445ac/
hypertrack.geofence
    .retrieve("15ce9cdc-1409-4976-a260-dc0e5b2445ac")
    .then(function(geofence) {});

Update a Geofence

Edit an existing geofence object.

HTTP Request

PATCH https://api.hypertrack.com/api/v1/geofences/<id>/

Returns

Returns the updated geofence object.

Parameters

Parameter Required Description
user_id No User for whom you want to set the geofence
type No Type of geofence, one of [location, time]
place No Place at which you want to set the location-based geofence
min_duration No Minimum duration (in seconds) beyond which you want to trigger the Geofence (for time-based geofence)
max_duration No Minimum duration (in seconds) beyond which you want to trigger the Geofence (for time-based geofence)
expire_at No Timestamp until which you want the geofence to be active, defaults to 1 month from time of creation
curl -H "Authorization: token YOUR_SK_TOKEN" \
     -H "Content-Type: application/json" \
     -X PATCH \
     -d "{\"expire_at\": \"2017-08-20T00:00:00+00:00\"}" \
     https://api.hypertrack.com/api/v1/geofences/15ce9cdc-1409-4976-a260-dc0e5b2445ac/
hypertrack.geofence
    .update(
        "15ce9cdc-1409-4976-a260-dc0e5b2445ac",
        {
            "expire_at": "2017-08-20T00:00:00+00:00"
        }
    );

Delete a Geofence

Delete an existing geofence object.

HTTP Request

DELETE https://api.hypertrack.com/api/v1/geofenecs/<id>/

Returns

Empty response if the object is deleted.

curl -H "Authorization: token YOUR_SK_TOKEN" \
     -H "Content-Type: application/json" \
     -X DELETE \
     https://api.hypertrack.com/api/v1/geofences/15ce9cdc-1409-4976-a260-dc0e5b2445ac/
hypertrack.geofence
    .delete("15ce9cdc-1409-4976-a260-dc0e5b2445ac");

Example response

{}

List all Geofences

Returns a list of your geofences.

HTTP Request

GET https://api.hypertrack.com/api/v1/geofences/

Returns

Returns a list of geofences.

Parameters

Parameter Required Description
page_size No Maximum number of objects to return, default is 50
min_created_at No Filter objects by minimum created at date
max_created_at No Filter objects by maximum created at date
curl -H "Authorization: token YOUR_SK_TOKEN" \
     https://api.hypertrack.com/api/v1/geofences/
hypertrack.geofence
    .list()
    .then(function(geofences) {});

results matching ""

    No results matching ""