Geofences

The geofencing feature is supported from Location SDK V3.2.0 onward.

Create a Geofence

There is no limit on the number of geofences you can create. However, for optimal performance, create only the geofences required by your business logic. The Location SDK supports creating geofences using four methods: AMAP POI, administrative district, custom circle, and custom polygon.

Note: Geofencing does not function correctly when the app's location permission is set to "approximate location."

1. Initialize the Geofence Client

Create a GeoFenceClient instance and configure the trigger actions to monitor.

// Instantiate the GeoFence client
GeoFenceClient mGeoFenceClient = new GeoFenceClient(getApplicationContext());

// Set the desired fence trigger behaviors to detect
// By default, only user entry into the fence is detected
// public static final int GEOFENCE_IN     - User enters the geofence
// public static final int GEOFENCE_OUT    - User exits the geofence
// public static final int GEOFENCE_STAYED - User stays inside the geofence for 10 minutes

mGeoFenceClient.setActivateAction(GEOFENCE_IN | GEOFENCE_OUT | GEOFENCE_STAYED);

2. Create an AMAP POI Geofence

Two methods are available for creating POI geofences: keyword search and nearby search by coordinates.

Create a Geofence by Keyword

Use the following method to perform a POI keyword search and create a geofence.

mGeoFenceClient.addGeoFence(String keyword, String poiType, String city, int size,String customId);

Parameter Description

Name	Meaning
keyword	POI keyword
poiType	POI type
city	City name where the POI is located
size	Number of POI results to use
customId	Custom business ID associated with the geofence

Example

mGeoFenceClient.addGeoFence(
    "Shoukai Plaza",          
    "Office Building",        
    "Beijing",                 
    1,
    "000FATE23 (Attendance Tracking)"  
);

Create a Geofence by Nearby POI

Use the following method to perform a POI nearby search and create a geofence.

mGeoFenceClient.addGeoFence(String keyword, String poiType, DPoint point, float aroundRadius, int size,String customId);

Parameter Description

Name	Meaning
keyword	POI keyword
poiType	POI type
point	Center point of the search area
aroundRadius	Search radius in meters
size	Number of POI results to use
customId	Custom business ID associated with the geofence

Example

// Create a center point
DPoint centerPoint = new DPoint();
centerPoint.setLatitude(39.123D);
centerPoint.setLongitude(116.123D);

// Add the geofence
mGeoFenceClient.addGeoFence("KFC", "Restaurant", centerPoint, 1000F, 10, "CustomID");

3. Create an Administrative District Geofence

Create a geofence based on an administrative district keyword.

mGeoFenceClient.addGeoFence(String keyword, String customId)；

Parameter Description

Name	Meaning
keyword	Administrative district keyword
customId	Custom business ID associated with the geofence

Example

mGeoFenceClient.addGeoFence("Haidian District", "00FDTW103 (Cosmetics Promotion Event in Haidian, Beijing)");

4. Create a Custom Geofence

Custom geofences include circular and polygon types. Each call creates a single custom geofence. To create multiple custom geofences, call the method multiple times.

Circular Geofence

Provide a center point and a radius.

mGeoFenceClient.addGeoFence(DPoint point, float radius, String customId);

Parameter Description

Name	Meaning
point	Center point of the geofence
radius	Radius of the geofence in meters
customId	Custom business ID associated with the geofence

Example

// Create a center point
DPoint centerPoint = new DPoint();
centerPoint.setLatitude(39.123D);
centerPoint.setLongitude(116.123D);

// Add the circular geofence
mGeoFenceClient.addGeoFence(centerPoint, 500F, "CustomID");

Polygon Geofence

Provide a list of boundary points.

mGeoFenceClient.addGeoFence(List<DPoint> points, String customId);

Parameter Description

Name	Meaning
points	Boundary coordinates of the polygon
customId	Custom business ID associated with the geofence

Example

List<DPoint> points = new ArrayList<DPoint>();

points.add(new DPoint(39.992702, 116.470470));
points.add(new DPoint(39.994387, 116.472498));
points.add(new DPoint(39.994478, 116.474161));
points.add(new DPoint(39.993163, 116.474504));
points.add(new DPoint(39.991363, 116.472605));

mGeoFenceClient.addGeoFence(points,"CustomID");

Start Location Detection

Once a geofence is created successfully, location detection starts automatically. No additional setup is required — the SDK handles this internally.

The SDK uses an adaptive location strategy to balance accuracy and power consumption: location frequency is reduced when the user is far from any geofence and increased as the user approaches a geofence, ensuring sufficient accuracy for geofence transition detection.

Important: To continuously monitor geofence transitions in the background, you must start GeoFenceClient in a local service and ensure the service remains alive.

Receive Geofence Creation Callbacks

Geofence creation results are delivered through the GeoFenceListener callback. Use this callback to check whether the geofence was created successfully and to inspect the geofence details.

// Create callback listener
GeoFenceListener fenceListenter = new GeoFenceListener() {
    
    @Override
    public void onGeoFenceCreateFinished(List<GeoFence> geoFenceList,
            int errorCode) {
        if(errorCode == GeoFence.ADDGEOFENCE_SUCCESS){ // Check if the geofence was created successfully
            tvReult.setText("Geofence added successfully!!");
            // geoFenceList contains the list of added geofences, which can be used to view the created geofences
        } else {
            tvReult.setText("Failed to add geofence!!");
        }
    }
};
mGeoFenceClient.setGeoFenceListener(fenceListenter); // Set the callback listener

Receive Geofence Transition Broadcasts

A geofence transition occurs when the user's location changes relative to a geofence. The three types of transitions are: enter, exit, and stay. Transitions are delivered as Android broadcasts.

The set of transitions to monitor is configured using the setActivateAction(int[] actions) method during initialization (see Step 1).

When location detection starts, the SDK immediately sends an initial status broadcast for each geofence, indicating whether the user is currently IN (inside) or OUT (outside) the geofence. This is not a transition broadcast — it is a one-time status report. You will receive these initial broadcasts when new geofences are created or when the monitored actions change. Subsequent broadcasts are transition broadcasts, sent only when the user's position relative to a geofence changes.

1. Create and Set a PendingIntent

// Define the action string for receiving broadcasts
public static final String GEOFENCE_BROADCAST_ACTION = "com.location.apis.geofencedemo.broadcast";
// Create and set PendingIntent
mGeoFenceClient.createPendingIntent(GEOFENCE_BROADCAST_ACTION);

2. Create a Broadcast Receiver

private BroadcastReceiver mGeoFenceReceiver = new BroadcastReceiver() {
    @Override
    public void onReceive(Context context, Intent intent) {
        if (intent.getAction().equals(GEOFENCE_BROADCAST_ACTION)) {
            // Parse the broadcast content
        }
    }
};

3. Register the Broadcast Receiver

IntentFilter filter = new IntentFilter(
                ConnectivityManager.CONNECTIVITY_ACTION);
        filter.addAction(GEOFENCE_BROADCAST_ACTION);
        registerReceiver(mGeoFenceReceiver, filter);

4. Parse the Broadcast Content

In the onReceive method of your broadcast receiver, parse the transition data from the Bundle.

// Get the Bundle
Bundle bundle = intent.getExtras();
// Get the geofence trigger action:
int status = bundle.getInt(GeoFence.BUNDLE_KEY_FENCESTATUS);
// Get the custom geofence identifier:
String customId = bundle.getString(GeoFence.BUNDLE_KEY_CUSTOMID);
// Get the geofence ID:
String fenceId = bundle.getString(GeoFence.BUNDLE_KEY_FENCEID);
// Get the currently triggered geofence object:
GeoFence fence = bundle.getParcelable(GeoFence.BUNDLE_KEY_FENCE);

Clear All Geofences

When geofences are no longer needed, call the following method to remove all geofences.

mGeoFenceClient.removeGeoFence()；