Analytics

Analytics To access analytical, aggregated data in DHIS 2 you can work with the analytics resource. The analytics resource 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. + role="italic">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. DHIS 2 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 @@ -1140,7 +1142,7 @@ Categories co - Not possible to define dimension items + Not possible to define dimension items for categories Data element group sets @@ -1166,73 +1168,93 @@ 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: api/analytics?dimension=dx:fbfJHSPpUQD;cYeuwXTCPkU&dimension=pe:2012Q1;2012Q2&dimension=ou:O6uvpzGd5pu;lc3eMKXaEfw + To query for data broken down by categories instead of data element totals you can include + the category dimension in the query string, for instance like this: + api/analytics?dimension=dx:fbfJHSPpUQD;cYeuwXTCPkU&dimension=coc&dimension=pe:201201&dimension=ou:O6uvpzGd5pu;lc3eMKXaEfw 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: api/analytics?Bpx0589u8y0:oRVt7g429ZO;MAs88nJc9nL&dimension=pe:2012&dimension=ou:ImspTQPwCqd - Data elements, indicator and data sets are part of a common data dimension, identifier 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 data element group set and - organisation unit group set dimensions, all dimension items will be used in the query if no - dimension items are given for the dimension. 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 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 dimension, instead the response - will contain the categories which are linked to the data. + A few things to be aware of when using the analytics resource are listed below. + + + Data elements, indicator and data sets are part of a common data dimension, identifier + 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 data element group set and organisation unit group set dimensions, all + dimension items will be used in the query if no dimension items are given for the + dimension. + + + 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 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 dimension. Instead the response + will contain the categories which are linked to the data values. + +

Request query parameters The analytics resource lets you specify a range of query parameters: - Query parameters - - - - - - - - Query parameter - Required - Description - Options - - - - - dimension - Yes - Dimensions to be retrieved - Any dimension - - - filter - No - Filters to apply to the query - Any dimension - - - aggregationType - No - Aggregation type to use in the aggregation process - SUM, AVERAGE_INT, AVERAGE_INT_DISAGGREGATION, AVERAGE_BOOL, COUNT - - - measureCriteria - No - Filters for the data/measures - EQ, GT, GE, LT, LE - - - -

- The dimension query parameter defines which dimensions - should be included in the analytics query. Any number of dimensions can be specified in a - query. + Query parameters + + + + + + + + Query parameter + Required + Description + Options + + + + + dimension + Yes + Dimensions to be retrieved, repeated for each + Any dimension + + + filter + No + Filters to apply to the query, repeated for each + Any dimension + + + aggregationType + No + Aggregation type to use in the aggregation process + SUM, AVERAGE_INT, AVERAGE_INT_DISAGGREGATION, AVERAGE_BOOL, COUNT + + + measureCriteria + No + Filters for the data/measures + EQ, GT, GE, LT, LE + + + + The dimension query parameter defines which + dimensions should be included in the analytics query. Any number of dimensions can be + specified in a query. The dimension parameter should be repeated for each dimension to + include in the query. 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 in a query. As an example, to query for certain data elements filtered by the - periods and organisation units you can use the following URL: + specified in a query. The filter parameter should be repeated for each filter to use in the + query. As an example, to query for certain data elements filtered by the periods and + organisation units you can use the following URL: api/analytics?dimension=dx:fbfJHSPpUQD;cYeuwXTCPkU&filter=pe:2012Q1;2012Q2&filter=ou:O6uvpzGd5pu;lc3eMKXaEfw The aggregationType query parameter lets you define which aggregation operator should be used for the query. By default the aggregation operator @@ -1275,15 +1297,15 @@ html - As an example, to request an analytics response in HTML format you can use the following + As an example, to request an analytics response in XML format you can use the following URL: - api/analytics.html?dimension=dx:fbfJHSPpUQD&dimension=pe:2012&dimension=ou:O6uvpzGd5pu;lc3eMKXaEfw + api/analytics.xml?dimension=dx:fbfJHSPpUQD&dimension=pe:2012&dimension=ou:O6uvpzGd5pu;lc3eMKXaEfw 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 "apps.dhis2.org/demo/api/analytics??dimension=dx:eTDtyyaSA7f;FbKK4ofIv5R&dimension=pe:2012Q1;2012Q2&filter=ou:ImspTQPwCqd" -u admin:district + curl "apps.dhis2.org/demo/api/analytics.json?dimension=dx:eTDtyyaSA7f;FbKK4ofIv5R&dimension=pe:2012Q1;2012Q2&filter=ou:ImspTQPwCqd" -u admin:district The JSON response will look like this: { "headers": [ @@ -1342,12 +1364,13 @@ 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 a measure, the word "Value". The meta - property is true if the column contains dimension items - or false if the column contains a measure (aggregated - value). 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. + 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. @@ -1394,5 +1417,15 @@

+ Generating the analytics tables + The analytics resource is utilzing a set of database tables which are optimized for data + aggregation. These tables must be updated in order to reflect the latest, captured data. + This task is typically one for a system administrator and not consuming clients. These + tables can be generated and scheduled to be refreshed at regular intervals through the user + interface of DHIS 2. It can also be generated directly from the Web API - to do so you can + make a request for the following resource using the HTTP PUT + method:http://<server-url>/api/resourceTables/analytics +