Geofencing

A 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.

A location-aware device (Android & iOS) user will enter or exit a geofence. This activity will trigger entry or exit events. Events can be used to send alerts to the user's device or to perform actions and tasks in the backend.

Base URL

The Roam 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.

https://api.roam.ai/v1/api/geofence

Authentication

The Roam API uses API keys to authenticate requests. You can view and manage your API keys in the Roam 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

Geofences can be created using the Roam API. Geofences can be created over circle or polygon geometry. By default, a geofence is applicable to all users of a project but can be restricted to a set of users or users belonging to a user group. Geofences can also be configured to be enabled for a specified time interval.

Geofence Types:

Roam allows you to create two (2) geofence geometry types:

  • Circle

  • 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
cURL
curl --location --request POST 'https://api.roam.ai/v1/api/geofence/' \
--header 'Api-Key: e566c098cc6b441a9c3453b6fcf76e88' \
--header 'Content-Type: application/json' \
--data-raw '{
"coordinates": [ -72.28122, 42.926042 ] ,
"geometry_radius": 177,
"is_enabled": [true, "2021-06-10T18:45:00", "2021-06-10T19:29:00"]
}'

Sample Response // Circle Geofence

RESPONSE 200:OK
{
"status": true,
"msg": "Geofence Added successfully.",
"code": 201,
"data": {
"geofence_id": "60e59c73ffb3fb58a9c6eb64",
"geometry_type": "circle",
"geometry_radius": 177,
"geometry_center": {
"type": "Point",
"coordinates": [
-72.28122,
42.926042
]
},
"is_enabled": [
true,
"2021-06-10T18:45:00.000",
"2021-06-10T19:29:00.000"
],
"is_deleted": false,
"created_at": "2021-07-07T12:22:11.105",
"updated_at": "2021-07-07T12:22:11.105"
}
}

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
cURL
curl --location --request POST 'https://api.roam.ai/v1/api/geofence/' \
--header 'Api-Key: e566c098cc6b441a9c3453b6fcf76e88' \
--header 'Content-Type: application/json' \
--data-raw '
{
"coordinates":[
[
-0.08789347686767579,
51.50619618452938
],
[
-0.0905934768676758,
51.50619618452938
],
[
-0.0905934768676758,
51.503796184529385
],
[
-0.08789347686767579,
51.50619618452938
]
],
"is_enabled": [
true,
"2021-06-10T18:45:00",
"2021-06-10T19:29:00"
]
}'

Sample Response

{
"status": true,
"msg": "Geofence Added successfully.",
"code": 201,
"data": {
"geofence_id": "60e59cfaffb3fb58a8c6eb66",
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
-0.08789347686767579,
51.50619618452938
],
[
-0.0905934768676758,
51.50619618452938
],
[
-0.0905934768676758,
51.503796184529385
],
[
-0.08789347686767579,
51.50619618452938
]
]
]
},
"geometry_type": "polygon",
"geometry_center": {
"type": "Point",
"coordinates": [
-0.08969347686882724,
51.505396185373506
]
},
"is_enabled": [
true,
"2021-06-10T18:45:00.000",
"2021-06-10T19:29:00.000"
],
"is_deleted": false,
"created_at": "2021-07-07T12:24:26.197",
"updated_at": "2021-07-07T12:24:26.197"
}
}

User Specific Geofence

You can monitor geofence events for a specific user or a list of users by passing user_ids which are generated at the time of creating a user. Or you group users using the groups_ids 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 ofuser_idto create a geofence specific for multiple users.

Sample Request for single User ID

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

Sample Request for multiple User IDs

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

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
cURL
curl --location --request POST 'https://api.roam.ai/v1/api/geofence/' \
--header 'Api-Key: e566c098cc6b441a9c3453b6fcf76e88' \
--header 'Content-Type: application/json' \
--data-raw '{
"geometry_type": "circle",
"coordinates": [ -72.28122, 42.926042 ] ,
"geometry_radius": 177,
"is_enabled": [true, "2021-06-10T18:45:00", "2021-06-10T19:29:00"],
"group_ids": ["6bda16edea01848b3b419163"]
}'

Sample Request for multiple Group ID

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

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 elements to theis_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
cURL
curl --location --request POST 'https://api.roam.ai/v1/api/geofence/' \
--header 'Api-Key: e566c098cc6b441a9c3453b6fcf76e88' \
--header 'Content-Type: application/json' \
--data-raw '{
"geometry_type": "circle",
"coordinates": [ -72.28122, 42.926042 ] ,
"geometry_radius": 177,
"is_enabled": [true, "2021-06-10T18:45:00", "2021-06-10T19:29:00"]
}'

Sample Response

{
"status": true,
"msg": "Geofence Added successfully.",
"code": 201,
"data": {
"geofence_id": "60e59e9effb3fb58a3c6eb69",
"geometry_type": "circle",
"geometry_radius": 177,
"geometry_center": {
"type": "Point",
"coordinates": [
-72.28122,
42.926042
]
},
"is_enabled": [
true,
"2021-06-10T18:45:00.000",
"2021-06-10T19:29:00.000"
],
"is_deleted": false,
"created_at": "2021-07-07T12:31:26.437",
"updated_at": "2021-07-07T12:31:26.437"
}
}

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
cURL
curl --location --request POST 'https://api.roam.ai/v1/api/geofence/' \
--header 'Api-Key: e566c098cc6b441a9c3453b6fcf76e88' \
--header 'Content-Type: application/json' \
--data-raw '{
"geometry_type": "circle",
"coordinates": [ -72.28122, 42.926042 ] ,
"geometry_radius": 177,
"description": "Google New York City",
"metadata": {
"object_id": "10000234243241234",
"google_user_id": "000034"
},
"is_enabled": [true, "2021-06-10T18:45:00", "2021-06-10T19:29:00"]
}'

Sample Response

{
"status": true,
"msg": "Geofence Added successfully.",
"code": 201,
"data": {
"geofence_id": "60ee5decffb3fb728a120cb4",
"geometry_type": "circle",
"geometry_radius": 177,
"geometry_center": {
"type": "Point",
"coordinates": [
-72.28122,
42.926042
]
},
"is_enabled": [
true,
"2021-06-10T18:45:00.000",
"2021-06-10T19:29:00.000"
],
"description": "Google New York City",
"metadata": {
"object_id": "10000234243241234",
"google_user_id": "000034"
},
"is_deleted": false,
"created_at": "2021-07-14T03:45:48.842",
"updated_at": "2021-07-14T03:45:48.842"
}
}

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 the geofence and how it is displayed on the dashboard. Hex Code for CSS colors should be passed in this field without #.

Sample Request

cURL
cURL
curl --location --request POST 'https://api.roam.ai/v1/api/geofence/' \
--header 'Api-Key: e566c098cc6b441a9c3453b6fcf76e88' \
--header 'Content-Type: application/json' \
--data-raw '{
"coordinates": [ -72.28122, 42.926042 ] ,
"geometry_radius": 177,
"description": "Google New York City",
"metadata": {
"object_id": "10000234243241234",
"google_user_id": "000034"
},
"tag": "home",
"color_code": "ffffff",
"is_enabled": [true, "2021-06-10T18:45:00", "2021-06-10T19:29:00"]
}'

Sample Response

{
"status": true,
"msg": "Geofence Added successfully.",
"code": 201,
"data": {
"geofence_id": "60ee5e1effb3fb728c120d88",
"geometry_type": "circle",
"geometry_radius": 177,
"geometry_center": {
"type": "Point",
"coordinates": [
-72.28122,
42.926042
]
},
"is_enabled": [
true,
"2021-06-10T18:45:00.000",
"2021-06-10T19:29:00.000"
],
"description": "Google New York City",
"color_code": "ffffff",
"tag": "home",
"metadata": {
"object_id": "10000234243241234",
"google_user_id": "000034"
},
"is_deleted": false,
"created_at": "2021-07-14T03:46:38.674",
"updated_at": "2021-07-14T03:46:38.674"
}
}

Update Geofence

A geofence can be updated using Roam API by PUT request using the geofence endpoint. A geofence that was created using Roam API are allowed to update the below values.

Parameters

Type

group_ids

array

user_ids

array

metadata

object

color_code

string

tag

string

description

string

is_enabled

array

The values which are not allowed to update once the geofence is created are mentioned below:

Parameters

Type

coordinates

array

geometry_type

string

geometry_radius

integer

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

This filter allows you to filter the list of geofences within the given date range. They are non-mandatory fields and will be set to the current date by default.

You can also either pass either the start_date or the end_date which will also work. If you pass a specific start date, make sure it is less than the current date since the end date will be set default to the current date. If you pass a specific end_date and leave the start_date empty, make sure it is greater than the current date.

Below are the acceptable formats for the date filter:

Parameter

Mandatory

Format

Default

start_date

No

YYYY-MM-DD

Current date

end_date

No

YYYY-MM-DD

Current date

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

Using geofence_id

You can also use geofence_id as a filter. If you pass a valid geofence_id, the results will be filtered to the given geofence id.

You can get the geofence_id when you create a geofence using the Create Geofence API.

When you use a geofence_id as a filter along with a date filter, the date filters will not be considered. And if you pass an empty or invalid geofence_id, the API will return an error.

Make sure the geofence_id used here belongs to the same project linked with the API key.

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

Using user_id

Similar to the geofence_id, you can fetch the list of geofences that are tagged with the given user_id, which was initially used during the Create Geofence API. The user_id is created within the SDK during thecreateUser method and returns a unique user_id for identification within the Roam environment.

When you use user_id as a filter along with a date filter, the date filters will not be considered. And if you pass an empty or invalid user_id, the API will return an error.

Make sure the user_id used here belongs to the same project linked with the API key.

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

Using group_id

To fetch the list of geofences that are tagged with the given group_id, which was initially used during the Create Geofence API, you can pass the group_id in the header parameter.

You can get the group_id when you create a group using the Create Group API.

When you use group_id as a filter along with the date filter, the date filters will not be considered. And if you pass an empty or invalid group_id, the API will return an error.

Make sure the group_id used here belongs to the same project linked with the API key.

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

Geofence Events

Roam's geofence feature has 2 possible events that can be triggered based on user behaviors:

  1. Geofence Entry Event - triggered when a user enters the defined geofence area

  2. Geofence Exit Event - triggered when a user exits from the defined geofence area

Sample Events:

Geofence Entry Event:

{
"events": [
{
"user_id": "60e5646151efb06fe4c65b0d",
"location_id": "60e566a4fa8a780000ed3194",
"geofence_id": "60e566a28ce7db5726c1c1cd",
"recorded_at": "2021-07-07T08:32:36.243Z",
"event_source": "geospark:geofence",
"event_version": "1.0",
"event_type": "geospark:geofence:entry",
"location": {
"type": "Point",
"coordinates": [
77.5573154,
9.4551286
]
},
"speed": 0,
"course": 316.1922912597656,
"altitude": 78.46394327410016,
"activity": "M",
"vertical_accuracy": null,
"horizontal_accuracy": 10.565999984741211
}
]
}

Geofence Exit Event:

{
"events": [
{
"user_id": "60e5646151efb06fe4c65b0d",
"location_id": "60e566a4fa8a780000ed3194",
"geofence_id": "60e566a28ce7db5726c1c1cd",
"recorded_at": "2021-07-07T08:32:36.243Z",
"event_source": "geospark:geofence",
"event_version": "1.0",
"event_type": "geospark:geofence:exit",
"location": {
"type": "Point",
"coordinates": [
77.5573154,
9.4551286
]
},
"speed": 0,
"course": 316.1922912597656,
"altitude": 78.46394327410016,
"activity": "M",
"vertical_accuracy": 5,
"horizontal_accuracy": 10.565999984741211
}
]
}

Enable Events

To process geofences for a user, thegeofence_events flag must be set to true for the user. This can be done from SDK using the Roam.toggleEvents method or by updating the user using the API. If thegeofence_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 the SDK.

Events via Webhook

Roam supports the posting of events to webhook in real-time. 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 the Roam 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.

Error Codes

Method

Status

Message

Reason

GET

400

"Error": [ "start_date provided is greater than end_date." ]

Invalid date filter

GET

400

"geofence_id": { "geofence_id": "This field is invalid." }

Invalid geofence id

GET

400

"Error": [ "Geofence does not exist." ]

Geofence does not exist

GET

400

"Error": [ "You are not authorized." ]

Invalid API key

GET

400

"Error": [ "Maximum 7 days data is allowed at a time." ]

Date filter greater than the limit of 7 days

GET

400

"ErrorMessage": "An error occurred"

Unknown server error

POST

400

"coordinates": [ "Invalid coordinates for given geometry type" ]

Invalid geofence geometry coordinates

POST

400

"enable_at": [ "DateTime has wrong format. Provide as YYYY-MM-DDThh:mm:ss" ]

Invalid date time format

POST

400

"non_field_errors": [ "enable_at provided is greater than disable_at." ]

Invalid enable_at value

POST

400

"non_field_errors": [ "disable_at field is required when enable_at field is present." ]

Empty disable_at value

POST

400

"non_field_errors": [ "enable_at field is required when disable_at field is present." ]

Empty enable_at value

POST

400

"Invalid is_enabled format. Allowed format: [bool, enable_at, disable_at]"

Invalid is_enabled format

POST

400

"coordinates": [ "Coordinates must be sent in a list" ]

Invalid coordinates

POST

400

"geometry_radius": [ "This field is required." ]

Empty geometry radius

POST

400

"tag": { "tag": "This field is invalid." }

Invalid tag

PUT

400

"geofence_id": { "geofence_id": "This field is invalid." }

Invalid geofence id

DELETE

400

"details": "This geofence is part of an active campaign."

Geofence cannot be deleted since its part of an active campaign

DELETE

400

"geofence_id": { "geofence_id": "This field is invalid." }

Invalid geofence id