T
T
The Cyprinus
Search…
Geofencing
Geofence is a virtual perimeter for a real-world geographical area. A geofence can be dynamically generated for two types - a radius around a location point (circle geofence) or a pre-defined set of boundaries (polygon geofence), such as stores, neighborhoods, or even cities.
The use of geofence is called geofencing. A location-aware device (iOS & Android devices) user entering or exiting a geofence. The activity will trigger entry and exit events which can be used to sent alerts to the user's mobile device or be used the event to perform actions and tasks in the backend.

Base URL

The Cyprinus API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.
1
https://api.roam.ai/v1/api/geofence
Copied!

Authentication

The Cyprinus API uses API keys to authenticate requests. You can view and manage your API keys in the Cyprinus Dashboard.
Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth. Authentication to the API is performed via a custom header Api-Key. Provide your API key as the value for the header Api-Key
All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Create Geofence

Geofence can be created using Cyprinus API. Geofence can be created over circle or polygon geometry. Geofence by default is applicable to all users of a project but can be restricted to a set of users or users belonging to a user group. Geofence can also be configured to be enabled for a specified time interval.

Geofence Types:

Cyprinus supports geofences of 2 different geometry type:
  1. 1.
    Circle
  2. 2.
    Polygon

Circle Geofence

A circle geofence is a radius around a location point. To create a circle geofence the required body parameters are ** coordinates, and geometry_radius .

Sample Request // Circle Geofence

cURL
1
curl --location --request POST 'https://api.roam.ai/v1/api/geofence/' \
2
--header 'Api-Key: e566c098cc6b441a9c3453b6fcf76e88' \
3
--header 'Content-Type: application/json' \
4
--data-raw '{
5
"coordinates": [ -72.28122, 42.926042 ] ,
6
"geometry_radius": 177,
7
"is_enabled": [true, "2021-06-10T18:45:00", "2021-06-10T19:29:00"]
8
}'
Copied!

Sample Response // Circle Geofence

RESPONSE 200:OK
1
{
2
"status": true,
3
"msg": "Geofence Added successfully.",
4
"code": 201,
5
"data": {
6
"geofence_id": "60e59c73ffb3fb58a9c6eb64",
7
"geometry_type": "circle",
8
"geometry_radius": 177,
9
"geometry_center": {
10
"type": "Point",
11
"coordinates": [
12
-72.28122,
13
42.926042
14
]
15
},
16
"is_enabled": [
17
true,
18
"2021-06-10T18:45:00.000",
19
"2021-06-10T19:29:00.000"
20
],
21
"is_deleted": false,
22
"created_at": "2021-07-07T12:22:11.105",
23
"updated_at": "2021-07-07T12:22:11.105"
24
}
25
}
Copied!

Polygon Geofence

A polygon geofence is a set of pre-defined boundaries of any shape around a location area. To create a circle geofence the required body parameters are **geometry_type andcoordinates.

Same Request to create a Polygon geofence

cURL
1
curl --location --request POST 'https://api.roam.ai/v1/api/geofence/' \
2
--header 'Api-Key: e566c098cc6b441a9c3453b6fcf76e88' \
3
--header 'Content-Type: application/json' \
4
--data-raw '
5
{
6
"coordinates":[
7
[
8
-0.08789347686767579,
9
51.50619618452938
10
],
11
[
12
-0.0905934768676758,
13
51.50619618452938
14
],
15
[
16
-0.0905934768676758,
17
51.503796184529385
18
],
19
[
20
-0.08789347686767579,
21
51.50619618452938
22
]
23
],
24
"is_enabled": [
25
true,
26
"2021-06-10T18:45:00",
27
"2021-06-10T19:29:00"
28
]
29
}'
Copied!

Sample Response

1
{
2
"status": true,
3
"msg": "Geofence Added successfully.",
4
"code": 201,
5
"data": {
6
"geofence_id": "60e59cfaffb3fb58a8c6eb66",
7
"geometry": {
8
"type": "Polygon",
9
"coordinates": [
10
[
11
[
12
-0.08789347686767579,
13
51.50619618452938
14
],
15
[
16
-0.0905934768676758,
17
51.50619618452938
18
],
19
[
20
-0.0905934768676758,
21
51.503796184529385
22
],
23
[
24
-0.08789347686767579,
25
51.50619618452938
26
]
27
]
28
]
29
},
30
"geometry_type": "polygon",
31
"geometry_center": {
32
"type": "Point",
33
"coordinates": [
34
-0.08969347686882724,
35
51.505396185373506
36
]
37
},
38
"is_enabled": [
39
true,
40
"2021-06-10T18:45:00.000",
41
"2021-06-10T19:29:00.000"
42
],
43
"is_deleted": false,
44
"created_at": "2021-07-07T12:24:26.197",
45
"updated_at": "2021-07-07T12:24:26.197"
46
}
47
}
Copied!

User Specific Geofence

Let's you monitor geofence events for a specific user or a list of users, by passing user_ids that were generated at the time of creating a user. Or you group users using the Groups ID which will give you a group_id. By default if user_ids and group_ids are not specified then the geofence is activated for all users of the project. __

Based on User ID

Pass a user_id under the "user_ids" body parameter. Pass an array of user_id to create a geofence specific for multiple users.

Sample Request for single User ID

cURL
1
curl --location --request POST 'https://api.roam.ai/v1/api/geofence/' \
2
--header 'Api-Key: e566c098cc6b441a9c3453b6fcf76e88' \
3
--header 'Content-Type: application/json' \
4
--data-raw '{
5
"geometry_type": "circle",
6
"coordinates": [ -72.28122, 42.926042 ] ,
7
"geometry_radius": 177,
8
"is_enabled": [true, "2021-06-10T18:45:00", "2021-06-10T19:29:00"],
9
"user_ids": ["6bda16edea01848b3b419163"]
10
}'
Copied!

Sample Request for multiple User IDs

cURL
1
curl --location --request POST 'https://api.roam.ai/v1/api/geofence/' \
2
--header 'Api-Key: e566c098cc6b441a9c3453b6fcf76e88' \
3
--header 'Content-Type: application/json' \
4
--data-raw '{
5
"geometry_type": "circle",
6
"coordinates": [ -72.28122, 42.926042 ] ,
7
"geometry_radius": 177,
8
"is_enabled": [true, "2021-06-10T18:45:00", "2021-06-10T19:29:00"],
9
"user_ids": ["6bda16edea01848b3b419163", "6bda16edea01848b3b419163"]
10
}'
Copied!

Based on Group ID

Pass a group_id under the "group_ids" body parameter. Pass multiple and array of group_id to create a geofence specific for multiple groups.

Sample Request for single Group ID

cURL
1
curl --location --request POST 'https://api.roam.ai/v1/api/geofence/' \
2
--header 'Api-Key: e566c098cc6b441a9c3453b6fcf76e88' \
3
--header 'Content-Type: application/json' \
4
--data-raw '{
5
"geometry_type": "circle",
6
"coordinates": [ -72.28122, 42.926042 ] ,
7
"geometry_radius": 177,
8
"is_enabled": [true, "2021-06-10T18:45:00", "2021-06-10T19:29:00"],
9
"group_ids": ["6bda16edea01848b3b419163"]
10
}'
Copied!

Sample Request for multiple Group ID

cURL
1
curl --location --request POST 'https://api.roam.ai/v1/api/geofence/' \
2
--header 'Api-Key: e566c098cc6b441a9c3453b6fcf76e88' \
3
--header 'Content-Type: application/json' \
4
--data-raw '{
5
"geometry_type": "circle",
6
"coordinates": [ -72.28122, 42.926042 ] ,
7
"geometry_radius": 177,
8
"is_enabled": [true, "2021-06-10T18:45:00", "2021-06-10T19:29:00"],
9
"group_ids": ["6bda16edea01848b3b419163", "6bda16edea01848b3b419163"]
10
}'
Copied!

Time-Aware Geofence

Create time aware geofences to trigger events between a specific time range by passing date and time in an array as 2nd and 3rd element to is_enabledfield of the body parameters.
During the specified time the entry and exit events will be triggered and outside the time you need to ensure "is_enabled" as "false"
cURL
1
curl --location --request POST 'https://api.roam.ai/v1/api/geofence/' \
2
--header 'Api-Key: e566c098cc6b441a9c3453b6fcf76e88' \
3
--header 'Content-Type: application/json' \
4
--data-raw '{
5
"geometry_type": "circle",
6
"coordinates": [ -72.28122, 42.926042 ] ,
7
"geometry_radius": 177,
8
"is_enabled": [true, "2021-06-10T18:45:00", "2021-06-10T19:29:00"]
9
}'
Copied!

Sample Response

1
{
2
"status": true,
3
"msg": "Geofence Added successfully.",
4
"code": 201,
5
"data": {
6
"geofence_id": "60e59e9effb3fb58a3c6eb69",
7
"geometry_type": "circle",
8
"geometry_radius": 177,
9
"geometry_center": {
10
"type": "Point",
11
"coordinates": [
12
-72.28122,
13
42.926042
14
]
15
},
16
"is_enabled": [
17
true,
18
"2021-06-10T18:45:00.000",
19
"2021-06-10T19:29:00.000"
20
],
21
"is_deleted": false,
22
"created_at": "2021-07-07T12:31:26.437",
23
"updated_at": "2021-07-07T12:31:26.437"
24
}
25
}
Copied!

Personalize Geofence

Description and Metadata

Adding a description and metadata can help identify and personalize the geofences while displaying them on a map. You can add this information while creating a geofence or updating a geofence.

Sample Request

cURL
1
curl --location --request POST 'https://api.roam.ai/v1/api/geofence/' \
2
--header 'Api-Key: e566c098cc6b441a9c3453b6fcf76e88' \
3
--header 'Content-Type: application/json' \
4
--data-raw '{
5
"geometry_type": "circle",
6
"coordinates": [ -72.28122, 42.926042 ] ,
7
"geometry_radius": 177,
8
"description": "Google New York City",
9
"metadata": {
10
"object_id": "10000234243241234",
11
"google_user_id": "000034"
12
},
13
"is_enabled": [true, "2021-06-10T18:45:00", "2021-06-10T19:29:00"]
14
}'
Copied!

Sample Response

1
{
2
"status": true,
3
"msg": "Geofence Added successfully.",
4
"code": 201,
5
"data": {
6
"geofence_id": "60ee5decffb3fb728a120cb4",
7
"geometry_type": "circle",
8
"geometry_radius": 177,
9
"geometry_center": {
10
"type": "Point",
11
"coordinates": [
12
-72.28122,
13
42.926042
14
]
15
},
16
"is_enabled": [
17
true,
18
"2021-06-10T18:45:00.000",
19
"2021-06-10T19:29:00.000"
20
],
21
"description": "Google New York City",
22
"metadata": {
23
"object_id": "10000234243241234",
24
"google_user_id": "000034"
25
},
26
"is_deleted": false,
27
"created_at": "2021-07-14T03:45:48.842",
28
"updated_at": "2021-07-14T03:45:48.842"
29
}
30
}
Copied!

Tags and Color Codes

Adding tag can help filter geofences easily by the tag. This field is optional. When a geofence event is generated tag is also sent along with the event.
color_code defines the color of Geofence and how it is displayed on the dashboard. Hex Code for CSS colors should be passed in this field without #.

Sample Request

cURL
1
curl --location --request POST 'https://api.roam.ai/v1/api/geofence/' \
2
--header 'Api-Key: e566c098cc6b441a9c3453b6fcf76e88' \
3
--header 'Content-Type: application/json' \
4
--data-raw '{
5
"coordinates": [ -72.28122, 42.926042 ] ,
6
"geometry_radius": 177,
7
"description": "Google New York City",
8
"metadata": {
9
"object_id": "10000234243241234",
10
"google_user_id": "000034"
11
},
12
"tag": "home",
13
"color_code": "ffffff",
14
"is_enabled": [true, "2021-06-10T18:45:00", "2021-06-10T19:29:00"]
15
}'
Copied!

Sample Response

1
{
2
"status": true,
3
"msg": "Geofence Added successfully.",
4
"code": 201,
5
"data": {
6
"geofence_id": "60ee5e1effb3fb728c120d88",
7
"geometry_type": "circle",
8
"geometry_radius": 177,
9
"geometry_center": {
10
"type": "Point",
11
"coordinates": [
12
-72.28122,
13
42.926042
14
]
15
},
16
"is_enabled": [
17
true,
18
"2021-06-10T18:45:00.000",
19
"2021-06-10T19:29:00.000"
20
],
21
"description": "Google New York City",
22
"color_code": "ffffff",
23
"tag": "home",
24
"metadata": {
25
"object_id": "10000234243241234",
26
"google_user_id": "000034"
27
},
28
"is_deleted": false,
29
"created_at": "2021-07-14T03:46:38.674",
30
"updated_at": "2021-07-14T03:46:38.674"
31
}
32
}
Copied!

Update Geofence

Geofence can be updated using Cyprinus API by PUT request using the geofence endpoint.

Get Geofence

This API gives you the filtered list of geofences. You can filter by geofence_id, created_at date using start_date and end_date fields, user_id and group_id

Sample Request

Using start_date and end_date

1
curl --location --request GET 'https://api.roam.ai/v1/api/geofence/?start_date=2020-09-28&end_date=2020-09-29' \
2
--header 'Api-Key: e566c098cc6b441a9c3453b6fcf76e88'
Copied!

Using geofence_id

1
curl --location --request GET 'https://api.roam.ai/v1/api/geofence/?geofence_id=5f73326ce5fc231ba4b253eb' \
2
--header 'Api-Key: e566c098cc6b441a9c3453b6fcf76e88'
Copied!

Using user_id

1
curl --location --request GET 'https://api.roam.ai/v1/api/geofence/?user_id=6073325bcf3e4eba5a1123a' \
2
--header 'Api-Key: e566c098cc6b441a9c3453b6fcf76e88'
Copied!

Using group_id

1
curl --location --request GET 'https://api.roam.ai/v1/api/geofence/?group_id=6073325bc3fe343ab6c1324b' \
2
--header 'Api-Key: e566c098cc6b441a9c3453b6fcf76e88'
Copied!

Geofence Events

Cyprinus 's geofence feature has 2 possible events that can be triggered based on user behaviors
  1. 1.
    Geofence Entry Event - triggered when a user enters the defined geofence area
  2. 2.
    Geofence Exit Event - triggered when a user exits from the defined geofence area
Sample Events:
Geofence Entry Event:
1
{
2
"events": [
3
{
4
"user_id": "60e5646151efb06fe4c65b0d",
5
"location_id": "60e566a4fa8a780000ed3194",
6
"geofence_id": "60e566a28ce7db5726c1c1cd",
7
"recorded_at": "2021-07-07T08:32:36.243Z",
8
"event_source": "geospark:geofence",
9
"event_version": "1.0",
10
"event_type": "geospark:geofence:entry",
11
"location": {
12
"type": "Point",
13
"coordinates": [
14
77.5573154,
15
9.4551286
16
]
17
},
18
"speed": 0,
19
"course": 316.1922912597656,
20
"altitude": 78.46394327410016,
21
"activity": "M",
22
"vertical_accuracy": null,
23
"horizontal_accuracy": 10.565999984741211
24
}
25
]
26
}
Copied!
Geofence Exit Event:
1
{
2
"events": [
3
{
4
"user_id": "60e5646151efb06fe4c65b0d",
5
"location_id": "60e566a4fa8a780000ed3194",
6
"geofence_id": "60e566a28ce7db5726c1c1cd",
7
"recorded_at": "2021-07-07T08:32:36.243Z",
8
"event_source": "geospark:geofence",
9
"event_version": "1.0",
10
"event_type": "geospark:geofence:exit",
11
"location": {
12
"type": "Point",
13
"coordinates": [
14
77.5573154,
15
9.4551286
16
]
17
},
18
"speed": 0,
19
"course": 316.1922912597656,
20
"altitude": 78.46394327410016,
21
"activity": "M",
22
"vertical_accuracy": 5,
23
"horizontal_accuracy": 10.565999984741211
24
}
25
]
26
}
Copied!

Enable Events

To process geofences for a user, geofence_events flag must be set to true for the user. This can be done from sdk using Roam.toggleEvents method or by updating user using API. If geofence_events flag is false for a user then geofence events are not processed for the location updates on the user. The user should also have publishandsave enabled in sdk.

Events via Webhook

Cyprinus supports posting of events to webhook in realtime. To enable posting events via webhook first the webhook url needs to be configured in the project using the dashboard (Project Settings -> integration) and should be enabled.

Events via API

Geofence events can be retrieved using Cyprinus API. The Get Events API lets you fetch the entry or exit events of the users from your event enabled geofences. The API also lets you filter by user or geofence, location, and more.

Delete Geofence

Delete any existing geofences from your projects by using the geofence_id
Last modified 4mo ago