1.45 Data usage analytics

The usage analytics API lets you access information about how people are using DHIS2 based on data analysis. When users access favorites, an event is recorded. The event consists of the user name, the UID of the favorite, when the event took place, and the type of event. The different types of events are listed in the table.

/api/26/dataStatistics

The usage analytics API lets you retrieve aggregated snapshots of usage analytics based on time intervals. The API captures user views (for example the number of times a chart or pivot table has been viewed by a user) and saved analysis favorites (for example favorite charts and pivot tables). DHIS2 will capture nightly snapshots which are then aggregated at request.

1.45.1 Request query parameters

The usage analytics (data statistics) API supports two operations:

  • POST: creates a view event

  • GET: retrieves aggregated statistics

1.45.2 Create view events (POST)

The usage analytics API lets you create event views. The dataStatisticsEventType parameter describes what type of item was viewed. The favorite parameter indicates the identifier of the relevant favorite.

URL that creates a new event view of charts:

POST /api/24/dataStatistics?eventType=CHART_VIEW&favorite=LW0O27b7TdD

A successful save operation returns HTTP status code 201. The table below shows the supported types of events.

Supported event types
Key Description
REPORT_TABLE_VIEW Report table (pivot table) view
CHART_VIEW Chart view
MAP_VIEW Map view (GIS)
EVENT_REPORT_VIEW Event report view
EVENT_CHART_VIEW Event chart view
DASHBOARD_VIEW Dashboard view
DATA_SET_REPORT_VIEW Data set report view

1.45.3 Retrieve aggregated usage analytics report (GET)

The usage analytics (data statistics) API lets you specify certain query parameters when asking for an aggregated report.

Query parameters for aggregated usage analytics (data statistics)
Query parameter Required Description Options
startDate Yes Start date for period Date in yyyy-MM-dd format
endDate Yes End date for period Date in yyyy-MM-dd format
interval Yes Type of interval to be aggregated DAY, WEEK, MONTH, YEAR

The startDate and endDate parameters specify the period for which snapshots are to be used in the aggregation. You must format the dates as shown above. If no snapshots are saved in the specified period, an empty list is sent back. The parameter called interval specifies what type of aggregation will be done.

API query that creates a query for a yearly aggregation:

GET /api/24/dataStatistics?startDate=2014-01-02&endDate=2016-01-01&interval=MONTH

1.45.4 Retrieve top favorites

The usage analytics API lets you retrieve the top favorites used in DHIS2, and by user.

Query parameters for top favorites
Query parameter Required Description Options
eventType Yes The data statistics event type See above table
pageSize No Size of the list returned For example 5, 10, 25. Default is 25
sortOrder No Descending or ascending ASC or DESC. Default is DESC.
username No If specified, the response will only contain favorites by this user. For example ‘admin’

The API query can be used without username, and will then find the top favorites of the system. If username is specified, the response will only contain the top favorites of that user.

/api/24/dataStatistics/favorites?eventType=CHART_VIEW&pageSize=25&sortOrder=ASC

/api/24/dataStatistics/favorites?eventType=CHART_VIEW&pageSize=25&sortOrder=ASC&username=admin

1.45.5 Response format

You can return the aggregated data in a usage analytics response in several representation formats. The default format is JSON. The available formats and content types are:

  • json (application/json)

  • xml (application/xml)

  • html (text/html)

API query that requests an usage analytics response in XML format:

/api/24/dataStatistics.xml?startDate=2014-01-01&endDate=2016-01-01&interval=WEEK

You must retrieve the aggregated usage analytics response with the HTTP GET method. This allows you to link directly from Web pages and other HTTP-enabled clients to usage analytics responses. To do functional testing use the cURL library.

Execute this command against the demo database to get an usage analytics response in JSON format:

curl "play.dhis2.org/demo/api/24/dataStatistics?startDate=2016-02-01&endDate=2016-02-14&
interval=WEEK" -u admin:district

The JSON response looks like this:

[
  {
    "year": 2016,
    "week": 5,
    "mapViews": 2181,
    "chartViews": 2227,
    "reportTableViews": 5633,
    "eventReportViews": 6757,
    "eventChartViews": 9860,
    "dashboardViews": 10082,
    "totalViews": 46346,
    "averageViews": 468,
    "averageMapViews": 22,
    "averageChartViews": 22,
    "averageReportTableViews": 56,
    "averageEventReportViews": 68,
    "averageEventChartViews": 99,
    "averageDashboardViews": 101,
    "savedMaps": 1805,
    "savedCharts": 2205,
    "savedReportTables": 1995,
    "savedEventReports": 1679,
    "savedEventCharts": 1613,
    "savedDashboards": 0,
    "savedIndicators": 1831,
    "activeUsers": 99,
    "users": 969
  },
  {
    "year": 2016,
    "week": 6,
    "mapViews": 2018,
    "chartViews": 2267,
    "reportTableViews": 4714,
    "eventReportViews": 6697,
    "eventChartViews": 9511,
    "dashboardViews": 12181,
    "totalViews": 47746,
    "averageViews": 497,
    "averageMapViews": 21,
    "averageChartViews": 23,
    "averageReportTableViews": 49,
    "averageEventReportViews": 69,
    "averageEventChartViews": 99,
    "averageDashboardViews": 126,
    "savedMaps": 1643,
    "savedCharts": 1935,
    "savedReportTables": 1867,
    "savedEventReports": 1977,
    "savedEventCharts": 1714,
    "savedDashboards": 0,
    "savedIndicators": 1646,
    "activeUsers": 96,
    "users": 953
  }
]

1.45.6 Retrieve statistics for a favorite

You can retrieve the number of view for a specific favorite by using the favorites resource, where {favorite-id} should be substituted with the identifier of the favorite of interest:

/api/24/dataStatistics/favorites/{favorite-id}.json

The response will contain the number of views for the given favorite and look like this:

{
  "views": 3
}