1.42 Event analytics

The event analytics API lets you access aggregated event data and query events captured in DHIS2. This resource lets you retrieve events based on a program and optionally a program stage, and lets you retrieve and filter events on any event dimensions.

/api/26/analytics/events

1.42.1 Dimensions and items

Event dimensions include data elements, attributes, organisation units and periods. The aggregated event analytics resource will return aggregated information such as counts or averages. The query analytics resource will simply return events matching a set of criteria and does not perform any aggregation. You can specify dimension items in the form of options from option sets and legends from legend sets for data elements and attributes which are associated with such. The event dimensions are listed in the table below.

Event dimensions
Dimension Dimension id Description
Data elements <id> Data element identifiers
Attributes <id> Attribute identifiers
Periods pe ISO periods and relative periods, see “date and period format”
Organisation units ou Organisation unit identifiers and keywords USER_ORGUNIT, USER_ORGUNIT_CHILDREN, USER_ORGUNIT_GRANDCHILDREN, LEVEL-<level> and OU_GROUP-<group-id>
Organisation unit group sets <org unit group set id> Organisation unit group set identifiers
Categories <category id> Category identifiers (program attribute categories only)

1.42.2 Request query parameters

The analytics event API let you specify a range of query parameters.

Query parameters for both event query and aggregate analytics
Query parameter Required Description Options
program Yes Program identifier. Any program identifier
stage No Program stage identifier. Any program stage identifier
startDate Yes Start date for events. Date in yyyy-MM-dd format
endDate Yes End date for events. Date in yyyy-MM-dd format
dimension Yes Dimension identifier including data elements, attributes, program indicators, periods, organisation units and organisation unit group sets. Parameter can be repeated any number of times. Item filters can be applied to a dimension on the format <item-id>:<operator>:<filter>. Filter values are case-insensitive. Operators can be EQ | GT | GE | LT | LE | NE | LIKE | IN
filter No Dimension identifier including data elements, attributes, periods, organisation units and organisation unit group sets. Parameter can be repeated any number of times. Item filters can be applied to a dimension on the format <item-id>:<operator>:<filter>. Filter values are case-insensitive.
hierarchyMeta No Include names of organisation unit ancestors and hierarchy paths of organisation units in the metadata. false | true
eventStatus No Specify status of events to include. ACTIVE | COMPLETED | SCHEDULE | OVERDUE | SKIPPED
programStatus No Specify enrollment status of events to include. ACTIVE | COMPLETED | CANCELLED
relativePeriodDate string No Date identifier e.g: “2016-01-01”. Overrides the start date of the relative period
columns No Dimensions to use as columns for table layout. Any dimension (must be query dimension)
rows No Dimensions to use as rows for table layout. Any dimension (must be query dimension)
Query parameters for event query analytics only
Query parameter Required Description Options
ouMode No The mode of selecting organisation units. Default is DESCENDANTS, meaning all sub units in the hierarchy. CHILDREN refers to immediate children in the hierarchy; SELECTED refers to the selected organisation units only. DESCENDANTS, CHILDREN, SELECTED
asc No Dimensions to be sorted ascending, can reference event date, org unit name and code and any item identifiers. EVENTDATE | OUNAME | OUCODE | item identifier
desc No Dimensions to be sorted descending, can reference event date, org unit name and code and any item identifiers. EVENTDATE | OUNAME | OUCODE | item identifier
coordinatesOnly No Whether to only return events which have coordinates. false | true
page No The page number. Default page is 1. Numeric positive value
pageSize No The page size. Default size is 50 items per page. Numeric zero or positive value
Query parameters for aggregate event analytics only
Query parameter Required Description Options
value No Value dimension identifier. Can be a data element or an attribute which must be of numeric value type. Data element or attribute identifier
aggregationType No Aggregation type for the value dimension. Default is AVERAGE. |SUM|AVERAGE | AVERAGE_SUM_ORG_UNIT | COUNT | STDDEV | VARIANCE | MIN | MAX
showHierarchy No Display full org unit hierarchy path together with org unit name. false | true
displayProperty No Property to display for metadata. NAME | SHORTNAME
sortOrder No Sort the records on the value column in ascending or descending order. ASC | DESC
limit No The maximum number of records to return. Cannot be larger than 10 000. Numeric positive value
outputType No Specify output type for analytical data which can be events, enrollments or tracked entity instances. The two last options apply to programs with registration only. EVENT | ENROLLMENT | TRACKED_ENTITY_INSTANCE
collapseDataDimensions No Collapse all data dimensions (data elements and attributes) into a single dimension in the response. false | true
skipMeta No Exclude the meta data part of the response (improves performance). false | true
skipData No Exclude the data part of the response. false | true
skipRounding No Skip rounding of aggregate data values. false | true
aggregateData No Produce aggregate values for the data dimensions (as opposed to dimension items). false | true
Query parameters for cluster event analytics only
Query parameter Required Description Options
clusterSize Yes Size of clusters in meters. Numeric positive value
coordinateField No Field to base geospatial event analytics on. Default is event. Can be set to identifiers of attributes and data elements of value type coordinate. EVENT | <attribute-id> | <dataelement-id>
bbox Yes Bounding box / area of events to include in the response on the format “min longitude, min latitude, max longitude , max latitude”. String
includeClusterPoints No Include information about underlying points for each cluster, be careful if cluster represent a very high number of points. false | true

1.42.3 Event query analytics

The analytics/events/query resource lets you query for captured events. This resource does not perform any aggregation, rather it lets you query and filter for information about events.

/api/26/analytics/events/query

You can specify any number of dimensions and any number of filters in a query. Dimension item identifiers can refer to any of data elements, person attributes, person identifiers, fixed and relative periods and organisation units. Dimensions can optionally have a query operator and a filter. Event queries should be on the format described below.

/api/26/analytics/events/query/<program-id>?startDate=yyyy-MM-dd&endDate=yyyy-MM-dd
  &dimension=ou:<ou-id>;<ou-id>&dimension=<item-id>&dimension=<item-id>:<operator>:<filter>

For example, to retrieve events from the “Inpatient morbidity and mortality” program between January and October 2016, where the “Gender” and “Age” data elements are included and the “Age” dimension is filtered on “18”, you can use the following query:

/api/26/analytics/events/query/eBAyeGv0exc?startDate=2016-01-01&endDate=2016-10-31
  &dimension=ou:O6uvpzGd5pu;fdc6uOvgoji&dimension=oZg33kd9taw&dimension=qrur9Dvnyt5:EQ:18

To retrieve events for the “Birth” program stage of the “Child programme” program between March and December 2016, where the “Weight” data element, filtered for values larger than 2000:

/api/26/analytics/events/query/IpHINAT79UW?stage=A03MvHHogjR&startDate=2016-03-01&endDate=2016-12-31
  &dimension=ou:O6uvpzGd5pu&dimension=UXz7xuGCEhU:GT:2000

Sorting can be applied to the query for the event date of the event and any dimensions. To sort descending on the event date and ascending on the “Age” data element dimension you can use:

/api/26/analytics/events/query/eBAyeGv0exc?startDate=2016-01-01&endDate=2016-10-31
  &dimension=ou:O6uvpzGd5pu&dimension=qrur9Dvnyt5&desc=EVENTDATE&asc=qrur9Dvnyt5

Paging can be applied to the query by specifying the page number and the page size parameters. If page number is specified but page size is not, a page size of 50 will be used. If page size is specified but page number is not, a page number of 1 will be used. To get the third page of the response with a page size of 20 you can use a query like this:

/api/26/analytics/events/query/eBAyeGv0exc?startDate=2016-01-01&endDate=2016-10-31
  &dimension=ou:O6uvpzGd5pu&dimension=qrur9Dvnyt5&page=3&pageSize=20

1.42.3.1 Filtering

Filters can be applied to data elements, person attributes and person identifiers. The filtering is done through the query parameter value on the following format:

&dimension=<item-id>:<operator>:<filter-value>

As an example, you can filter the “Weight” data element for values greater than 2000 and lower than 4000 like this:

&dimension=UXz7xuGCEhU:GT:2000&dimension=UXz7xuGCEhU:LT:4000

You can filter the “Age” data element for multiple, specific ages using the IN operator like this:

&dimension=qrur9Dvnyt5:IN:18;19;20

You can specify multiple filters for a given item by repeating the operator and filter components, all separated with semi-colons:

&dimension=qrur9Dvnyt5:GT:5:LT:15

The available operators are listed below.

Filter operators
Operator Description
EQ Equal to
GT Greater than
GE Greater than or equal to
LT Less than
LE Less than or equal to
NE Not equal to
LIKE Like (free text match)
IN Equal to one of multiple values separated by “;”

1.42.3.2 Response formats

The default response representation format is JSON. The requests must be using the HTTP GET method. The following response formats are supported.

  • json (application/json)

  • jsonp (application/javascript)

  • xls (application/vnd.ms-excel)

As an example, to get a response in Excel format you can use a file extension in the request URL like this:

/api/26/analytics/events/query/eBAyeGv0exc.xls?startDate=2016-01-01&endDate=2016-10-31
  &dimension=ou:O6uvpzGd5pu&dimension=oZg33kd9taw&dimension=qrur9Dvnyt5

You can set the hierarchyMeta query parameter to true in order to include names of all ancestor organisation units in the meta-section of the response:

/api/26/analytics/events/query/eBAyeGv0exc?startDate=2016-01-01&endDate=2016-10-31
  &dimension=ou:YuQRtpLP10I&dimension=qrur9Dvnyt5:EQ:50&hierarchyMeta=true

The default response JSON format will look similar to this:

{
    "headers": [
    {
        "name": "psi",
        "column": "Event",
        "type": "java.lang.String",
        "hidden": false,
        "meta": false
    },
    {
        "name": "ps",
        "column": "Program stage",
        "type": "java.lang.String",
        "hidden": false,
        "meta": false
    },
    {
        "name": "eventdate",
        "column": "Event date",
        "type": "java.lang.String",
        "hidden": false,
        "meta": false
    },
    {
        "name": "coordinates",
        "column": "Coordinates",
        "type": "java.lang.String",
        "hidden": false,
        "meta": false
    },
    {
        "name": "ouname",
        "column": "Organisation unit name",
        "type": "java.lang.String",
        "hidden": false,
        "meta": false
    },
    {
        "name": "oucode",
        "column": "Organisation unit code",
        "type": "java.lang.String",
        "hidden": false,
        "meta": false
    },
    {
        "name": "ou",
        "column": "Organisation unit",
        "type": "java.lang.String",
        "hidden": false,
        "meta": false
    },
    {
        "name": "oZg33kd9taw",
        "column": "Gender",
        "type": "java.lang.String",
        "hidden": false,
        "meta": false
    },
    {
        "name": "qrur9Dvnyt5",
        "column": "Age",
        "type": "java.lang.String",
        "hidden": false,
        "meta": false
    } ],
    "metaData": {
        "names": {
            "qrur9Dvnyt5": "Age",
            "eBAyeGv0exc": "Inpatient morbidity and mortality",
            "ImspTQPwCqd": "Sierra Leone",
            "O6uvpzGd5pu": "Bo",
            "YuQRtpLP10I": "Badjia",
            "oZg33kd9taw": "Gender"
        },
        "ouHierarchy": {
            "YuQRtpLP10I": "/ImspTQPwCqd/O6uvpzGd5pu"
        },
    },
    "width": 8,
    "height": 4,
    "rows": [
        ["yx9IDINf82o", "Zj7UnCAulEk", "2016-08-05", "[5.12, 1.23]", "Ngelehun", "OU_559", "YuQRtpLP10I", "Female", "50"],
        ["IPNa7AsCyFt", "Zj7UnCAulEk", "2016-06-12", "[5.22, 1.43]", "Ngelehun", "OU_559", "YuQRtpLP10I", "Female", "50"],
        ["ZY9JL9dkhD2", "Zj7UnCAulEk", "2016-06-15", "[5.42, 1.33]", "Ngelehun", "OU_559", "YuQRtpLP10I", "Female", "50"],
        ["MYvh4WAUdWt", "Zj7UnCAulEk", "2016-06-16", "[5.32, 1.53]", "Ngelehun", "OU_559", "YuQRtpLP10I", "Female", "50"]
    ]
}

The headers section of the response describes the content of the query result. The event unique identifier, the program stage identifier, the event date, the organisation unit name, the organisation unit code and the organisation unit identifier appear as the first six dimensions in the response and will always be present. Next comes the data elements, person attributes and person identifiers which were specified as dimensions in the request, in this case the “Gender” and “Age” data element dimensions. The header section contains the identifier of the dimension item in the “name” property and a readable dimension description in the “column” property.

The metaData section, ou object contains the identifiers of all organisation units present in the response mapped to a string representing the hierarchy. This hierarchy string lists the identifiers of the ancestors (parents) of the organisation unit starting from the root. The names object contains the identifiers of all items in the response mapped to their names.

The rows section contains the events produced by the query. Each row represents exactly one event.

In order to have the event analytics resource generate the data in the shape of a ready-made table, you can provide rows and columns parameters with requested dimension identifiers separated by semi-colons as values to indicate which ones to use as table columns and rows. Instead of generating a plain, normalized data source, the event analytics resource will now generate the data in table layout. The column and rows dimensions must be present as a data dimension in the query (not a filter). Such a request can look like this:

/api/29/analytics.html+css?dimension=dx:cYeuwXTCPkU;fbfJHSPpUQD&dimension=pe:WEEKS_THIS_YEAR&filter=ou:ImspTQPwCqd&displayProperty=SHORTNAME&columns=dx&rows=pe

1.42.4 Event aggregate analytics

The analytics/events/aggregate resource lets you retrieve aggregated numbers of events captured in DHIS2. This resource lets you retrieve aggregate data based on a program and optionally a program stage, and lets you filter on any event dimension.

/api/26/analytics/events/aggregate

The events aggregate resource does not return the event information itself, rather the aggregate numbers of events matching the request query. Event dimensions include data elements, person attributes, person identifiers, periods and organisation units. Aggregate event queries should be on the format described below.

/api/26/analytics/events/aggregate/<program-id>?startDate=yyyy-MM-dd&endDate=yyyy-MM-dd
  &dimension=ou:<ou-id>;<ou-id>&dimension=<item-id>&dimension=<item-id>:<operator>:<filter>

For example, to retrieve aggregate numbers for events from the “Inpatient morbidity and mortality” program between January and October 2016, where the “Gender” and “Age” data elements are included, the “Age” dimension item is filtered on “18” and the “Gender” item is filtered on “Female”, you can use the following query:

/api/26/analytics/events/aggregate/eBAyeGv0exc?startDate=2016-01-01&endDate=2016-10-31
  &dimension=ou:O6uvpzGd5pu&dimension=oZg33kd9taw:EQ:Female&dimension=qrur9Dvnyt5:GT:50

To retrieve data for fixed and relative periods instead of start and end date, in this case May 2016 and last 12 months, and the organisation unit associated with the current user, you can use the following query:

/api/26/analytics/events/aggregate/eBAyeGv0exc?dimension=pe:201605;LAST_12_MONTHS
  &dimension=ou:USER_ORGUNIT;fdc6uOvgo7ji&dimension=oZg33kd9taw

In order to specify “Female” as a filter for “Gender” for the data response, meaning “Gender” will not be part of the response but will filter the aggregate numbers in it, you can use the following syntax:

/api/26/analytics/events/aggregate/eBAyeGv0exc?dimension=pe:2016;
  &dimension=ou:O6uvpzGd5pu&filter=oZg33kd9taw:EQ:Female

To specify the “Bo” organisation unit and the period “2016” as filters, and the “Mode of discharge” and Gender" as dimensions, where “Gender” is filtered on the “Male” item, you can use a query like this:

/api/26/analytics/events/aggregate/eBAyeGv0exc?filter=pe:2016&filter=ou:O6uvpzGd5pu
  &dimension=fWIAEtYVEGk&dimension=oZg33kd9taw:EQ:Male

To create a “Top 3 report” for “Mode of discharge” you can use the limit and sortOrder query parameters similar to this:

/api/26/analytics/events/aggregate/eBAyeGv0exc?filter=pe:2016&filter=ou:O6uvpzGd5pu
  &dimension=fWIAEtYVEGk&limit=3&sortOrder=DESC

To specify a value dimension with a corresponding aggregation type you can use the value and aggregationType query parameters. Specifying a value dimension will make the analytics engine return aggregate values for the values of that dimension in the response as opposed to counts of events.

/api/26/analytics/events/aggregate/eBAyeGv0exc.json?stage=Zj7UnCAulEk&dimension=ou:ImspTQPwCqd
  &dimension=pe:LAST_12_MONTHS&dimension=fWIAEtYVEGk&value=qrur9Dvnyt5&aggregationType=AVERAGE

1.42.4.1 Ranges / legend sets

For aggregate queries you can specify a range / legend set for numeric data element and attribute dimensions. The purpose is to group the numeric values into ranges. As an example, instead of generating data for an “Age” data element for distinct years, you can group the information into age groups. To achieve this, the data element or attribute must be associated with the legend set. The format is described below:

?dimension=<item-id>-<legend-set-id>

An example looks like this:

/api/26/analytics/events/aggregate/eBAyeGv0exc.json?stage=Zj7UnCAulEk&dimension=qrur9Dvnyt5-Yf6UHoPkdS6
  &dimension=ou:ImspTQPwCqd&dimension=pe:LAST_12_MONTHS

1.42.4.2 Response formats

The default response representation format is JSON. The requests must be using the HTTP GET method. The response will look similar to this:

{
    "headers": [
        {
            "name": "oZg33kd9taw",
            "column": "Gender",
            "type": "java.lang.String",
            "meta": false
        },
        {
            "name": "qrur9Dvnyt5",
            "column": "Age",
            "type": "java.lang.String",
            "meta": false
        },
        {
            "name": "pe",
            "column": "Period",
            "type": "java.lang.String",
            "meta": false
        },
        {
            "name": "ou",
            "column": "Organisation unit",
            "type": "java.lang.String",
            "meta": false
        },
        {
            "name": "value",
            "column": "Value",
            "type": "java.lang.String",
            "meta": false
        }
    ],
    "metaData": {
        "names": {
            "eBAyeGv0exc": "Inpatient morbidity and mortality"
        }
    },
    "width": 5,
    "height": 39,
    "rows": [
        [
            "Female",
            "95",
            "201605",
            "O6uvpzGd5pu",
            "2"
        ],
        [
            "Female",
            "63",
            "201605",
            "O6uvpzGd5pu",
            "2"
        ],
        [
            "Female",
            "67",
            "201605",
            "O6uvpzGd5pu",
            "1"
        ],
        [
            "Female",
            "71",
            "201605",
            "O6uvpzGd5pu",
            "1"
        ],
        [
            "Female",
            "75",
            "201605",
            "O6uvpzGd5pu",
            "14"
        ],
        [
            "Female",
            "73",
            "201605",
            "O6uvpzGd5pu",
            "5"
        ],
    ]
}

Note that the max limit for rows to return in a single response is 10

  1. If the query produces more than the max limit, a 409 Conflict status code will be returned.

1.42.5 Event clustering analytics

The analytics/events/cluster resource provides clustered geospatial event data. A request looks like this:

/api/26/analytics/events/cluster/eBAyeGv0exc?startDate=2016-01-01&endDate=2016-10-31&dimension=ou:LEVEL-2
  &clusterSize=100000&bbox=-13.2682125,7.3721619,-10.4261178,9.904012&includeClusterPoints=false

The cluster response provides the count of underlying points, the centre point and extent of each cluster. If the includeClusterPoints query parameter is set to true, a comma-separated string with the identifiers of the underlying events is included. A sample response looks like this:

{
    "headers": [{
        "name": "count",
        "column": "Count",
        "type": "java.lang.Long",
        "meta": false
    }, {
        "name": "center",
        "column": "Center",
        "type": "java.lang.String",
        "meta": false
    }, {
        "name": "extent",
        "column": "Extent",
        "type": "java.lang.String",
        "meta": false
    }, {
        "name": "points",
        "column": "Points",
        "type": "java.lang.String",
        "meta": false
    }],
    "width": 3,
    "height": 4,
    "rows": [
        ["3", "POINT(-13.15818 8.47567)", "BOX(-13.26821 8.4St7215,-13.08711 8.47807)", ""],
        ["9", "POINT(-13.11184 8.66424)", "BOX(-13.24982 8.51961,-13.05816 8.87696)", ""],
        ["1", "POINT(-12.46144 7.50597)", "BOX(-12.46144 7.50597,-12.46144 7.50597)", ""],
        ["7", "POINT(-12.47964 8.21533)", "BOX(-12.91769 7.66775,-12.21011 8.49713)", ""]
    ]
}

1.42.6 Event count and extent analytics

The analytics/events/count resource is suitable for geometry-related requests for retrieving the count and extent (bounding box) of events for a specific query. The query syntax is equal to the events/query resource. A request looks like this:

/api/26/analytics/events/count/eBAyeGv0exc?startDate=2016-01-01&endDate=2016-10-31&dimension=ou:O6uvpzGd5pu

The response will provide the count and extent in JSON format:

{
    extent: "BOX(-13.2682125910096 7.38679562779441,-10.4261178860988 9.90401290212795)",
    count: 59
}