Documentation

IMPORTANT: The TomTom Geofencing API and Geofencing module in the Maps SDK for Android are currently in Public Preview. To find out what our Public Preview is and to revisit our Terms and Conditions, see the Public Preview Page. Under Public Preview, specific terms and conditions apply which are described here in section 4 of the Terms and Conditions

Initialization

In order to use Geofencing you will need the appropriate Geofencing API Key. For more information on obtaining and configuring TomTom API Keys and their configuration, go to the "Getting started" page.

The Geofencing API provides you with the ability to define virtual barriers on real geographic locations. With geofenced object location you can determine if that object is located within or outside of predefined virtual barriers on real geographic locations.

The Geofencing API offers a number of services including the Configuration service, Report service, Projects service, Objects service, Transitions service, and Archive service. Details are available in the Geofencing API. Currently, the Maps SDK only offers the Report service.

Regular API

Create a Geofencing API object in the following manner:

private val geofencingApi = GeofencingApi(context, BuildConfig.GEOFENCING_API_KEY)

GeofencingApi geofencingApi = new GeofencingApi(context, BuildConfig.GEOFENCING_API_KEY)

Reactive API

The other way to use Geofencing is to initialize a Reactive API. Create a Reactive Geofencing API object in the following manner:

private val rxGeofencingApi = RxGeofencingApi(context, BuildConfig.GEOFENCING_API_KEY)

RxGeofencingApi rxGeofencingApi = new RxGeofencingApi(context, BuildConfig.GEOFENCING_API_KEY);

Report service

The Report service allows you to generate a location report which determines if an object is within fences. The Response of this service contains a summary and:

• A list of fences that the object/point is inside of.
• A list of fences within a specified radius that the object is not inside of.

If no fences match the query parameters, then the list returned in the Report can be empty. The outside fences list can only be empty if there are no more fences left in the project.

To use the Report you need to have at least one project defined within a configuration.

For your mobile app you can use a listener approach or Reactive approach when preparing the Report query.

Listener approach

The first approach involves using the obtainReport() method, taking the ReportQuery and ` ReportListener implementation as parameters.

To obtain a Report for an object you will need to create a query in the following manner:

1ReportQuery.Builder(position.toLocation())
2    .projectId(projectId)
3    .range(QUERY_RANGE)
4    .build()

1return new ReportQuery.Builder(location)
2        .projectId(projectId)
3        .range(QUERY_RANGE)
4        .build();

Then register an onResult listener to receive a callback with the Report service Response:

1private val resultListener = object :
2    ReportCallback {
3    override fun onSuccess(report: Report) {
4        processResponse(report)
5    }
6
7    override fun onError(error: GeofencingException) {
8        Toast.makeText(context, error.message, Toast.LENGTH_LONG).show()
9    }
10}

1private ReportCallback resultListener = new ReportCallback() {
2
3    @Override
4    public void onSuccess(@NonNull Report report) {
5        markerDrawer.removeFenceMarkers();
6        markerDrawer.updateMarkersFromResponse(report);
7    }
8
9    @Override
10    public void onError(@NonNull GeofencingException error) {
11        Toast.makeText(getContext(), R.string.report_service_request_error, Toast.LENGTH_LONG).show();
12    }
13};

Now you can perform a Report service Request by calling:

geofencingApi.obtainReport(query, resultListener);

Reactive approach

To obtain a Report for an object you will need to create a query in the following manner:

1ReportQuery.Builder(position.toLocation())
2    .projectId(projectId)
3    .range(QUERY_RANGE)
4    .build()

1return new ReportQuery.Builder(location)
2        .projectId(projectId)
3        .range(QUERY_RANGE)
4        .build();

Then subscribe for Report:

1rxGeofencingApi.obtainReport(reportQuery)
2    .subscribeOn(workingScheduler)
3    .observeOn(resultScheduler)
4    .subscribe(
5        { response -> result.value = Resource.success(response) },
6        { error -> result.value = Resource.error(null, Error(error.message)) }
7    )
8    .let { disposable.set(it) }

1rxGeofencingApi.obtainReport(reportQuery)
2        .subscribeOn(Schedulers.newThread())
3        .observeOn(AndroidSchedulers.mainThread())
4        .subscribe(
5                report -> { /* Handle result */ },
6                error -> { /* Handle exception */ }
7        );