Using reports

The purpose of 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

At minimum, to be able to generate some reports, user must have at least the following prerequisities in place:

  • 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 to 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 responses the measures are grouped by interval, which can be a day, a week or a month. The start parameter defines additionally on what day a week is started and what time of the day a new day is started. Note that the format of start and end parameters is date-time string for which the timezone is zero offset from UTC. This means that the hours must be set differently depending to the user's desired 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 dates would be defined as in the following request:

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

A reportId will be provided in the successful response body. You can get different reports related to the selected time range and rule using the reportId. The report is available for one week after which it needs to be created again.

Note

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

Check the status of the report

Report is created asyncronously. Thus, it might be that the report creation has not yet finished. To get the report creation status, you can make a GET query using the reportId without any additional query parameters.

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

In the response body you will find status property, which should be completed before you can get the actual reports.

Make a GET query with the query parameters interval, measure and trackingId defined. With the parameters defined as in the example below, you will get a report telling how long time was the specified device dwelling per each report 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'

In the response body you will find an array of timestamp value pairs. The timestamp defines the start of the interval to which the value relates. The unit of the value depends on the measure. When the measure is duration, the value is in seconds.

Get an interval report that combines data from all associated devices

Make a GET query with the query parameters interval, measure, groupBy and method defined. With the parameters defined as in the example below, you will get a report telling how long time did an average device dwell per each report 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 an interval report that combines data from all geofences

Make a GET query with the query parameters interval, measure, groupBy and method defined. With the parameters defined as in the example below, you will get a report telling how long time did devices dwell on average in a geofence per each report 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

Geofence-related reports are applicable only when the report is created for a dwelling rule.

Get a top list of devices

Make a GET query with the query parameters measure and groupBy defined. With the parameters defined as in the example below, you will get a list of devices with the respective cumulative dwelling duration throughout the report 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'

In the response body of this request you will find an array of trackingId value pairs. The list is automatically ordered by the value in descending order. In case you want to change the sorting, you can define additional query parameter sort=value:asc.

results matching ""

    No results matching ""