Skip to content

Geofence API

The Geolocation service provides the following APIs:

Run the OnEnter action

Run the OnStay action

Run the OnExit action

Retrieve geopoints from a geofence

Run the OnEnter Action

Requests the server to run the configured OnEnter action for a geofence either for all geopoints located within the geofence or for the specified geopoint.

Method:

POST

URL

https://api.backendless.com/<applicaton-id>/<REST-api-key>/geo/fence/onenter?geoFence=<geofenceName>

where:

Argument                Description
<application id> ID of the application which can be obtained from the Manage > App Settings screen of the Backendless Console
<REST-api-key> REST API key of your application. You can get the value from the Manage > App Settings section of the Backendless Console.
<geofenceName> name of the geofence for which the OnEnter action will run.

Request headers

Content-Type: application/json  
user-token: optional value obtained as a result of the login operation.

where:

Argument                Description
Content-Type Must be set to application/json. This header is mandatory.
user-token Optional header. Contains a value returned by Backendless in a preceding user Login API call. If user-token is set in the request, the currently logged in user will be assigned to the ownerId property of the user object which is being saved.  Additionally, the operation will be executed with the security policy associated currently logged in user. This means all permissions associated with the user and the roles assigned to the user will be enforced by Backendless.

Request body

The body may optionally contain a geopoint object. If specified, the geopoint will be used as the context for the action execution. Any substitutions which the action may be configured with will be resolved against the geopoint. If there is no geopoint in the body, the action is executed on all geopoints located within the geofence.

Response body

Number of geopoints for which the action has been executed.

Example

curl -H "Content-Type:application/json" \  
-d "{ \"latitude\": 10, \"longitude\": 20}" \  
-X POST \  
https://api.backendless.com/XXXX-XXXX-XXXX/ZZZZ-ZZZZ-ZZZZ/geo/fence/onenter?geoFence=RadioCityHall

Run the OnStay Action

Requests the server to run the configured OnStay action for a geofence either for all geopoints located within the geofence or for the specified geopoint.

Method:

POST

URL

https://api.backendless.com/<application-id>/<REST-api-key>/geo/fence/onstay?geoFence=<geofenceName>

where:

Argument                Description
<application id> ID of the application which can be obtained from the Manage > App Settings screen of the Backendless Console
<REST-api-key> REST API key of your application. You can get the value from the Manage > App Settings section of the Backendless Console.
<geofenceName> name of the geofence for which the OnStay action will run.

Request headers

Content-Type: application/json  
user-token: optional value obtained as a result of the login operation.

where:

Argument                Description
Content-Type Must be set to application/json. This header is mandatory.
user-token Optional header. Contains a value returned by Backendless in a preceding user Login API call. If user-token is set in the request, the currently logged in user will be assigned to the ownerId property of the user object which is being saved.  Additionally, the operation will be executed with the security policy associated currently logged in user. This means all permissions associated with the user and the roles assigned to the user will be enforced by Backendless.

Request body

The body may optionally contain a geopoint object. If specified, the geopoint will be used as the context for the action execution. Any substitutions which the action may be configured with will be resolved against the geopoint. If there is no geopoint in the body, the action is executed on all geopoints located within the geofence.

Response body

Number of geopoints for which the action has been executed.

Example

curl -H "Content-Type:application/json" \  
-d "{ \"latitude\": 10, \"longitude\": 20}" \  
-X POST \  
https://api.backendless.com/XXXX-XXXX-XXXX/ZZZZ-ZZZZ-ZZZZ/geo/fence/onstay?geoFence=RadioCityHall

Run the OnExit Action

Requests the server to run the configured OnExit action for a geofence either for all geopoints located within the geofence or for the specified geopoint.

Method:

POST

URL

https://api.backendless.com/<application-id>/<REST-api-key>/geo/fence/onxit?geoFence=<geofenceName>

where:

Argument                Description
<application id> ID of the application which can be obtained from the Manage > App Settings screen of the Backendless Console
<REST-api-key> REST API key of your application. You can get the value from the Manage > App Settings section of the Backendless Console.
<geofenceName> name of the geofence for which the OnExit action will run.

Request headers

Content-Type: application/json  
user-token: optional value obtained as a result of the login operation.

where:

Argument                Description
Content-Type Must be set to application/json. This header is mandatory.
user-token Optional header. Contains a value returned by Backendless in a preceding user Login API call. If user-token is set in the request, the currently logged in user will be assigned to the ownerId property of the user object which is being saved.  Additionally, the operation will be executed with the security policy associated currently logged in user. This means all permissions associated with the user and the roles assigned to the user will be enforced by Backendless.

Request body

The body may optionally contain a geopoint object. If specified, the geopoint will be used as the context for the action execution. Any substitutions which the action may be configured with will be resolved against the geopoint. If there is no geopoint in the body, the action is executed on all geopoints located within the geofence.

Response body

Number of geopoints for which the action has been executed.

Example

curl -H Content-Type:application/json \  
-d "{ \"latitude\": 10, \"longitude\": 20}" \  
-X POST \  
https://api.backendless.com/XXXX-XXXX-XXXX/ZZZZ-ZZZZ-ZZZZ/geo/fence/onexit?geoFence=RadioCityHall

Retrieve Geopoints from a Geofence

Retrieves a collection of geopoints currently located within a geofence

Method:

POST

URL

https://api.backendless.com/<application-id>/<REST-api-key>/geo/points?geoFence=<geofenceName>&pagesize=<pageSize>&offset=<offset>&includemetadata=<metaInResponse> 

where:

Argument                Description
<application id> ID of the application which can be obtained from the Manage > App Settings screen of the Backendless Console
<REST-api-key> REST API key of your application. You can get the value from the Manage > App Settings section of the Backendless Console.
<geoFenceName> name of a geofence to retrieve the geopoints from.
<pageSize> number of geo points to be returned in the response.
<metaInResponse> a Boolean value indicating whether geo point metadata should be included in the response. Supported values are true or false.
<offset> sequential (zero-based) index from where to run the search. For example, suppose the first search query returned 50 geo points (pageSize is set to 50). A subsequent search should set the offset value to 50 in order to get the next page of search results.

Request headers

user-token: optional value obtained as a result of the login operation.

where:

Argument                Description
user-token Optional header. Contains a value returned by Backendless in a preceding user Login API call. If user-token is set in the request, the currently logged in user will be assigned to the ownerId property of the user object which is being saved.  Additionally, the operation will be executed with the security policy associated currently logged in user. This means all permissions associated with the user and the roles assigned to the user will be enforced by Backendless.

Response Body

A JSON array of geo points, identical to response for the Search in Category request.

Example

The example loads geopoints from a geofence called "Manhattan". The returned geopoints will have metadata properties initialized.

curl -X GET \  
https://api.backendless.com/XXXX-XXXX-XXXX/ZZZZ-ZZZZ-ZZZZ/geo/points?geoFence=Manhattan&includemetadata=true