Using reports

The purpose of the Reports API is to collect and analyze all the relevant event data generated by all the devices of the project. This guide assumes that suitable event history exist.

Prerequisites

To be able to generate reports, the user must have at least the following in place:

A Tracking device
At least one of the following rules created and associated to the device:
- Dwelling rule
- Utilization rule
- Detention rule
In case of a dwelling rule, at least one geofence needs to be associated with the device
Event history related to the rule

Start report creation

Start report creation by defining a rule and a time range. In this example, for simplicity, let's assume that the rule is a dwelling rule. The same logic applies for other rule types as well, unless stated otherwise.

In some of the reports the metrics are grouped by an interval, which can be a day, a week or a month. The start parameter defines additionally which day is the first day of the week and which hour is the first hour of the day.

NOTE: The format of start and end parameters is a date-time string in UTC timezone.

For example, if the user wants to get a report from the week 1 of 2021, starting on Monday midnight until the end of February 2021, and the user is in the UTC+01 timezone, the start and end parameters would be defined as the following:

curl -X POST \
  https://tracking.api.here.com/reports/v4 \
  -H 'authorization: Bearer {userToken}' \
  -H 'content-type: application/json' \
  -d '{
  "start": "2021-01-03T23:00:00.000Z",
  "end": "2021-02-27T23:00:00.000Z",
  "ruleId": {ruleId}
}'

This will return a reportId upon a successful report creation. The same reportId can be used for various reports queries within the specified time range and for the specified rule. The report is available for one week after which it needs to be recreated.

If you are a member of multiple projects, please specify the project ID in the projectId query parameter.

Check the status of the report creation

Reports are created asyncronously. To get the report creation status, make the following request specifying the reportId without any extra parameters:

curl -X GET \
  https://tracking.api.here.com/reports/v4/{reportId} \
  -H 'authorization: Bearer {userToken}' \
  -H 'content-type: application/json'

This will return the status of the report creation. When status is pending or started, check it later again. Only when the status is completed, one can fetch the actual reports.

Get a simple interval report for a device

Make a GET request specifying the interval, trackingId and measure query parameters. The latter is the target metric to be calculated. In the example below, you will get a report on how long the specified device was dwelling during each week.

curl -X GET \
  https://tracking.api.here.com/reports/v4/{reportId}?measure=duration&interval=week&trackingId={trackingId} \
  -H 'authorization: Bearer {userToken}' \
  -H 'content-type: application/json'

The response body will contain an array of timestamp-value pairs. The timestamp defines the start of each interval and the value is the metric calculated over this interval. The unit of the value depends on the metric. When the metric is duration, the value will be in seconds.

Get a combined interval report for all devices

Make a GET request specifying the interval, measure, groupBy and method query parameters. In the example below, you will get a report on how long a device dwelled on average during each week.

curl -X GET \
  https://tracking.api.here.com/reports/v4/{reportId}?measure=duration&interval=week&groupBy=asset&method=average \
  -H 'authorization: Bearer {userToken}' \
  -H 'content-type: application/json'

Get a combined interval report for all geofences

Make a GET request specifying the interval, measure, groupBy and method query parameters. In the example below, you will get a report on how long a device dwelled on average in a geofence during each week.

curl -X GET \
  https://tracking.api.here.com/reports/v4/{reportId}?measure=duration&interval=week&groupBy=geofence&method=cumulative \
  -H 'authorization: Bearer {userToken}' \
  -H 'content-type: application/json'

NOTE: Getting geofence-specific reports is applicable only for a reportId created with a dwelling rule.

Get a top list of devices

Make a GET request specifying the measure and groupBy query parameters. In the example below, you will get a report on a list of devices with the respective cumulative dwelling durations for the whole report time period.

curl -X GET \
  https://tracking.api.here.com/reports/v4/{reportId}?measure=duration&groupBy=asset \
  -H 'authorization: Bearer {userToken}' \
  -H 'content-type: application/json'

The response body will contain an array of trackingId-value pairs, sorted in descending order. In case you want to change the sorting, you can define an additional query parameter sort=value:asc.

Create reports