Geofencing
Explore Roam's Geofencing documentation.
Geofence is a virtual perimeter for a real-world geographical area. A geofence can be dynamically generated around a location point with a radius (circle geofence) or with a pre-defined set of boundaries (polygon geofence) for stores, neighborhoods, or even cities.
Every time the end user enters or exits a geofence with a location aware device, events are generated. These events can be used to alert the user or perform actions in the backend.
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
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 and API requests without authentication will fail.
Geofences can be created using the Roam API. They can be created over a circle or a polygon geometry. By default, a geofence is applicable to all the users of a project but can also be restricted to a group of users. Geofences can be configured to be enabled for a specified time interval.
Roam allows you to create two geofence geometry types:
- Circle
- Polygon
A circular geofence is the region around a location point defined by a radius. To create a circular geofence, the required body parameters are
coordinates
, and geometry_radius
.
Sample Request // Circle Geofence
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"
}
}
A polygon geofence is the area defined by a set of boundaries forming any shape around a location area. To create a polygon geofence, the required body parameters are
geometry_type
andcoordinates
.
Same Request to create a Polygon geofence
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"
}
}
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. In the case of a user group, you may pass the group_id. If by default, user_ids
and group_ids
are not specified, then the geofence is activated for all the users of the project. Pass a
user_id
under the "user_ids"
body parameter. Pass an array ofuser_ids
to create a geofence specific to multiple users.
Sample Request for single User ID
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 --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"]
}'
Pass a
group_id
under the "group_ids"
body parameter. You may pass multiple group IDs into an array to create a geofence specific to those groups.
Sample Request for single Group ID
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 --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"]
}'

You can create time aware geofences to trigger events between a specific time range. You can do so by passing the date and time as the second and third elements of the array to the
is_enabled
field in the body section.During the specified time interval, the entry and exit events will be triggered. However, outside the time interval, you need to ensure that the
"is_enabled"
field is set to "false".
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"
}
}
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 --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"
}
}
Adding
tag
can help filter geofences easily. This field is optional. When a geofence event is generated, the 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 --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"
}
}
Geofence can be updated using
PUT
API request along with the geofence endpoint. The following are the values that can be updated once after the Geofence is created.
Parameters | Type |
group_ids | array |
user_ids | array |
metadata | object |
color_code | string |
tag | string |
description | string |
is_enabled | array |
The values that cannot be updated once the geofence is created are:
Parameters | Type |
coordinates | array |
geometry_type | string |
geometry_radius | integer |
This API gives you a filtered list of geofences. You can filter by
geofence_id
, created_at, start_date
and end_date
fields, user_id
and group_id.
Sample Request
This filter allows you to filter the geofences within the given date range. These are non-mandatory fields and will be set to the current date by default.
You may also pass either the
start_date
or the end_date
as filters. 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'
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. If you use a
geofence_id
as a filter along with a date filter, the date filters will not be considered. Passing an empty or invalid
geofence_id
, will return an error.Make sure the
geofence_id
used here belongs to the same project linked to the API key.curl --location --request GET 'https://api.roam.ai/v1/api/geofence/?geofence_id=5f73326ce5fc231ba4b253eb' \
--header 'Api-Key: e566c098cc6b441a9c3453b6fcf76e88'
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. If you use the
user_id
as a filter along with the 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'
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. If you use
group_id
as a filter along with the date filter, the date filters will not be considered. Passing an empty or invalid group_id
, 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'
Roam's geofence feature has 2 possible events that can be triggered based on user behavior:
- 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
}
]
}
To enable geofence events for a user, you’ll need to ensure the following:
- 1.Under
Roam.toggleEvents
thegeofence
flag must be set totrue
,and - 2.Ensure you’re publishing location to the server.
If the geofence flag is false for a user and location is not being published, then geofence events will not be processed for their location updates.
Roam supports the posting of events to webhooks 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.

Geofence events can be retrieved using the Roam API. The Get Events API lets you fetch entry or exit events of the users from your event-enabled geofences. The API also lets you filter by user, geofence, location, and more.
Delete any existing geofences from your projects by using the
geofence_id.
You can delete the geofence with the delete API using the following two options:
Option 1: Delete geofence individually
You can delete one geofence at a time by passing the geofence ID as a query parameter.
Option 2: Delete geofences in bulk
By passing multiple geofence_ids as a body parameter, you can delete up to 200 geofences at a time.
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 it is part of an active campaign |
DELETE | 400 | "geofence_id": { "geofence_id": "This field is invalid." } | Invalid geofence id |
Last modified 3mo ago