Skip to content

Geofence API

Client-side geofence monitoring is the process of tracking the position of the device in relation to the geofences defined in Backendless. Functionality  in Backendless client libraries loads information about geofences (or a specific geofence) and tracks device positional changes. When the device crosses, stays in, or exits a geofence boundary, the Backendless client executes a callback. Based on this, Backendless client-side monitoring supports the following options:

In-app callback interface

Client applications must use a special interface to receive local callbacks. The Backendless library invokes the interface methods when the current device's location enters, stays in or exits a geofence:

package com.backendless.geo.geofence;

public interface IGeofenceCallback
{
  void geoPointEntered( String geofenceName, 
                        String geofenceId, 
                        double latitude, 
                        double longitude );
  void geoPointStayed( String geofenceName, 
                       String geofenceId, 
                       double latitude, 
                       double longitude );
  void geoPointExited( String geofenceName, 
                       String geofenceId, 
                       double latitude, 
                       double longitude );
}
Consider the following example of the in-app callback interface implementation. The example creates and saves a geopoint with dummy coordinates (0,0). As the device changes its location, the in-app callback is executed and the code saves the device's location on the server. See the example below.

final GeoPoint me = new GeoPoint( 0, 0 );

Backendless.Geo.savePoint( me, new AsyncCallback<GeoPoint>()
{
    @Override
    public void handleResponse( GeoPoint response )
    {
        me.setObjectId( response.getObjectId() );
    }

    @Override
    public void handleFault( BackendlessFault fault )
    {

    }
});

final AsyncCallback<GeoPoint> saveCallback;
saveCallback = new AsyncCallback<GeoPoint>()
{
    @Override
    public void handleResponse( GeoPoint response )
    {
       System.out.println( "Geopoint position has been updated" );
    }

    @Override
    public void handleFault( BackendlessFault fault )
    {

    }
};

IGeofenceCallback callback = new IGeofenceCallback()
{
    @Override
    public void geoPointEntered( String geofenceName, 
                                 String geofenceId, 
                                 double latitude, 
                                 double longitude )
    {
        me.setLatitude( latitude );
        me.setLongitude( longitude );
        Backendless.Geo.savePoint( me, saveCallback );
    }

    @Override
    public void geoPointStayed( String geofenceName, 
                                String geofenceId, 
                                double latitude, 
                                double longitude )
    {
        me.setLatitude( latitude );
        me.setLongitude( longitude );
        Backendless.Geo.savePoint( me, saveCallback );
    }

    @Override
    public void geoPointExited( String geofenceName, 
                                String geofenceId, 
                                double latitude, 
                                double longitude )
    {
        me.setLatitude( latitude );
        me.setLongitude( longitude );
        Backendless.Geo.savePoint( me, saveCallback );
    }
};
  • Remote callback for the on enter, on stay and on exit event. The Backendless client automatically notifies the server when a geofence event occurs. If there is an action associated with the event, Backendless executes on the server-side.

The API applies the options above either to a specific or all geofences. It is important to note that a Backendless client can monitor only the geofences which are not activated for the server-side monitoring. In other words, a geofence with the "Is Active" toggle in the Backendless console set to ON cannot be tracked on the client-side.

Android App Configuration

An Android application which uses the Backendless Geofence API must include the following permission in the Android app manifest:

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

To enable location tracking while app is running in background, add the following manifest:

<service android:name="com.backendless.geo.LocationTracker"/>

In order to enable location tracking after device reboot (or power cycle), the following must be added to application's manifest:

<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />  
<receiver android:name="com.backendless.AutoStart" >  
    <intent-filter>  
        <action android:name="android.intent.action.BOOT_COMPLETED"/>  
    </intent-filter>  
</receiver>

Geofence APIs

The Geolocation service provides the following APIs:

Client-side location monitoring:

Executing a geofence action:

Retrieve geopoints from a geofence

Start location monitoring for a specific geofence with an in-app callback

Starts client-side monitoring of the device's location for the geofence. Uses the callback to notify when the device enters, stays in, or exits the geofence boundary.

public void startGeofenceMonitoring( String geofenceName, 
                                     IGeofenceCallback callback, 
                                     final AsyncCallback<Void> responder ) 
                                               throws BackendlessException

where:

Argument                Description
geofenceName name of a geofence, which monitors the device's location.
callback a callback object that the Backendless library notifies when the device crosses, stays in, or exits the geofence boundary.
responder a responder that notifies the calling program when the operation started successfully geofence monitoring or  resulted in error.

Example

IGeofenceCallback geofenceCallback = new IGeofenceCallback()
{
  @Override
  public void geoPointEntered( String geofenceName, 
                               String geofenceId, 
                               double latitude, 
                               double longitude )
  {

  }

  @Override
  public void geoPointStayed( String geofenceName, 
                              String geofenceId, 
                              double latitude, 
                              double longitude )
  {

  }

  @Override
  public void geoPointExited( String geofenceName, 
                              String geofenceId, 
                              double latitude, 
                              double longitude )
  {

  }
};

AsyncCallback<Void> completionCallback = new AsyncCallback<Void>()
{
    @Override
    public void handleResponse( Void response )
    {
        Log.i( "GEOFENCING", "Geofence monitoring has been started" );
    }

    @Override
    public void handleFault( BackendlessFault fault )
    {
        Log.e( "GEOFENCING", "Error - " + fault.getMessage() );
    }
};

Backendless.Geo.startGeofenceMonitoring( "Shopping Mall", 
                                         geofenceCallback, 
                                         completionCallback );

Start location monitoring for all geofences with an in-app callback

Starts client-side monitoring of the device's location for all geofences. Uses the callback to notify when the device enters, stays in or exits a geofence boundary.

public void startGeofenceMonitoring( IGeofenceCallback callback, 
                                     final AsyncCallback<Void> responder ) 
                                              throws BackendlessException

where:

Argument                Description
callback a callback object that the Backendless library notifies when the device crosses, stays in, or exits the geofence boundary.
responder a responder that notifies the calling program when the operation started successfully geofence monitoring or  resulted in error.

Example

IGeofenceCallback geofenceCallback = new IGeofenceCallback()
{
  @Override
  public void geoPointEntered( String geofenceName, 
                               String geofenceId, 
                               double latitude, 
                               double longitude )
  {

  }

  @Override
  public void geoPointStayed( String geofenceName, 
                              String geofenceId, 
                              double latitude, 
                              double longitude )
  {

  }

  @Override
  public void geoPointExited( String geofenceName, 
                              String geofenceId, 
                              double latitude, 
                              double longitude )
  {

  }
};

AsyncCallback<Void> completionCallback = new AsyncCallback<Void>()
{
    @Override
    public void handleResponse( Void response )
    {
        Log.i( "GEOFENCING", "Geofence monitoring has been started for all geofences" );
    }

    @Override
    public void handleFault( BackendlessFault fault )
    {
        Log.e( "GEOFENCING", "Error - " + fault.getMessage() );
    }
};

Backendless.Geo.startGeofenceMonitoring( geofenceCallback, completionCallback );

Start location monitoring for a specific geofence with a remote callback

Starts client-side monitoring of the device's location for a specific geofence. This function notifies the server when the device enters, stays in, or exits the geofence boundary.

public void startGeofenceMonitoring( String geofenceName, 
                                     GeoPoint geoPoint, 
                                     final AsyncCallback<Void> responder ) 
                                            throws BackendlessException

where:

Argument                Description
geofenceName name of a geofence, which monitors the device's location.
geoPoint the geopoint object to pass to the server. The geopoint represents the current device location. It may be a geopoint stored in the Geolocation storage (with objectId assigned to it) or a new geopoint object. The Backendless client assigns the current location coordinates to the geoPoint object before sending it to the server.
responder a responder that notifies the calling program when the operation has started successfully geofence monitoring or has resulted in error.

Example

// Create a geopoint. The coordinates are irrelevant
// because Backendless client will update them when the 
// current location of the device where this program runs changes.
// The geopoint with the updated coordinates will be delivered 
// to the server when the the current location triggers a 
// geofence event;
GeoPoint myLocation = new GeoPoint( 0, 0 );

// assign device's token to geopoint metadata.
// the token is received by registering device
// with Backendless for push notifications.
myLocation.addMetadata( "__deviceId", deviceToken );

AsyncCallback<Void> callback = new AsyncCallback<Void>()
{
    @Override
    public void handleResponse( Void response )
    {
       Log.i( "GEOFENCING", "Geofence monitoring has been started" );
    }

    @Override
    public void handleFault( BackendlessFault fault )
    {
       Log.e( "GEOFENCING", "Error - " + fault.getMessage() );
    }
};

Backendless.Geo.startGeofenceMonitoring( "Radio City Hall", myLocation, completionCallback );

Start location monitoring for all geofences with a remote callback

Starts client-side monitoring of the device's location for all geofences. This function notifies the server when the device enters, stays in or exits a geofence boundary.

public void startGeofenceMonitoring( GeoPoint geoPoint, 
                                     final AsyncCallback<Void> responder ) 
                                              throws BackendlessException

where:

Argument                Description
geoPoint the geopoint object to pass to the server. The geopoint represents the current device location. It may be a geopoint stored in the Geolocation storage (with objectId assigned to it) or a new geopoint object. The Backendless client assigns current location coordinates to the geoPoint object before sending it to the server.
responder a responder used for to notify the calling program when the operation has either successfully started geofence monitoring or resulted in error.

Example

// Create a geopoint. The coordinates are irrelevant
// because Backendless client will update them when the
// current location of the device where this program runs changes.
// The geopoint with the updated coordinates will be delivered
// to the server when the the current location triggers a
// geofence event;
GeoPoint myLocation = new GeoPoint( 0, 0 );

// assign device's token to geopoint metadata.
// the token is received by registering device
// with Backendless for push notifications.
myLocation.addMetadata( "__deviceId", deviceToken );

AsyncCallback<Void> callback = new AsyncCallback<Void>()
{
    @Override
    public void handleResponse( Void response )
    {
       Log.i( "GEOFENCING", "Geofence monitoring has been started" );
    }

    @Override
    public void handleFault( BackendlessFault fault )
    {
        Log.e( "GEOFENCING", "Error - " + fault.getMessage() );
    }
};

Backendless.Geo.startGeofenceMonitoring( myLocation, completionCallback );

Stop location monitoring for a specific geofence

Stops client-side monitoring of the device's location for the geofence.

public void stopGeofenceMonitoring( String geofenceName );

where:

Argument                Description
geofenceName name of the geofence for which device location monitoring will stop.

Example

Backendless.Geo.stopGeofenceMonitoring( "Home" );

Stop location monitoring for all geofences

Stops client-side monitoring of device locations for all geofences.

public void stopGeofenceMonitoring();

Example

Backendless.Geo.stopGeofenceMonitoring();

Configure Location Tracker

Configures client-side location tracker

public void setLocationTrackerParameters( int minTime, 
                                          int minDistance, 
                                          int acceptedDistanceAfterReboot )

where:

Argument                Description
minTime minimum time in milliseconds as an interval between location updates;
minDistance minimum distance in meters as a difference between locations; if distance is less than this value, android service will not send new coordinates to app;
acceptedDistanceAfterReboot max distance between two locations after rebooting the device; if distance is greater than this value, service resets location status and starts fence(s) monitoring from the beginning. Used when user reboots the device.

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.

Blocking API

public int runOnEnterAction( String geoFenceName ) 
                                        throws BackendlessException;
public void runOnEnterAction( String geoFenceName, GeoPoint geoPoint ) 
                                        throws BackendlessException;

Non-Blocking API

public void runOnEnterAction( String geoFenceName, 
                              final AsyncCallback<Integer> responder ) 
                                          throws BackendlessException;
public void RunOnEnterAction( String geofenceName, 
                              GeoPoint geoPoint, 
                              AsyncCallback<Void> callback );

where:

Argument                Description
geofenceName name of the geofence on which the OnEnter action will run.
geoPoint a geopoint which 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.
callback a responder that notifies the calling program when the operation has requested successfully the action to be executed or resulted in error.

Example

Backendless.Geo.runOnEnterAction( "Home" );

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.

Blocking API

public int runOnStayAction( String geoFenceName ) 
                                throws BackendlessException;
public void runOnStayAction( String geoFenceName, 
                             GeoPoint geoPoint ) 
                                throws BackendlessException;

Non-Blocking API

public void runOnStayAction( String geoFenceName, 
                             final AsyncCallback<Integer> responder ) 
                                          throws BackendlessException;
public void RunOnStayAction( String geofenceName, 
                             GeoPoint geoPoint, 
                             AsyncCallback<Void> callback );

where:

Argument                Description
geofenceName name of a geofence on which the OnStay action will run.
geoPoint a geopoint which 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.
callback a responder that notifies the calling program when the operation has requested successfully the action to be executed or resulted in error.

Example

Backendless.Geo.runOnStayAction( "Home" );

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.

Blocking API

public int runOnExitAction( String geoFenceName ) 
                                    throws BackendlessException;
public void runOnExitAction( String geoFenceName, 
                             GeoPoint geoPoint ) 
                                    throws BackendlessException;

Non-Blocking API

public void runOnExitAction( String geoFenceName, 
                             final AsyncCallback<Integer> responder ) 
                                        throws BackendlessException;
public void RunOnExitAction( String geofenceName, 
                             GeoPoint geoPoint, 
                             AsyncCallback<Void> callback );

where:

Argument                Description
geofenceName name of a geofence on which the OnExit action will run.
geoPoint a geopoint which 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.
callback a responder that notifies the calling program when the operation has requested successfully the action to be executed or resulted in error.

Example

Backendless.Geo.runOnExitAction( "Home" );

Retrieve Geopoints from a Geofence

Retrieves a collection of geopoints currently located within a geofence

Blocking API

public List<GeoPoint> getPoints( String geofenceName, BackendlessGeoQuery query ) 
                                                          throws BackendlessException;

Non-Blocking API

public void getPoints( final String geofenceName, 
                       final BackendlessGeoQuery query, 
                       final AsyncCallback<List<GeoPoint>> callback );

where:

Argument                Description
geofenceName name of a geofence to retrieve the geopoints from.
query a BackendlessGeoQuery object controlling various aspects of geopoint retrieval such as paging, inclusion of metadata and/or SQL search query.
callback a responder that notifies the calling program when the operation has successfully retrieved geopoints or resulted in error.

Example

The example loads geopoints from a geofence called "Manhattan". The returned geopoints will have metadata properties and will match the SQL query:

BackendlessGeoQuery geoQuery = new BackendlessGeoQuery();
geoQuery.setIncludeMeta( true );
geoQuery.setWhereClause( "businessType='restaurant' and rating > 3" );

Backendless.Geo.getPoints( "Manhattan", geoQuery, 
           new AsyncCallback<List<GeoPoint>>()
{
    @Override
    public void handleResponse( BackendlessCollection<GeoPoint> points )
    {
        // "points" collection contains geopoints which satisfy the query
    }

    @Override
    public void handleFault( BackendlessFault fault )
    {
      Log.e( "MYAPP", "server reported an error - " + fault.getMessage() );
    }
} );