Report service

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

Give your users the ability to check if an object is inside or outside of a predefined geographic area.

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

IMPORTANT: In order to use the Report service you need to complete each of the following steps using several of the following Geofencing API methods:

1. Generate an Admin Key that can be used to administer Geofencing objects/fences/projects as described in the following example: Register Admin Key
2. Create a new project and assign it to the customer’s configuration as described in the following example: Add a new project
3. Add a new fence to a project endpoint and automatically link it to a single project as described in the following example: Add new fence to a project

Sample use case: You want to check if your user is still in the city center and/or within a certain part of the city center.

This example contains two predefined fences, one representing the center of Amsterdam and the other representing Amsterdam’s De Plantage area.

Please note: The Report service doesn’t provide you with the coordinates of a fence. These coordinates are defined while creating a fence and can only be accessed from the Fences service. In this example fences are drawn for a better understanding of this service.

IMPORTANT: The Report service example requires the:

• Geofencing API Key: You can obtain this key from from the Geofencing API site.
• Administration Key: You need to generate this key using the Register Admin Key
• Two projects with ID’s: Run the TomTomGeofencingProjectGenerator.sh script that we made for you to generate projects with fences. You can find it at the Maps SDK Examples app repository under sampleapp/scripts.
• Update the following fields in GeofencingReportPresenter with the project ID’s returned from the script:

private static final UUID PROJECT_UUID_ONE_FENCE = UUID.fromString("19892ca6-1cce-4fc1-b499-2887eeba6361")
private static final UUID PROJECT_UUID_TWO_FENCES = UUID.fromString("138b8a81-a596-49fa-8dae-496ff6e34400");

private val PROJECT_UUID_ONE_FENCE = UUID.fromString("19892ca6-1cce-4fc1-b499-2887eeba6361")
private val PROJECT_UUID_TWO_FENCES = UUID.fromString("138b8a81-a596-49fa-8dae-496ff6e34400")

Please note: You need to have jQuery installed otherwise the script will not work as intented:

• For Linux users: sudo apt install jq
• For Mac OS users: brew install jq

To obtain a report for the object you need to create a query in the following manner:

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

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

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

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};

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}

Now you can perform a Report service Request by calling:

geofencingApi.obtainReport(query, resultListener);

The Report service returns a summary and:

• A list of fences that an object is inside of.
• A list of fences that an object is outside of.

Each element of the list contains details about a fence such as name, ID of a fence, distance, and closest point.

In the following example the black marker represents an object’s position when requesting a location report. It shows a balloon after a Response is received with the names of the fences that object is inside/outside of. Green markers indicate the closest point to the fence from the object’s position.