1.34. Analytics

To access analytical, aggregated data in DHIS2 you can work with the analytics resource. The analytics resource is powerful as it lets you query and retrieve data aggregated along all available data dimensions. For instance, you can ask the analytics resource to provide the aggregated data values for a set of data elements, periods and organisation units. Also, you can retrieve the aggregated data for a combination of any number of dimensions based on data elements and organisation unit group sets.


1.34.1. Request query parameters

The analytics resource lets you specify a range of query parameters:

Table 1.64. Query parameters

Query parameterRequiredDescriptionOptions
dimensionYesDimensions and dimension items to be retrieved, repeated for each.Any dimension
filterNoFilters and filter items to apply to the query, repeated for each.Any dimension
aggregationTypeNoAggregation type to use in the aggregation process.SUM | AVERAGE | COUNT | STDDEV | VARIANCE
measureCriteriaNoFilters for the data/measures.EQ | GT | GE | LT | LE
preAggregationMeasureCriteriaNoFilters for the date/measure before aggregationEQ | GT | GE | LT | LE
skipMetaNoExclude the meta data part of the response (improves performance).false | true
skipDataNoExclude the data part of the response.false | true
skipRoundingNoSkip rounding of data values, i.e. provide full precision.false | true
hierarchyMetaNoInclude names of organisation unit ancestors and hierarchy paths of organisation units in the metadata.false | true
ignoreLimitNoIgnore limit on max 50 000 records in response - use with care.false | true
tableLayoutNoUse plain data source or table layout for response.false | true
hideEmptyRowsNoHides empty rows in response, applicable when table layout is true.false | true
showHierarchyNoDisplay full org unit hierarchy path together with org unit name.false | true
includeNumDenNoInclude the numerator and denominator used to calculate the value in the response.false | true
displayPropertyNoProperty to display for metadata.NAME | SHORTNAME
outputIdSchemeNoIdentifier scheme to use for metadata items the query response, can be identifier, code or attributes.UID | CODE | ATTRIBUTE:<UID>
inputIdSchemeNoIdentifier scheme to use for metadata items in the query request, can be identifier, code or attributes.UID | CODE | ATTRIBUTE:<UID>
approvalLevelNoInclude data which has been approved at least up to the given approval level, refers to identfier of approval level.Identifier of approval level
relativePeriodDateNoDate used as basis for relative periods.Date.
userOrgUnitNoExplicitly define the user org units to utilize, overrides organisation units associated with current user, multiple identifiers can be separated by semi-colon.Organisation unit identifiers.
columnsNoDimensions to use as columns for table layout.Any dimension (must be query dimension)
rowsNoDimensions to use as rows for table layout.Any dimension (must be query dimension)

The dimension query parameter defines which dimensions should be included in the analytics query. Any number of dimensions can be specified. The dimension parameter should be repeated for each dimension to include in the query response. The query response can potentially contain aggregated values for all combinations of the specified dimension items.

The filter parameter defines which dimensions should be used as filters for the data retrieved in the analytics query. Any number of filters can be specified. The filter parameter should be repeated for each filter to use in the query. A filter differs from a dimension in that the filter dimensions will not be part of the query response content, and that the aggregated values in the response will be collapsed on the filter dimensions. In other words, the data in the response will be aggregated on the filter dimensions, but the filters will not be included as dimensions in the actual response. As an example, to query for certain data elements filtered by the periods and organisation units you can use the following URL:


The aggregationType query parameter lets you define which aggregation operator should be used for the query. By default the aggregation operator defined for data elements included in the query will be used. If your query does not contain any data elements, but does include data element groups, the aggregation operator of the first data element in the first group will be used. The order of groups and data elements is undefined. This query parameter allows you to override the default and specify a specific aggregation operator. As an example you can set the aggregation operator to "count" with the following URL:


The measureCriteria query parameter lets you filter out ranges of data records to return. You can instruct the system to return only records where the aggregated data value is equal, greater than, greater or equal, less than or less or equal to certain values. You can specify any number of criteria on the following format, where critieria and value should be substituted with real values:


As an example, the following query will return only records where the data value is greater or equal to 6500 and less than 33000:


Similar to measureCriteria, the preAggregationMeasureCriteria query parameter lets you filter out data, only before aggregation is performed. For example, the following query only aggregates data where the original value is within the criterias defined:


In order to have the analytics resource generate the data in the shape of a ready-made table, you can provide the tableLayout parameter with true as value. Instead of generating a plain, normalized data source, the analytics resource will now generate the data in table layout. You can use the columns and rows parameters with dimension identifiers separated by semi-colons as values to indicate which ones to use as table columns and rows. 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:


1.34.2. Dimensions and items

DHIS2 features a multi-dimensional data model with several fixed and dynamic data dimensions. The fixed dimensions are the data element, period (time) and organisation unit dimension. You can dynamically add dimensions through categories, data element group sets and organisation unit group sets. The table below displays the available data dimensions in DHIS2. Each data dimension has a corresponding dimension identifier, and each dimension can have a set of dimension items:

Table 1.65. Dimensions and dimension items

DimensionDimension idDimension items
Data elements, indicators, data set reporting rate metrics, data element operands, program indicators, program data elements, program attributesdxData element, indicator, data set reporting rate metrics, data element operand, program indicator, program attribute identifiers, keyword DE_GROUP-<group-id>, IN_GROUP-<group-id>, use <dataelement-id>.<optioncombo-id> for data element operands, <program-id>.<dataelement-id> for program data elements, <program-id>.<attribute-id> for program attributes.
Periods (time)peISO periods and relative periods, see "date and period format"
Organisation unit hierarchyouOrganisation unit identifiers, and keywords USER_ORGUNIT, USER_ORGUNIT_CHILDREN, USER_ORGUNIT_GRANDCHILDREN, LEVEL-<level> and OU_GROUP-<group-id>
Category option combinationscoCategory option combo identifers (omit to get all items)
Attribute option combinationsaoCategory option combo identifers (omit to get all items)
Categories<category id>Category option identifiers (omit to get all items)
Data element group sets<group set id>Data element group identifiers (omit to get all items)
Organisation unit group sets<group set id>Organisation unit group identifiers (omit to get all items)
Category option group sets<group set id>Category option group identifiers (omit to get all items)

It is not necessary to be aware of which objects are used for the various dynamic dimensions when designing analytics queries. You can get a complete list of dynamic dimensions by visiting this URL in the Web API:


The base URL to the analytics resource is api/analytics. To request specific dimensions and dimension items you can use a query string on the following format, where dim-id and dim-item should be substituted with real values:


As illustrated above, the dimension identifier is followed by a colon while the dimension items are separated by semi-colons. As an example, a query for two data elements, two periods and two organisation units can be done with the following URL:


To query for data broken down by category option combinations instead of data element totals you can include the category dimension in the query string, for instance like this:


When selecting data elements you can also select all data elements in a group as items by using the DE_GROUP-<id> syntax:


When selecting data set reporting rates, the syntax contains of a data set identifier followed by a reporting rate metric:


To query for program data elements (of tracker domain type) you can get those by specifying the program for each data element using the <program-id>.<dataelement-id> syntax:


To query for program attributes (tracked entity attributes) you can get those by specifying the program for each attribute using the <program.id>.<attribute-id> syntax:


To query for organisation unit group sets and data elements you can use the following URL - notice how the group set identifier is used as dimension identifier and the groups as dimension items:


To query for data elements and categories you can use this URL. Use the category identifier as dimension identifier and the category options as dimension items:


To query using relative periods and organisation units associated with the current user you can use a URL like this:


When selecting organisation units for a dimension you can select an entire level optionally constrained by any number of boundary organisation units with the LEVEL-<level> syntax. Boundary refers to a top node in a sub-hierarchy, meaning that all organisation units at the given level below the given boundary organisation unit in the hierarchy will be included in the response, and is provided as regular organisation unit dimension items. A simple query for all org units at level three:


A query for level three and four with two boundary org units can be specified like this:


When selecting organisation units you can also select all organisation units in an organisation unit group to be included as dimension items using the OU_GROUP-<id> syntax. The organisation units in the groups can optionally be constrained by any number of boundary organisation units. Both the level and the group items can be repeated any number of times:


You can utilize identifier schemes for the metadata part of the analytics response with the outputIdScheme property like this. You can use ID, code and attributes as identifier scheme:


A few things to be aware of when using the analytics resource are listed below.

  • Data elements, indicator, data set reporting rates, program data elements and program indicators are part of a common data dimension, identified as "dx". This means that you can use any of data elements, indicators and data set identifiers together with the "dx" dimension identifier in a query.

  • For the category, data element group set and organisation unit group set dimensions, all dimension items will be used in the query if no dimension items are specified.

  • For the period dimension, the dimension items are ISO period identifiers and/or relative periods. Please refer to the section above called "Date and period format" for the period format and available relative periods.

  • For the organisation unit dimension you can specify the items to be the organisation unit or sub-units of the organisation unit associated with the user currently authenticated for the request using they keys USER_ORGUNIT or USER_ORGUNIT_CHILDREN as items, respectively. You can also specify organisation unit identifiers directly, or a combination of both.

  • For the organisation unit dimension you can specify the organisation hierarchy level and the boundary unit to use for the request on the format LEVEL-<level>-<boundary-id>; as an example LEVEL-3-ImspTQPwCqd implies all organisation units below the given boundary unit at level 3 in the hierarchy.

  • For the organisation unit dimension the dimension items are the organisation units and their sub-hierarchy - data will be aggregated for all organisation units below the given organisation unit in the hierarchy.

  • You cannot specify dimension items for the category option combination dimension. Instead the response will contain the items which are linked to the data values.

1.34.3. The dx dimension

The dx dimension is a special dimension which can contain all of the following data types.

Table 1.66. Data dx dimension types

TypeSyntaxDescriptionData source
Indicator<indicator-id>Indicator identifier.Aggregated data
IndicatorIN_GROUP-<indicatorgroup-id>Keyword followed by indicator group identifier. Will include all indicators in the group in the response.Aggregated data
Data element<dataelement-id> Data element identifier.Aggregated data
Data elementDE_GROUP-<dataelementgroup-id>Keyword followed by data element group identifier. Will include all data elements in the group in the response.Aggregated data
Data set<dataset-id>.<reporting-rate-metric>Data set identifier followed by reporting rate metric. Can be REPORTING_RATE | REPORTING_RATE_ON_TIME | ACTUAL_REPORTS | ACTUAL_REPORTS_ON_TIME | EXPECTED_REPORTS.Aggregated data
Program data element<program-id>.<dataelement-id>Program identifier followed by data element identifier. Reads from events within the specified program.Events from the given program
Program indicator<programindicator-id>Program indicator identifier. Reads from events from within the program associated with the program identifier.Events from the program of the program indicator

Items from all of the various dx types can be combined in an analytics request. An example looks like this:


The group syntax can be used together with any other item as well. An example looks like this:


A great way to learn how to use the analytics API is to use the DHIS2 pivot table app. You can play around with pivot tables using the various dimensions and items and click Download > Plain data source > JSON to see the resulting analytics API calls in the address bar of your Web browser.

1.34.4. Response formats

The analytics response containing aggregate data can be returned in various representation formats. As usual, you can indicate interest in a specific format by appending a file extension to the URL, through the Accept HTTP header or through the format query parameter. The default format is JSON. The available formats and content-types are listed below.

  • json (application/json)

  • jsonp (application/javascript)

  • xml (application/xml)

  • csv (application/csv)

  • html (text/html)

  • html+css

  • xls (application/vnd.ms-excel)

As an example, to request an analytics response in XML format you can use the following URL:


The analytics responses must be retrieved using the HTTP GET method. This allows for direct linking to analytics responses from Web pages as well as other HTTP-enabled clients. To do functional testing we can use the cURL library. By executing this command against the demo database you will get an analytics response in JSON format:

curl "play.dhis2.org/demo/api/26/analytics.json?dimension=dx:eTDtyyaSA7f;FbKK4ofIv5R
  &dimension=pe:2016Q1;2016Q2&filter=ou:ImspTQPwCqd" -u admin:district

The JSON response will look like this:

    "headers": [
            "name": "dx",
            "column": "Data",
            "meta": true,
            "type": "java.lang.String"
            "name": "pe",
            "column": "Period",
            "meta": true,
            "type": "java.lang.String"
            "name": "value",
            "column": "Value",
            "meta": false,
            "type": "java.lang.Double"
    "height": 4,
    "metaData": {
        "pe": [
        "ou": [
        "names": {
            "2016Q1": "Jan to Mar 2016",
            "2016Q2": "Apr to Jun 2016",
            "FbKK4ofIv5R": "Measles Coverage <1 y",
            "ImspTQPwCqd": "Sierra Leone",
            "eTDtyyaSA7f": "Fully Immunized Coverage"
    "rows": [
    "width": 3

The response represents a table of dimensional data. The headers array gives an overview of which columns are included in the table and what the columns contain. The column property shows the column dimension identifier, or if the column contains measures, the word "Value". The meta property is true if the column contains dimension items or false if the column contains a measure (aggregated data values). The name property is similar to the column property, except it displays "value" in case the column contains a measure. The type property indicates the Java class type of the column values.

The height and width properties indicate how many data columns and rows are contained in the response, respectively.

The metaData periods property contains a unique, ordered array of the periods included in the response. The metaData ou property contains an array of the identifiers of organisation units included in the response. The metaData names property contains a mapping between the identifiers used in the data response and the names of the objects they represent. It can be used by clients to substitute the identifiers within the data response with names in order to give a more meaningful view of the data table.

The rows array contains the dimensional data table. It contains columns with dimension items (object or period identifiers) and a column with aggregated data values. The example response above has a data/indicator column, a period column and a value column. The first column contains indicator identifiers, the second contains ISO period identifiers and the third contains aggregeted data values.

1.34.5. Constraints

There are several constraints on the input you can provide to the analytics resource.

  • At least one dimension must be specified in a query.

  • Dimensions cannot be specified as dimension and filter simultaneously.

  • At least one period must be specified as dimension or filter.

  • Categories cannot be specified as filter.

  • Only a single indicator can be specified as filter.

  • Only a single reporting rate can be specified as filter.

  • Data element group sets cannot be specified together with data sets.

  • Categories can only be specified together with data elements, not indicators or data sets.

  • A dimension cannot be specified more than once.

  • Fixed dimensions ("dx", "pe", "ou") must have at least one option if included in a query.

  • A table cannot contain more than 50 000 cells by default, this can be configured under system settings.

When a query request violates any of these constraints the server will return a response with status code 409 and content-type "text/plain" together with a textual description of the problem.

1.34.6. Data value set format

The analytics dataValueSet resource allows for returning aggregated data in the data value set format. This format represents raw data values, as opposed to data which has been aggregated along various dimensions. Exporting aggregated data as regular data values is useful for data exchange between systems when the target system contains data of finer granularity compared to what the destination system is storing.

As an example one can specify an indicator in the target system to summarize data for multiple data elements and import this data for a single data element in the destionation system. As another example one can aggregate data collected at organisation unit level 4 in the target system to level 2 and import that data in the destination system.

You can retrieve data in the raw data value set format from the dataValueSet resource:


The following resource representations are supported:

  • json (application/json)

  • xml (application/xml)

When using the data value set format, exactly three dimensions must be specified as analytics dimensions with at least one dimension item each:

  • Data (dx)

  • Period (pe)

  • Organisation unit (ou)

Any other dimension will be ignored. Filters will be applied as with regular analytics requests. Note that any data dimension type can be specified, including indicators, data elements, data element operands, data sets and program indicators.

An example request which aggregates data for specific indicators, periods and organisation units and returns it as regular data values in XML looks like this:


A request which aggregates data for data element operands and uses CODE as output identifier scheme looks like the below. When defining the output identifier scheme, all metadata objects part of the response are affected:


When using attribute-based identifier schemes for export there is a risk of producing duplicate data values. The boolean query parameter duplicatesOnly can be used for debugging purposes to return only duplicates data values. This response can be used to clean up the duplicates:


1.34.7. Raw data format

The analytics rawData resource allows for returning the data stored in the analytics data tables without any aggregation being performed. This is useful for clients which would like to perform aggregation and filtering on their own without having to denormalize data in the available data dimensions themselves.


The following resource representations are supported:

  • json (application/json)

  • csv (application/csv)

This resource follows the syntax of the regular analytics resource. Only a subset of the query parameters are supported. Additionally, a startDate and endDate parameter are available. The supported parameters are listed in the table below.

Table 1.67. Query parameters

Query parameterRequired / Notes
startDateNo / yyyy-MM-dd
endDateNo / yyyy-MM-dd

The dimension query parameter defines which dimensions (table columns) should be included in the response. It can optionally be constrained with items. The filter query parameter defines which items and dimensions (table columns) should be used as filter for the response.

For the organisation unit dimension, the response will contain data associated with the organisation unit and all organisation units in the sub-hierarchy (children in the tree). This is different compared to the regular analytics resource, where only the explicitly selected organisation units are included.

To retrieve a response with specific data elements, specific periods, specific organisation units and all data for two custom dimensions you can issue a request like this:


The startDate and endDate parameters allow for fetching data linked to any period between those dates. This avoids the need for defining all periods explicitly in the request:


The filter parameter can be used to filter a response without including that dimension as part of the response, this time in CSV format:


The response from the rawData resource will look identical to the regular analytics resource; the difference is that the response contain raw, non-aggregated data, suitable for further aggregation by third-party systems.

1.34.8. Debugging

When debugging analytics requests it can be useful to examine the data value source of the aggregated analytics response. The analytics/debug/sql resource will provide an SQL statement that returns the relevant content of the datavalue table. You can produce this SQL by doing a GET request with content type "text/html" or "text/plain" like below. The dimension and filter syntax is identical to regular analytics queries: