Analytics¶

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.

/api/analytics

Solicitar parâmetros de consulta¶

O recurso de análise permite que você especifique uma variedade de parâmetros de consulta:

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:

/api/analytics?dimension=dx:fbfJHSPpUQD;cYeuwXTCPkU&filter=pe:2014Q1;2014Q2
  &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 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:

/api/analytics?dimension=dx:fbfJHSPpUQD&dimension=pe:2014Q1&dimension=ou:O6uvpzGd5pu
  &aggregationType=COUNT

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 criteria and value should be substituted with real values:

/api/analytics?measureCriteria=criteria:value;criteria:value

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

/api/analytics?dimension=dx:fbfJHSPpUQD;cYeuwXTCPkU&dimension=pe:2014
  &dimension=ou:O6uvpzGd5pu;lc3eMKXaEfw&measureCriteria=GE:6500;LT: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 criteria defined:

/api/analytics?dimension=dx:fbfJHSPpUQD;cYeuwXTCPkU&dimension=pe:2014
  &dimension=ou:O6uvpzGd5pu;lc3eMKXaEfw&preAggregationMeasureCriteria=GE:10;LT:100

The startDate and endDate parameters can be used to specify a custom date range to aggregate over. When specifying a date range you can not specify relative nor fixed periods as dimension or filter. The date range will filter the analytics response. You can use it like this:

/api/analytics.json?dimension=dx:fbfJHSPpUQD;cYeuwXTCPkU
  &dimension=ou:ImspTQPwCqd&startDate=2018-01-01&endDate=2018-06-01

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 a 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:

/api/analytics.html?dimension=dx:fbfJHSPpUQD;cYeuwXTCPkU&dimension=pe:2014Q1;2014Q2
  &dimension=ou:O6uvpzGd5pu&tableLayout=true&columns=dx;ou&rows=pe

The order parameter can be used for analytics resource to generate ordered data. The data will be ordered in ascending (or descending) order of values. An example request for ordering the values in descending order is:

/api/analytics?dimension=dx:fbfJHSPpUQD&dimension=pe:LAST_12_MONTHS
  &dimension=ou:O6uvpzGd5pu&order=DESC

Dimensões e itens¶

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:

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:

/api/dimensions

If you want to retrieve only the dimensional items for a given dynamic dimension you can use the example below. Pagination is disabled by default. It can be enabled by adding the pagination parameter paging=true to the URL.

/api/dimensions/J5jldMd8OHv/items?paging=true

The /dimensions API also provides an endpoint where the clients can get the recomendations for a given set of dimensions. For example:

/api/33/dimensions/recommendations?fields=id&dimension=dx:fbfJHSPpUQD

In the example above, the client will receive back all the Categories that are configured as Data dimensions and associated (through data sets and category combos) with the data element fbfJHSPpUQD. In addition, all *Organization Unit Group Set*s that are configured as Data dimensions will also (and always) be returned as part of the response.

The endpoint supports multiple data elements. If one wishes to send multiple data elements, they should be separated by ;. For example:

/api/33/dimensions/recommendations?fields=id&dimension=dx:fbfJHSPpUQD;JuTpJ2Ywq5b

Note

This endpoint returns only dimensions that can be read by the current logged user. It will check if the current user can read the data or the metadata of the respective recommended dimension. Non-authorized dimensions are omitted from the list.

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:

/api/analytics?dimension=dim-id:dim-item;dim-item&dimension=dim-id:dim-item;dim-item

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:

/api/analytics?dimension=dx:fbfJHSPpUQD;cYeuwXTCPkU
  &dimension=pe:2016Q1;2016Q2&dimension=ou:O6uvpzGd5pu;lc3eMKXaEfw

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:

/api/analytics?dimension=dx:fbfJHSPpUQD;cYeuwXTCPkU
  &dimension=co&dimension=pe:201601&dimension=ou:O6uvpzGd5pu;lc3eMKXaEfw

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

/api/analytics?dimension=dx:DE_GROUP-h9cuJOkOwY2
  &dimension=pe:201601&dimension=ou:O6uvpzGd5pu

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

/api/analytics?dimension=dx:BfMAe6Itzgt.REPORTING_RATE;BfMAe6Itzgt.ACTUAL_REPORTS
  &dimension=pe:201601&dimension=ou:O6uvpzGd5pu

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:

/api/analytics.json?dimension=dx:eBAyeGv0exc.qrur9Dvnyt5;eBAyeGv0exc.GieVkTxp4HH
  &dimension=pe:LAST_12_MONTHS&filter=ou:ImspTQPwCqd

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:

/api/analytics.json?dimension=dx:IpHINAT79UW.a3kGcGDCuk6;IpHINAT79UW.UXz7xuGCEhU
  &dimension=pe:LAST_4_QUARTERS&dimension=ou:ImspTQPwCqd

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 a dimension identifier and the groups as dimension items:

/api/analytics?dimension=Bpx0589u8y0:oRVt7g429ZO;MAs88nJc9nL
  &dimension=pe:2016&dimension=ou:ImspTQPwCqd

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

/api/analytics?dimension=dx:s46m5MS0hxu;fClA2Erf6IO&dimension=pe:2016
  &dimension=YNZyaJHiHYq:btOyqprQ9e8;GEqzEKCHoGA&filter=ou:ImspTQPwCqd

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

/api/analytics?dimension=dx:fbfJHSPpUQD;cYeuwXTCPkU
  &dimension=pe:LAST_12_MONTHS&dimension=ou:USER_ORGUNIT

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. The level value can either be a numerical level or refer to the identifier of the organisation unit level entity. A simple query for all org units at level three:

/api/analytics?dimension=dx:fbfJHSPpUQD&dimension=pe:2016&dimension=ou:LEVEL-3

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

/api/analytics?dimension=dx:fbfJHSPpUQD&dimension=pe:2016
  &dimension=ou:LEVEL-3;LEVEL-4;O6uvpzGd5pu;lc3eMKXaEf

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:

/api/analytics?dimension=dx:fbfJHSPpUQD&dimension=pe:2016
  &dimension=ou:OU_GROUP-w0gFTTmsUcF;OU_GROUP-EYbopBOJWsW;O6uvpzGd5pu;lc3eMKXaEf

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:

/api/analytics?dimension=dx:fbfJHSPpUQD;cYeuwXTCPkU
  &dimension=pe:2017Q1;2017Q2&dimension=ou:O6uvpzGd5pu&outputIdScheme=CODE

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 the 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.

A dimensão dx¶

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

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

/api/analytics.json
  ?dimension=dx:Uvn6LCg7dVU;BfMAe6Itzgt.REPORTING_RATE;IpHINAT79UW.a3kGcGDCuk6
  &dimension=pe:LAST_12_MONTHS&filter=ou:ImspTQPwCqd

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

/api/analytics.json
  ?dimension=dx:DE_GROUP-qfxEYY9xAl6;IN_GROUP-oehv9EO3vP7;BfMAe6Itzgt.REPORTING_RATE
  &dimension=pe:LAST_12_MONTHS&filter=ou:ImspTQPwCqd

Data element operands can optionally specify attribute option combinations and use wildcards e.g. to specify all category option combination values:

/api/analytics.json
  ?dimension=dx:Uvn6LCg7dVU.*.j8vBiBqGf6O;Uvn6LCg7dVU.Z4oQs46iTeR
  &dimension=pe:LAST_12_MONTHS&filter=ou:ImspTQPwCqd

Tip

A great way to learn how to use the analytics API is to use the DHIS2 Data Visualizer web app and create a pivot table. 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.

Formatos de resposta¶

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 (aplicativo/json)

• jsonp (aplicativo / javascript)

• xml (aplicativo/xml)

• csv (aplicativo/csv)

• html (texto / html)

• html + css (texto / html)

• xls (application / vnd.ms-excel)

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

/api/analytics.xml?dimension=dx:fbfJHSPpUQD
  &dimension=pe:2016&dimension=ou:O6uvpzGd5pu;lc3eMKXaEfw

A resposta JSON será semelhante a esta:

{
  "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": [
      "2016Q1",
      "2016Q2"
    ],
    "ou": [
      "ImspTQPwCqd"
    ],
    "names": {
      "2016Q1": "Jan to Mar 2016",
      "2016Q2": "Apr to Jun 2016",
      "FbKK4ofIv5R": "Measles Coverage <1 y",
      "ImspTQPwCqd": "Sierra Leone",
      "eTDtyyaSA7f": "Fully Immunized Coverage"
    }
  },
  "rows": [
    [
      "eTDtyyaSA7f",
      "2016Q2",
      "81.1"
    ],
    [
      "eTDtyyaSA7f",
      "2016Q1",
      "74.7"
    ],
    [
      "FbKK4ofIv5R",
      "2016Q2",
      "88.9"
    ],
    [
      "FbKK4ofIv5R",
      "2016Q1",
      "84.0"
    ]
  ],
  "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 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 aggregated data values.

Restrições e validação¶

There are several constraints to the input parameters you can provide to the analytics resource. If any of the constraints are violated, the API will return a 409 Conflict response and a response message looking similar to this:

`json { "httpStatus": "Conflito", "httpStatusCode": 409, "status": "ERROR", "message": "Apenas um único indicador pode ser especificado como filtro", "errorCode": "E7108" } `

The httpStatus and httpStatusCode fields indicate the HTTP status and status code per the HTTP specification. The messsage field provides a human-readable description of the validation error. The errorCode field provides a machine-readable code which can be used by clients to handle validation errors. The possible validation errors for the aggregate analytics API are described in the table below.

Formato de conjunto de valores de dados¶

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 destination 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:

/api/analytics/dataValueSet

As seguintes representações de recursos são suportadas:

• json (aplicativo/json)

• xml (aplicativo/xml)

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

• Dados (dx)

• Ponto final (pe)

• Unidade organizacional (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:

api / analytics / dataValueSet.xml? dimension = dx: Uvn6LCg7dVU; OdiHJayrsKo
  & dimension = pe: LAST_4_QUARTERS & dimension = ou: lc3eMKXaEfw; PMa2VCrupOd

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:

api / analytics / dataValueSet.json? dimension = dx: fbfJHSPpUQD.pq2XI5kz2BY; fbfJHSPpUQD.PT59n8BQbqM
  & dimension = pe: LAST_12_MONTHS & dimension = ou: ImspTQPwCqd & outputIdScheme = CODE

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:

api / analytics / dataValueSet.xml? dimension = dx: Uvn6LCg7dVU; OdiHJayrsKo
  & dimension = pe: LAST_4_QUARTERS & dimension = ou: lc3eMKXaEfw & duplicatesOnly = true

Formato de dados brutos¶

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.

/ api / analytics / rawData

As seguintes representações de recursos são suportadas:

• json (aplicativo/json)

• csv (aplicativo/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.

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 a 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:

/api/analytics/rawData.json?dimension=dx:fbfJHSPpUQD;cYeuwXTCPkU;Jtf34kNZhzP
  & dimension = J5jldMd8OHv & dimension = Bpx0589u8y0
  & dimension = pe: LAST_12_MONTHS
  & dimension = ou: O6uvpzGd5pu; fdc6uOvgoji

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:

/api/analytics/rawData.json?dimension=dx:fbfJHSPpUQD;cYeuwXTCPkU;Jtf34kNZhzP
  & dimension = J5jldMd8OHv & dimension = Bpx0589u8y0
  & startDate = 2015-01-01 & endDate = 2015-12-31
  & dimension = ou: O6uvpzGd5pu; fdc6uOvgoji

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

/api/analytics/rawData.csv?dimension=dx:fbfJHSPpUQD;cYeuwXTCPkU;Jtf34kNZhzP
  & filter = J5jldMd8OHv: uYxK4wmcPqA; tDZVQ1WtwpA
  & startDate = 2015-01-01 & endDate = 2015-12-31
  & dimension = ou: O6uvpzGd5pu

The outputIdScheme parameter is useful if you want human readable data responses as it can be set to NAME like this:

/api/analytics/rawData.csv?dimension=dx:fbfJHSPpUQD;cYeuwXTCPkU
  & filter = J5jldMd8OHv: uYxK4wmcPqA; tDZVQ1WtwpA
  & startDate = 2017-01-01 & endDate = 2017-12-31
  & dimension = ou: O6uvpzGd5pu
  & outputIdScheme = NOME

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

Depurando¶

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 are identical to regular analytics queries:

/ api / analytics / debug / sql? dimension = dx: fbfJHSPpUQD; cYeuwXTCPkU
  & filter = pe: 2016Q1; 2016Q2 & filter = ou: O6uvpzGd5pu

Análise de eventos¶

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/analytics/events

Dimensões e itens¶

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.

Solicitar parâmetros de consulta¶

A API de eventos analíticos permite que você especifique uma variedade de parâmetros de consulta.

Análise de consulta de evento¶

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/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/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/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/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/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/analytics/events/query/eBAyeGv0exc?startDate=2016-01-01&endDate=2016-10-31
  &dimension=ou:O6uvpzGd5pu&dimension=qrur9Dvnyt5&page=3&pageSize=20

Filtrando¶

Os filtros podem ser aplicados a elementos de dados, atributos de pessoas e identificadores de pessoas. A filtragem é feita por meio do valor do parâmetro de consulta no seguinte formato:

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

Como exemplo, você pode filtrar o elemento de dados "Peso" para valores maiores que 2.000 e inferiores a 4.000 da seguinte maneira:

& 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

Você pode especificar vários filtros para um determinado item, repetindo o operador e os componentes do filtro, todos separados por ponto e vírgula:

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

Os operadores disponíveis estão listados abaixo.

Time Field Filtering¶

By default, the query endpoints filter periods based on eventDate. However, it is possible to filter entries based on lastUpdated or schedule instead, by using the timeField query parameter. For example:

&timeField=LAST_UPDATED
&timeField=SCHEDULED_DATE

Enhanced conditions¶

By default enhancedConditions flag is set to false. This means all conditions expressed in dimension and filter are meant as AND conditions. For example:

dimension=a:GT:20:LT:40&dimension=b:GT:1:LT:5

translates into the following logical condition:

a>20 and a<40 and b>1 and b<5

However, there are cases in which more control on conditions might be needed and can be enabled by setting enhancedConditions query parameter to true. By doing so, a client can use a special _OR_ separator to join conditions using OR logical operator.

Exemplo:

dimension=a:GT:20:LT:40_OR_b:GT:1:LT:5&dimension=c:EQ:test

translates into the following logical condition:

((a>20 and a<40) or (b>1 and b<5)) and c = "test"

Formatos de resposta¶

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

• json (aplicativo/json)

• jsonp (aplicativo / javascript)

• xls (application / vnd.ms-excel)

Por exemplo, para obter uma resposta em formato Excel, você pode usar uma extensão de arquivo no URL de solicitação como este:

/api/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/analytics/events/query/eBAyeGv0exc?startDate=2016-01-01&endDate=2016-10-31
  &dimension=ou:YuQRtpLP10I&dimension=qrur9Dvnyt5:EQ:50&hierarchyMeta=true

O formato JSON de resposta padrão será semelhante a este:

{
  "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": "storedby",
      "column": "Stored by",
      "valueType": "TEXT",
      "type": "java.lang.String",
      "hidden": false,
      "meta": true
    },
    {
      "name": "lastupdated",
      "column": "Last Updated",
      "valueType": "DATE",
      "type": "java.time.LocalDate",
      "hidden": false,
      "meta": true
    },
    {
      "name": "createdbydisplayname",
      "column": "Created by (display name)",
      "valueType": "TEXT",
      "type": "java.lang.String",
      "hidden": false,
      "meta": true
    },
    {
      "name": "lastupdatedbydisplayname",
      "column": "Last updated by (display name)",
      "valueType": "TEXT",
      "type": "java.lang.String",
      "hidden": false,
      "meta": true
    },
    {
      "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",
      "system",
      "2018-08-07",
      "[5.12, 1.23]",
      "Ngelehun",
      "OU_559",
      "YuQRtpLP10I",
      "Female",
      "50"
    ],
    [
      "IPNa7AsCyFt",
      "Zj7UnCAulEk",
      "2016-06-12",
      "system",
      "2018-08-07",
      "[5.22, 1.43]",
      "Ngelehun",
      "OU_559",
      "YuQRtpLP10I",
      "Female",
      "50"
    ],
    [
      "ZY9JL9dkhD2",
      "Zj7UnCAulEk",
      "2016-06-15",
      "system",
      "2018-08-07",
      "[5.42, 1.33]",
      "Ngelehun",
      "OU_559",
      "YuQRtpLP10I",
      "Female",
      "50"
    ],
    [
      "MYvh4WAUdWt",
      "Zj7UnCAulEk",
      "2016-06-16",
      "system",
      "2018-08-07",
      "[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/analytics.html+css?dimension=dx:cYeuwXTCPkU;fbfJHSPpUQD&dimension=pe:WEEKS_THIS_YEAR
  &filter=ou:ImspTQPwCqd&displayProperty=SHORTNAME&columns=dx&rows=pe

Análise agregada de eventos¶

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/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/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/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/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/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/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/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/analytics/events/aggregate/eBAyeGv0exc.json?stage=Zj7UnCAulEk
  &dimension=ou:ImspTQPwCqd&dimension=pe:LAST_12_MONTHS&dimension=fWIAEtYVEGk
  &value=qrur9Dvnyt5&aggregationType=AVERAGE

To base event analytics aggregation on a specific data element or attribute of value type date or date time you can use the timeField parameter:

/api/analytics/events/aggregate/IpHINAT79UW.json?dimension=ou:ImspTQPwCqd
  &dimension=pe:LAST_12_MONTHS&dimension=cejWyOfXge6&stage=A03MvHHogjR
  &timeField=ENROLLMENT_DATE

To base event analytics aggregation on a specific data element or attribute of value type organisation unit you can use the orgUnitField parameter:

/api/analytics/events/aggregate/eBAyeGv0exc.json?dimension=ou:ImspTQPwCqd
  &dimension=pe:THIS_YEAR&dimension=oZg33kd9taw&stage=Zj7UnCAulEk
  &orgUnitField=S33cRBsnXPo

The orgUnitField parameter value may be one of the following:

Faixas / conjuntos de legendas¶

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>

Um exemplo se parece com este:

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

Formatos de resposta¶

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 000. If the query produces more than the max limit, a 409 Conflict status code will be returned.

Análise de agrupamento de eventos¶

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

/api/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 center 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)",
      ""
    ]
  ]
}

Análise de contagem e extensão de eventos¶

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/analytics/events/count/eBAyeGv0exc?startDate=2016-01-01
  &endDate=2016-10-31&dimension=ou:O6uvpzGd5pu

A resposta fornecerá a contagem e a extensão no formato JSON:

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

Restrições e validação¶

There are several constraints to the input parameters you can provide to the event analytics resource. If any of the constraints are violated, the API will return a 409 Conflict response and a response message looking similar to this:

`json { "httpStatus": "Conflito", "httpStatusCode": 409, "status": "ERROR", "message": "Pelo menos uma unidade organizacional deve ser especificada", "errorCode": "E7200" } `

The possible validation errors for the event analytics API are described in the table below.

Análise de inscrição¶

The enrollment analytics API lets you access aggregated event data and query enrollments with their event data captured in DHIS2. This resource lets you retrieve data for a program based on program stages and data elements - in addition to tracked entity attributes. When querying event data for a specific programstages within each enrollment, the data element values for each program stage will be returned as one row in the response from the api. If querying a data element in a program stage that is repeatable, the newest data element value will be used for that data element in the api response.

Dimensões e itens¶

As dimensões de inscrição incluem elementos de dados, atributos, unidades de organização e períodos. O recurso de análise de consulta simplesmente retornará inscrições que correspondem a um conjunto de critérios e não executa nenhuma agregação.

Repeatable stages¶

Data element identifier must include program stage. The program stage can be repeatable. For example the dimension edqlbukwRfQ.vANAXwtLwcT can refer to repeatable program stage. The data element of this stage is accessible via index parameters (enclosed with [ ]).

Warning: Indexing of non-repeatable program stage leads to parameter validation error.

Análise de consulta de inscrição¶

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

/api/analytics/enrollments/query

Você pode especificar qualquer número de dimensões e qualquer número de filtros em uma consulta. Os identificadores de itens de dimensão podem referir-se a qualquer um dos elementos de dados nos estágios do programa, atributos de entidade rastreados, períodos fixos e relativos e unidades de organização. Dimensões podem opcionalmente ter um operador de consulta e um filtro. As consultas de inscrição devem seguir o formato descrito abaixo.

/api/analytics/enrollments/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>

Por exemplo, para recuperar inscrições no programa de "Cuidado pré-natal" de janeiro de 2019, em que o "Nome" é obtido dos atributos, os elementos de dados "Condições crônicas" e "Tabagismo" são incluídos na primeira fase do programa, e "Valor de hemoglobina" do seguinte estágio do programa, e apenas mulheres com "doenças crônicas" seriam incluídas. Você pode usar a seguinte consulta:

/api/analytics/enrollments/query/WSGAb5XwJ3Y.json?dimension=ou:ImspTQPwCqd
  &dimension=w75KJ2mc4zz&dimension=WZbXY0S00lP.de0FEHSIoxh:eq:1&dimension=w75KJ2mc4zz
  &dimension=WZbXY0S00lP.sWoqcoByYmD&dimension=edqlbukwRfQ.vANAXwtLwcT
  &startDate=2019-01-01&endDate=2019-01-31

Para recuperar as inscrições no programa de "Cuidado pré-natal" do mês passado (em relação ao momento em que a consulta é executada), onde os elementos de dados "Condições crônicas" e "Tabagismo" estão incluídos na primeira fase do programa, e " Valor de hemoglobina "do estágio do programa de acompanhamento, incluindo apenas mulheres fumantes com hemoglobina inferior a 20:

/api/analytics/enrollments/query/WSGAb5XwJ3Y.json?dimension=ou:ImspTQPwCqd
  &dimension=WZbXY0S00lP.de0FEHSIoxh&dimension=w75KJ2mc4zz
  &dimension=WZbXY0S00lP.sWoqcoByYmD:eq:1&dimension=edqlbukwRfQ.vANAXwtLwcT:lt:20
  &dimension=pe:LAST_MONTH

A classificação pode ser aplicada à consulta para as datas de inscrição e incidente da inscrição:

/api/analytics/enrollments/query/WSGAb5XwJ3Y.xls?dimension=ou:ImspTQPwCqd
  &columns=w75KJ2mc4zz&dimension=WZbXY0S00lP.sWoqcoByYmD&dimension=pe:LAST_MONTH
  &stage=WZbXY0S00lP&pageSize=10&page=1&asc=ENROLLMENTDATE&ouMode=DESCENDANTS

A paginação pode ser aplicada à consulta especificando o número da página e os parâmetros de tamanho da página. Se o número da página for especificado, mas o tamanho da página não, um tamanho de página de 50 será usado. Se o tamanho da página for especificado, mas o número da página não, um número de página 1 será usado. Para obter a segunda página da resposta com um tamanho de página de 10, você pode usar uma consulta como esta:

/api/analytics/enrollments/query/WSGAb5XwJ3Y.json?dimension=ou:ImspTQPwCqd
  &dimension=WZbXY0S00lP.de0FEHSIoxh&dimension=w75KJ2mc4zz&dimension=pe:LAST_MONTH
  &dimension=WZbXY0S00lP.sWoqcoByYmD&pageSize=10&page=2

Filtrando¶

Os filtros podem ser aplicados a elementos de dados, atributos de pessoas e identificadores de pessoas. A filtragem é feita por meio do valor do parâmetro de consulta no seguinte formato:

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

Como exemplo, você pode filtrar o elemento de dados "Peso" para valores maiores que 2.000 e inferiores a 4.000 da seguinte maneira:

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

Você pode filtrar o atributo "Idade" para várias idades específicas usando o operador IN como este:

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

Você pode especificar vários filtros para um determinado item, repetindo o operador e os componentes do filtro, todos separados por ponto e vírgula:

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

Time Field Filtering¶

By default, the query endpoints filter periods based on enrollmentDate. However, it is possible to filter entries based on lastUpdated instead, by using the timeField query parameter.

&timeField=LAST_UPDATED

NV keyword¶

A special keyword NV can be used to filter by null values

Filter by AGE is null

&dimension=qrur9Dvnyt5:EQ:NV

Filter by AGE is not null

&dimension=qrur9Dvnyt5:NE:NV

Filter by AGE is 18, 19 or is null

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

NV can be used with EQ, NE and IN operators

Operators¶

Os operadores disponíveis estão listados abaixo.

Solicitar parâmetros de consulta¶

A API de consulta de inscrição de análise permite especificar uma variedade de parâmetros de consulta.

Formatos de resposta¶

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

• json (aplicativo/json)
• xml (aplicativo/xml)
• xls (application / vnd.ms-excel)
• csv (aplicativo / csv)
• html (texto / html)
• html + css (texto / html)

Por exemplo, para obter uma resposta em formato Excel, você pode usar uma extensão de arquivo no URL de solicitação como este:

/api/analytics/enrollments/query/WSGAb5XwJ3Y.xls?dimension=ou:ImspTQPwCqd
  &dimension=WZbXY0S00lP.de0FEHSIoxh&columns=w75KJ2mc4zz
  &dimension=WZbXY0S00lP.sWoqcoByYmD&dimension=pe:LAST_MONTH&stage=WZbXY0S00lP
  &pageSize=10&page=1&asc=ENROLLMENTDATE&ouMode=DESCENDANTS

O formato JSON de resposta padrão será semelhante a este:

{
  "headers": [
    {
      "name": "pi",
      "column": "Enrollment",
      "valueType": "TEXT",
      "type": "java.lang.String",
      "hidden": false,
      "meta": true
    },
    {
      "name": "tei",
      "column": "Tracked entity instance",
      "valueType": "TEXT",
      "type": "java.lang.String",
      "hidden": false,
      "meta": true
    },
    {
      "name": "enrollmentdate",
      "column": "Enrollment date",
      "valueType": "DATE",
      "type": "java.util.Date",
      "hidden": false,
      "meta": true
    },
    {
      "name": "incidentdate",
      "column": "Incident date",
      "valueType": "DATE",
      "type": "java.util.Date",
      "hidden": false,
      "meta": true
    },
    {
      "name": "storedby",
      "column": "Stored by",
      "valueType": "TEXT",
      "type": "java.lang.String",
      "hidden": false,
      "meta": true
    },
    {
      "name": "lastupdated",
      "column": "Last Updated",
      "valueType": "DATE",
      "type": "java.time.LocalDate",
      "hidden": false,
      "meta": true
    },
    {
      "name": "storedby",
      "column": "Stored by",
      "valueType": "TEXT",
      "type": "java.lang.String",
      "hidden": false,
      "meta": true
    },
    {
      "name": "createdbydisplayname",
      "column": "Created by (display name)",
      "valueType": "TEXT",
      "type": "java.lang.String",
      "hidden": false,
      "meta": true
    },
    {
      "name": "lastupdatedbydisplayname",
      "column": "Last updated by (display name)",
      "valueType": "TEXT",
      "type": "java.lang.String",
      "hidden": false,
      "meta": true
    },
    {
      "name": "geometry",
      "column": "Geometry",
      "valueType": "TEXT",
      "type": "java.lang.String",
      "hidden": false,
      "meta": true
    },
    {
      "name": "longitude",
      "column": "Longitude",
      "valueType": "NUMBER",
      "type": "java.lang.Double",
      "hidden": false,
      "meta": true
    },
    {
      "name": "latitude",
      "column": "Latitude",
      "valueType": "NUMBER",
      "type": "java.lang.Double",
      "hidden": false,
      "meta": true
    },
    {
      "name": "ouname",
      "column": "Organisation unit name",
      "valueType": "TEXT",
      "type": "java.lang.String",
      "hidden": false,
      "meta": true
    },
    {
      "name": "oucode",
      "column": "Organisation unit code",
      "valueType": "TEXT",
      "type": "java.lang.String",
      "hidden": false,
      "meta": true
    },
    {
      "name": "ou",
      "column": "Organisation unit",
      "valueType": "TEXT",
      "type": "java.lang.String",
      "hidden": false,
      "meta": true
    },
    {
      "name": "de0FEHSIoxh",
      "column": "WHOMCH Chronic conditions",
      "valueType": "BOOLEAN",
      "type": "java.lang.Boolean",
      "hidden": false,
      "meta": true
    },
    {
      "name": "sWoqcoByYmD",
      "column": "WHOMCH Smoking",
      "valueType": "BOOLEAN",
      "type": "java.lang.Boolean",
      "hidden": false,
      "meta": true
    }
  ],
  "metaData": {
    "pager": {
      "page": 2,
      "total": 163,
      "pageSize": 4,
      "pageCount": 41
    },
    "items": {
      "ImspTQPwCqd": {
        "name": "Sierra Leone"
      },
      "PFDfvmGpsR3": {
        "name": "Care at birth"
      },
      "bbKtnxRZKEP": {
        "name": "Postpartum care visit"
      },
      "ou": {
        "name": "Organisation unit"
      },
      "PUZaKR0Jh2k": {
        "name": "Previous deliveries"
      },
      "edqlbukwRfQ": {
        "name": "Antenatal care visit"
      },
      "WZbXY0S00lP": {
        "name": "First antenatal care visit"
      },
      "sWoqcoByYmD": {
        "name": "WHOMCH Smoking"
      },
      "WSGAb5XwJ3Y": {
        "name": "WHO RMNCH Tracker"
      },
      "de0FEHSIoxh": {
        "name": "WHOMCH Chronic conditions"
      }
    },
    "dimensions": {
      "pe": [],
      "ou": [
        "ImspTQPwCqd"
      ],
      "sWoqcoByYmD": [],
      "de0FEHSIoxh": []
    }
  },
  "width": 12,
  "rows": [
    [
      "A0cP533hIQv",
      "to8G9jAprnx",
      "2019-02-02 12:05:00.0",
      "2019-02-02 12:05:00.0",
      "system",
      "2020-08-06 21:20:52.0",
      "",
      "0.0",
      "0.0",
      "Tonkomba MCHP",
      "OU_193264",
      "xIMxph4NMP1",
      "0",
      "1"
    ],
    [
      "ZqiUn2uXmBi",
      "SJtv0WzoYki",
      "2019-02-02 12:05:00.0",
      "2019-02-02 12:05:00.0",
      "system",
      "2020-08-06 21:20:52.0",
      "",
      "0.0",
      "0.0",
      "Mawoma MCHP",
      "OU_254973",
      "Srnpwq8jKbp",
      "0",
      "0"
    ],
    [
      "lE747mUAtbz",
      "PGzTv2A1xzn",
      "2019-02-02 12:05:00.0",
      "2019-02-02 12:05:00.0",
      "system",
      "2020-08-06 21:20:52.0",
      "",
      "0.0",
      "0.0",
      "Kunsho CHP",
      "OU_193254",
      "tdhB1JXYBx2",
      "",
      "0"
    ],
    [
      "nmcqu9QF8ow",
      "pav3tGLjYuq",
      "2019-02-03 12:05:00.0",
      "2019-02-03 12:05:00.0",
      "system",
      "2020-08-06 21:20:52.0",
      "",
      "0.0",
      "0.0",
      "Korbu MCHP",
      "OU_678893",
      "m73lWmo5BDG",
      "",
      "1"
    ]
  ],
  "height": 4
}

The headers section of the response describes the content of the query result. The enrollment unique identifier, the tracked entity instance identifier, the enrollment date, the incident date, geometry, latitude, longitude, the organisation unit name and the organisation unit code appear as the first dimensions in the response and will always be present. Next comes the data elements, and tracked entity attributes which were specified as dimensions in the request, in this case, the "WHOMCH Chronic conditions" and "WHOMCH smoking" 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 enrollments produced by the query. Each row represents exactly one enrollment.

Analytics across TEI relationships with program indicators¶

A API de análise de inscrição de não agregação também oferece suporte para vincular indicadores de programa a tipos de relacionamento, a fim de mostrar o resultado de um cálculo de um indicador de programa específico aplicado às entidades relacionadas da Instância de entidade rastreada listada.

For the Program Indicator/Relationship Type link to work, the /api/analytics/enrollments/query API requires an additional dimension which must include the chosen Relationship Type UID and the chosen Program Indicator UID:

/api/analytics/enrollments/query/<program-id>
  ?dimension=<relationshiptype-id>.<programindicator-id>

Por exemplo, para recuperar uma lista de inscrições do programa "WHO RMNCH Tracker" para janeiro de 2019 e exibir a contagem de casos de malária vinculados a essa inscrição pelo tipo de relação "Malaria case linked to person", você pode usar a seguinte consulta

/api/analytics/enrollments/query/WSGAb5XwJ3Y.json?dimension=mxZDvSZYxlw.nFICjJluo74
  &startDate=2019-01-01&endDate=2019-01-31

A API suporta o uso de indicadores de programa que não estão associados ao programa "principal" (que é o ID do programa especificado após / query /).

Dimensions¶

Five resources allow to easily retrieve data dimensions:

• Event Query data dimensions/analytics/events/query/dimensions
• Event Aggregate data dimensions /analytics/events/aggregate/dimensions
• Enrollment Query data dimensions /analytics/enrollments/query/dimensions
• Enrollment Aggregate data dimensions /analytics/enrollments/aggregate/dimensions
• Tracked Entities query data dimensions) /analytics/teis/query/dimensions

Resources mentioned above share the following request parameter:

Dimension filters¶

Dimensions endpoints support filtering the output to narrow down the response to desired elements. Filters are in the format filter=field:op:value&filter=field:op:value&...&filter=field:op:value.

Supported field values are:

• id/uid - dimension id
• code - dimension code
• valueType - dimension value type
• name - the name of the dimension
• dimensionType - the type of the dimension
  • DATA_ELEMENT
  • PROGRAM_INDICATOR
  • PROGRAM_ATTRIBUTE
  • CATEGORY
  • CATEGORY_OPTION_GROUP_SET
• displayName - displayName of the dimension
• displayShortName - displayShortName of the dimension

Supported opvalues are:

• startsWith - field starts with
• !startsWith - field does not start with
• endsWith - field ends with
• !endsWith - field does not end with-
• eq - equals
• ieq - equals ignoring case
• ne - not equals
• like - contains
• !like - does not contain
• ilike - contains ignoring case
• !ilike - does not contain ignoring case

Event analytics dimensions¶

Event query analytics dimensions¶

The /analytics/events/query/dimensions?programStageId=... resource accepts a mandatory tracker program stage and returns the following data dimensions:

• Program indicators associated with the program (derived from programStageId)
• Data elements of supported types in the program stage
• Tracked entity attributes of supported types associated with the program (derived from programStageId)
• Categories in category combo associated with the program (derived from programStageId)
• Category option group sets of type ATTRIBUTE

All value types for data elements and tracked entity attributes are considered supported types, except IMAGE, FILE_RESOURCE and TRACKER_ASSOCIATE.

Event aggregate dimensions¶

The /analytics/events/aggregate/dimensions?programStageId=... resource accepts a mandatory programStageId parameter and returns the following data dimensions:

• Data elements of supported types in the program stage
• Tracked entity attributes of supported types associated with the program (derived from programStageId)
• Categories in category combo associated with the program (derived from programStageId)
• Category option group sets of type ATTRIBUTE associated with program (derived from programStageId)

Data elements and tracked entity attributes are considered supported types if their value type is one of the following:

• NUMBER
• UNIT_INTERVAL
• PERCENTAGE
• INTEGER
• INTEGER_POSITIVE
• INTEGER_NEGATIVE
• INTEGER_ZERO_OR_POSITIVE
• BOOLEAN
• TRUE_ONLY

Enrollment analytics dimensions¶

Enrollment query analytics dimensions¶

The /analytics/enrollments/query/dimensions?programId=... resource accepts a mandatory id of a tracker program and returns the following data dimensions:

• Program indicators connected to the program
• Data elements of supported types in the program, with program stage for each data element
• Tracked entity attributes of supported types associated with the program that are not confidential

All value types for data elements and tracked entity attributes are considered supported types, except IMAGE, FILE_RESOURCE and TRACKER_ASSOCIATE.

Enrollment aggregate dimensions¶

The /analytics/enrollments/aggregate/dimensions?programId=... resource accepts a mandatory id of a tracker program, referring to a program with registration, and returns the following data dimensions:

• Data elements of supported types in the program, with program stage for each data element
• Tracked entity attributes of supported types associated with the program that are not confidential

Data elements and tracked entity attributes are considered supported types if their value type is one of the following:

• NUMBER
• UNIT_INTERVAL
• PERCENTAGE
• INTEGER
• INTEGER_POSITIVE
• INTEGER_NEGATIVE
• INTEGER_ZERO_OR_POSITIVE
• BOOLEAN
• TRUE_ONLY

Tracked Entities analytics dimensions¶

Tracked Entities query analytics dimensions¶

The /analytics/teis/query/dimensions?trackedEntityType=TET resource accepts a mandatory id of a tracked entity type TET and returns the following data dimensions:

for each program P associated with a tracked entity instance of type TET: - Program indicators associated to P - Data elements of supported types in P, with program stage for each data element - Tracked entity attributes of supported types associated with the program that are not confidential - Program attributes of P

All value types for data elements and tracked entity attributes are considered supported types, except IMAGE, FILE_RESOURCE and TRACKER_ASSOCIATE.

Sample request and response¶

GET /api/analytics/events/query/dimensions?programStageId=A03MvHHogjR&order=code&filter=name:ilike:weight

{
   "page":1,
   "total":5,
   "pageSize":50,
   "dimensions":[
      {
         "dimensionType":"PROGRAM_INDICATOR",
         "created":"2015-08-06T22:49:20.128",
         "lastUpdated":"2015-08-06T22:51:19.787",
         "name":"Measles + Yellow fever doses low infant weight",
         "displayName":"Measles + Yellow fever doses low infant weight",
         "id":"tt54DiKuQ9c",
         "uid":"tt54DiKuQ9c",
         "displayShortName":"Measles + Yellow fever doses low infant weight"
      },
      {
         "dimensionType":"PROGRAM_INDICATOR",
         "created":"2017-01-20T10:32:26.388",
         "lastUpdated":"2017-01-20T10:32:26.388",
         "name":"Weight gain(in g) between birth and last postnatal",
         "displayName":"Weight gain(in g) between birth and last postnatal",
         "id":"qhTkqwAJLMv",
         "uid":"qhTkqwAJLMv",
         "displayShortName":"Weight gain(g)"
      },
      {
         "dimensionType":"PROGRAM_INDICATOR",
         "created":"2015-09-14T20:25:55.543",
         "lastUpdated":"2018-08-28T12:22:47.857",
         "name":"Average weight (g)",
         "displayName":"Average weight (g)",
         "id":"GxdhnY5wmHq",
         "uid":"GxdhnY5wmHq",
         "displayShortName":"Average weight (g)"
      },
      {
         "dimensionType":"PROGRAM_INDICATOR",
         "created":"2015-08-06T22:35:40.391",
         "lastUpdated":"2015-08-06T22:35:40.391",
         "name":"BCG doses low birth weight",
         "displayName":"BCG doses low birth weight",
         "id":"hCYU0G5Ti2T",
         "uid":"hCYU0G5Ti2T",
         "displayShortName":"BCG doses low birth weight"
      },
      {
         "valueType":"NUMBER",
         "dimensionType":"DATA_ELEMENT",
         "created":"2012-09-20T17:37:45.474",
         "lastUpdated":"2014-11-11T21:56:05.418",
         "name":"MCH Weight (g)",
         "displayName":"MCH Weight (g)",
         "id":"A03MvHHogjR.UXz7xuGCEhU",
         "uid":"UXz7xuGCEhU",
         "code":"DE_2005736",
         "displayShortName":"Weight (g)"
      }
   ]
}

Análise de unidade organizacional¶

A API de análise de unidade organizacional fornece estatísticas sobre unidades organizacionais classificadas por conjuntos de grupos de unidades organizacionais, ou seja, contagens de unidades organizacionais por grupo de unidades organizacionais dentro de conjuntos de grupos de unidades organizacionais.

GET /api/orgUnitAnalytics?ou=<org-unit-id>&ougs=<org-unit-group-set-id>

A API requer pelo menos uma unidade organizacional e pelo menos um conjunto de grupos de unidades organizacionais. Várias unidades organizacionais e conjuntos de grupos podem ser fornecidos separados por um ponto e vírgula.

Solicitar parâmetros de consulta¶

O recurso de análise da unidade organizacional permite que você especifique uma variedade de parâmetros de consulta:

A resposta conterá uma coluna para a unidade organizacional pai, colunas para cada grupo de unidades organizacionais definido como parte da solicitação e uma coluna para a contagem. As estatísticas incluem a contagem de unidades organizacionais que fazem parte da sub-hierarquia das unidades organizacionais especificadas na solicitação. A resposta contém uma seção de metadados que especifica o nome de cada unidade organizacional e parte do grupo de unidades organizacionais da resposta referenciada por seus identificadores.

A resposta padrão é normalizada com uma única coluna count. A resposta pode ser renderizada em um layout de tabela, especificando pelo menos um grupo de unidades organizacionais definido usando o parâmetro de consulta colunas.

Formatos de resposta¶

O endpoint de análise da unidade organizacional oferece suporte aos seguintes formatos de representação:

• json (aplicativo/json)
• csv (aplicativo/csv)
• xls (application / vnd.ms-excel)
• pdf (aplicação / pdf)

Exemplos¶

Para buscar análises de unidade organizacional para uma unidade organizacional e conjunto de grupos de unidades organizacionais:

GET /api/orgUnitAnalytics?ou=lc3eMKXaEfw&ougs=J5jldMd8OHv

Para buscar dados analíticos de unidade organizacional para duas unidades organizacionais e dois conjuntos de grupos de unidades organizacionais:

GET /api/orgUnitAnalytics?ou=lc3eMKXaEfw;PMa2VCrupOd&ougs=J5jldMd8OHv;Bpx0589u8y0

Para buscar dados analíticos da unidade organizacional no modo de tabela com um conjunto de grupos renderizado como colunas:

GET / api / orgUnitAnalytics? Ou = fdc6uOvgoji; jUb8gELQApl; lc3eMKXaEfw; PMa2VCrupOd
  & ougs = J5jldMd8OHv & colunas = J5jldMd8OHv

Restrições e validação¶

The possible validation errors specifically for the org unit analytics API are described in the table below. Some errors specified for the aggregate analytics API are also relevant.

Relatório de conjunto de dados¶

Data set reports can be generated through the web api using the /dataSetReport resource. This resource generates reports on data set and returns the result in the form of an HTML table.

/api/dataSetReport

Solicitar parâmetros de consulta¶

A solicitação suporta os seguintes parâmetros:

O recurso de relatório do conjunto de dados aceita apenas solicitações GET. O tipo de conteúdo de resposta é application / json e retorna dados em uma grade. Este terminal funciona para todos os tipos de conjuntos de dados, incluindo padrão, seção e formulários personalizados.

An example request to retrieve a report for a monthly data set and org unit for October 2018 looks like this:

GET /api/dataSetReport?ds=BfMAe6Itzgt&pe=201810&ou=ImspTQPwCqd&selectedUnitOnly=false

An example request to retrieve a report for a monthly data set and org unit for October, November, and December 2018 looks like this:

GET /api/dataSetReport?ds=BfMAe6Itzgt&pe=201810,201811,201812&ou=ImspTQPwCqd&selectedUnitOnly=false

Para obter um relatório de conjunto de dados com um filtro, você pode usar o parâmetro filter. Nesse caso, o filtro é baseado em um conjunto de grupos de unidades organizacionais e dois grupos de unidades organizacionais:

GET /api/dataSetReport?ds=BfMAe6Itzgt&pe=201810&ou=ImspTQPwCqd
  &filter=J5jldMd8OHv:RXL3lPSK8oG;tDZVQ1WtwpA

Formatos de resposta¶

O endpoint do relatório do conjunto de dados oferece suporte à saída nos formatos a seguir. Você pode recuperar um endpoint específico usando a extensão do arquivo ou o cabeçalho HTTP Aceitar.

• json (aplicativo/json)
• pdf (aplicação / pdf)
• xls (application / vnd.ms-excel)

Formulários personalizados¶

Um terminal dedicado está disponível para conjuntos de dados com formulários HTML personalizados. Este endpoint retorna o conteúdo do formulário HTML com o tipo de conteúdo text / html com dados inseridos nele. Observe que você pode usar o ponto de extremidade do relatório de conjunto de dados geral também para conjuntos de dados com formulários personalizados; no entanto, isso retornará o relatório no formato JSON como uma grade. Este ponto de extremidade funciona apenas para conjuntos de dados com formulários HTML personalizados.

GET /api/dataSetReport/custom

A sintaxe para este ponto de extremidade é igual ao ponto de extremidade do relatório de conjunto de dados geral. Para recuperar um relatório de conjunto de dados HTML personalizado, você pode emitir uma solicitação como esta:

GET /api/dataSetReport/custom?ds=lyLU2wR22tC&pe=201810&ou=ImspTQPwCqd

Análise Push¶

The push analysis API includes endpoints for previewing a push analysis report for the logged in user and manually triggering the system to generate and send push analysis reports, in addition to the normal CRUD operations. When using the create and update endpoints for push analysis, the push analysis will be scheduled to run based on the properties of the push analysis. When deleting or updating a push analysis to be disabled, the job will also be stopped from running in the future.

To get an HTML preview of an existing push analysis, you can do a GET request to the following endpoint:

/api/pushAnalysis/<id>/render

To manually trigger a push analysis job, you can do a POST request to this endpoint:

/api/pushAnalysis/<id>/run

A push analysis consists of the following properties, where some are required to automatically run push analysis jobs:

Análise de uso de dados¶

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/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.

Solicitar parâmetros de consulta¶

A API de análise de uso (estatísticas de dados) oferece suporte a duas operações:

• POST: creates a view event

• GET: retrieves aggregated statistics

Criar eventos de visualização (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/dataStatistics?eventType=CHART_VIEW&favorite=LW0O27b7TdD

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

Recuperar relatório de análise de uso agregado (GET)¶

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

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 monthly aggregation:

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

Recupere os principais favoritos¶

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

The API query can be used without a username, and will then find the top favorites of the system.

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

Se o nome de usuário for especificado, a resposta conterá apenas os principais favoritos desse usuário.

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

Formato de resposta¶

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 (aplicativo/json)

• xml (aplicativo/xml)

• html (texto / html)

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

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

To get an usage analytics response in JSON format:

/api/dataStatistics?startDate=2016-02-01&endDate=2016-02-14&interval=WEEK

A resposta JSON é semelhante a esta:

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

Recuperar estatísticas para um favorito¶

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/dataStatistics/favorites/{favorite-id}.json

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

{
  "views": 3
}

Características geoespaciais¶

The geoFeatures resource lets you retrieve geospatial information from DHIS2. Geospatial features are stored together with organisation units. The syntax for retrieving features is identical to the syntax used for the organisation unit dimension for the analytics resource. It is recommended to read up on the analytics api resource before continuing to read this section. You must use the GET request type, and only JSON response format is supported.

As an example, to retrieve geo features for all organisation units at level 3 in the organisation unit hierarchy you can use a GET request with the following URL:

/api/geoFeatures.json?ou=ou:LEVEL-3

To retrieve geo features for organisation units at a level within the boundary of an organisation unit (e.g. at level 2) you can use this URL:

/api/geoFeatures.json?ou=ou:LEVEL-4;O6uvpzGd5pu

The response coordinates value can be read from two properties which is decided by the parameter coordinateField. - The geometry property of the OrganisationUnit: this is the default behaviour which is applied when parameter coordinateField is not provided. - The OrgansationUnit attribute of value type GeoJSON: the api will use the provided coordinateField={attributeId} to get the GeoJSON coordinates from this attribute value.

For example, to retrieve geo features for all organisation units at level 3 as above but get the coordinates from OrganisationUnit attribute tJqtSV4quLb

/api/geoFeatures.json?ou=ou:LEVEL-3&coordinateField=tJqtSV4quLb

The semantics of the response properties are described in the following table.

GeoJSON¶

To export GeoJSON, you can simply add .geosjon as an extension to the endpoint /api/organisationUnits, or you can use the Accept header application/json+geojson.

Two parameters are supported: level (default is 1) and parent (default is root organisation units). Both can be included multiple times. Some examples:

Obtenha todos os recursos nos níveis 2 e 4:

/api/organisationUnits.geojson?level=2&level=4

Obtenha todos os recursos no nível 3 com uma unidade de organização de limite:

/api/organisationUnits.geojson?parent=fdc6uOvgoji&level=3

Ganchos de tabela de análise¶

Analytics table hooks provide a mechanism for invoking SQL scripts during different phases of the analytics table generation process. This is useful for customizing data in resource and analytics tables, e.g. in order to achieve specific logic for calculations and aggregation. Analytics table hooks can be manipulated at the following API endpoint:

/ api / analyticsTableHooks

The analytics table hooks API supports the standard HTTP CRUD operations for creating (POST), updating (PUT), retrieving (GET) and deleting (DELETE) entities.

Campos de gancho¶

Os ganchos da tabela de análise têm os seguintes campos:

The ANALYTICS_TABLE_POPULATED phase takes place after the analytics table has been populated, but before indexes have been created and the temp table has been swapped with the main table. As a result, the SQL script should refer to the analytics temp table, e.g. analytics_temp, analytics_completeness_temp, analytics_event_temp_ebayegv0exc.

This applies also to the RESOURCE_TABLE_POPULATED phase, which takes place after the resource table has been populated, but before indexes have been created and the temp table has been swapped with the main table. As a result, the SQL script should refer to the resource temp table, e.g. _orgunitstructure_temp, _categorystructure_temp.

You should define only one of the resourceTableType and analyticsTableType fields, depending on which phase is defined.

You can refer to the temporary database table which matches the specified hook table type only (other temporary tables will not be available). As an example, if you specify ORG_UNIT_STRUCTURE as the resource table type, you can refer to the _orgunitstructure_temp temporary database table only.

The following table shows the valid combinations of phases, table types and temporary tables.

Criando ganchos¶

To create a hook which should run after the resource tables have been populated you can do a POST request like this using JSON as content type:

POST /api/analyticsTableHooks

{
  "name": "Update 'Area' in org unit group set resource table",
  "phase": "RESOURCE_TABLE_POPULATED",
  "resourceTableType": "ORG_UNIT_GROUP_SET_STRUCTURE",
  "sql": "update _organisationunitgroupsetstructure_temp set \"uIuxlbV1vRT\" = 'b0EsAxm8Nge'"
}

To create a hook which should run after the data value analytics table has been populated you can do a POST request like this using JSON format:

{
  "name": "Update 'Currently on treatment' data in analytics table",
  "phase": "ANALYTICS_TABLE_POPULATED",
  "analyticsTableType": "DATA_VALUE",
  "sql": "update analytics_temp set monthly = '200212' where monthly in ('200210', '200211')"
}

To create a hook which should run after the event analytics tables are populated you can do a POST request like this using JSON format:

{
  "name": "Delete data for a data element",
  "phase": "ANALYTICS_TABLE_POPULATED",
  "analyticsTableType": "EVENT",
  "sql": "delete from analytics_event_temp_lxaq7zs9vyr where dx = 'uDX9LKGRwaH'"
}

Conversão SVG¶

The Web API provides a resource which can be used to convert SVG content into more widely used formats such as PNG and PDF. Ideally this conversion should happen on the client side, but not all client side technologies are capable of performing this task. Currently PNG and PDF output formats are supported. The SVG content itself should be passed with a svg query parameter, and an optional query parameter filename can be used to specify the filename of the response attachment file. Note that the file extension should be omitted. For PNG you can send a POST request to the following URL with Content-type application/x-www-form-urlencoded, identical to a regular HTML form submission.

api / svg.png

For PDF you can send a POST request to the following URL with content-type application/x-www-form-urlencoded.

api / svg.pdf

Analytics query execution plan and costs including execution time estimation¶

The analytics API provides endpoints for investigation of query performance issues. It is implemented as part of all analytics endpoints:

• analytics/explain
• analytics/event/explain
• analytics/enrollment/explain

Example

GET /api/analytics/explain?displayProperty=NAME
  &dimension=dx:Uvn6LCg7dVU;sB79w2hiLp8,ou:USER_ORGUNIT
  &filter=pe:THIS_YEAR&includeNumDen=false&skipMeta=false
  &skipData=true&includeMetadataDetails=true

The response looks like this.

{
    "headers": [
        {
            "name": "dx",
            "column": "Data",
            "valueType": "TEXT",
            "type": "java.lang.String",
            "hidden": false,
            "meta": true
        },
        {
            "name": "ou",
            "column": "Organisation unit",
            "valueType": "TEXT",
            "type": "java.lang.String",
            "hidden": false,
            "meta": true
        },
        {
            "name": "value",
            "column": "Value",
            "valueType": "NUMBER",
            "type": "java.lang.Double",
            "hidden": false,
            "meta": false
        }
    ],
    "metaData": {
        "items": {
            "ImspTQPwCqd": {
                "uid": "ImspTQPwCqd",
                "code": "OU_525",
                "name": "Sierra Leone",
                "dimensionItemType": "ORGANISATION_UNIT",
                "valueType": "NUMBER",
                "totalAggregationType": "SUM"
            },
            "sB79w2hiLp8": {
                "uid": "sB79w2hiLp8",
                "name": "ANC 3 Coverage",
                "description": "Total 3rd ANC visits (Fixed and outreach) by expected number of pregnant women.",
                "legendSet": "fqs276KXCXi",
                "dimensionItemType": "INDICATOR",
                "valueType": "NUMBER",
                "totalAggregationType": "AVERAGE",
                "indicatorType": {
                    "name": "Per cent",
                    "displayName": "Per cent",
                    "factor": 100,
                    "number": false
                }
            },
            "dx": {
                "uid": "dx",
                "name": "Data",
                "dimensionType": "DATA_X"
            },
            "pe": {
                "uid": "pe",
                "name": "Period",
                "dimensionType": "PERIOD"
            },
            "ou": {
                "uid": "ou",
                "name": "Organisation unit",
                "dimensionType": "ORGANISATION_UNIT"
            },
            "Uvn6LCg7dVU": {
                "uid": "Uvn6LCg7dVU",
                "code": "IN_52486",
                "name": "ANC 1 Coverage",
                "description": "Total 1st ANC visits (Fixed and outreach) by expected number of pregnant women.",
                "legendSet": "fqs276KXCXi",
                "dimensionItemType": "INDICATOR",
                "valueType": "NUMBER",
                "totalAggregationType": "AVERAGE",
                "indicatorType": {
                    "name": "Per cent",
                    "displayName": "Per cent",
                    "factor": 100,
                    "number": false
                }
            },
            "THIS_YEAR": {
                "name": "This year"
            },
            "2022": {
                "uid": "2022",
                "code": "2022",
                "name": "2022",
                "dimensionItemType": "PERIOD",
                "valueType": "NUMBER",
                "totalAggregationType": "SUM",
                "startDate": "2022-01-01T00:00:00.000",
                "endDate": "2022-12-31T00:00:00.000"
            }
        },
        "dimensions": {
            "dx": [
                "Uvn6LCg7dVU",
                "sB79w2hiLp8"
            ],
            "pe": [
                "2022"
            ],
            "ou": [
                "ImspTQPwCqd"
            ],
            "co": []
        }
    },
    "performanceMetrics": {
        "totalTimeInMillis": 90.894,
        "executionPlans": [
            {
                "timeInMillis": 12.314,
                "planningTime": 6.801,
                "executionTime": 5.513,
                "query": "select ax.\"dx\",ax.\"uidlevel1\", sum(daysxvalue) / 365 as value from analytics_2022 as ax where ax.\"dx\" in ('h0xKKjijTdI') and ax.\"uidlevel1\" in ('ImspTQPwCqd') and ( ax.\"yearly\" in ('2022') ) and ax.\"year\" in (2022) group by ax.\"dx\",ax.\"uidlevel1\"",
                "plan": {
                    "Node Type": "Aggregate",
                    "Strategy": "Sorted",
                    "Partial Mode": "Simple",
                    "Parallel Aware": false,
                    "Async Capable": false,
                    "Startup Cost": 20.21,
                    "Total Cost": 5602.98,
                    "Plan Rows": 260,
                    "Plan Width": 32,
                    "Actual Startup Time": 5.448,
                    "Actual Total Time": 5.449,
                    "Actual Rows": 1,
                    "Actual Loops": 1,
                    "Group Key": [
                        "dx",
                        "uidlevel1"
                    ],
                    "Plans": [
                        {
                            "Node Type": "Bitmap Heap Scan",
                            "Parent Relationship": "Outer",
                            "Parallel Aware": false,
                            "Async Capable": false,
                            "Relation Name": "analytics_2022",
                            "Alias": "ax",
                            "Startup Cost": 20.21,
                            "Total Cost": 5588.33,
                            "Plan Rows": 1520,
                            "Plan Width": 32,
                            "Actual Startup Time": 0.446,
                            "Actual Total Time": 5.003,
                            "Actual Rows": 1032,
                            "Actual Loops": 1,
                            "Recheck Cond": "(dx = 'h0xKKjijTdI'::bpchar)",
                            "Rows Removed by Index Recheck": 0,
                            "Filter": "((uidlevel1 = 'ImspTQPwCqd'::bpchar) AND (yearly = '2022'::text) AND (year = 2022))",
                            "Rows Removed by Filter": 0,
                            "Exact Heap Blocks": 46,
                            "Lossy Heap Blocks": 0,
                            "Plans": [
                                {
                                    "Node Type": "Bitmap Index Scan",
                                    "Parent Relationship": "Outer",
                                    "Parallel Aware": false,
                                    "Async Capable": false,
                                    "Index Name": "in_dx_ao_ax_2022_MClNI",
                                    "Startup Cost": 0.0,
                                    "Total Cost": 19.83,
                                    "Plan Rows": 1520,
                                    "Plan Width": 0,
                                    "Actual Startup Time": 0.406,
                                    "Actual Total Time": 0.407,
                                    "Actual Rows": 1032,
                                    "Actual Loops": 1,
                                    "Index Cond": "(dx = 'h0xKKjijTdI'::bpchar)"
                                }
                            ]
                        }
                    ]
                }
            },
            {
                "timeInMillis": 38.35,
                "planningTime": 0.627,
                "executionTime": 37.723,
                "query": "select ax.\"dx\",ax.\"uidlevel1\", sum(value) as value from analytics_2022 as ax where ax.\"dx\" in ('Jtf34kNZhzP') and ax.\"uidlevel1\" in ('ImspTQPwCqd') and ( ax.\"yearly\" in ('2022') ) and ax.\"year\" in (2022) group by ax.\"dx\",ax.\"uidlevel1\"",
                "plan": {
                    "Node Type": "Aggregate",
                    "Strategy": "Sorted",
                    "Partial Mode": "Simple",
                    "Parallel Aware": false,
                    "Async Capable": false,
                    "Startup Cost": 193.57,
                    "Total Cost": 47322.83,
                    "Plan Rows": 261,
                    "Plan Width": 32,
                    "Actual Startup Time": 37.685,
                    "Actual Total Time": 37.685,
                    "Actual Rows": 1,
                    "Actual Loops": 1,
                    "Group Key": [
                        "dx",
                        "uidlevel1"
                    ],
                    "Plans": [
                        {
                            "Node Type": "Bitmap Heap Scan",
                            "Parent Relationship": "Outer",
                            "Parallel Aware": false,
                            "Async Capable": false,
                            "Relation Name": "analytics_2022",
                            "Alias": "ax",
                            "Startup Cost": 193.57,
                            "Total Cost": 47191.38,
                            "Plan Rows": 17179,
                            "Plan Width": 32,
                            "Actual Startup Time": 1.981,
                            "Actual Total Time": 32.332,
                            "Actual Rows": 17462,
                            "Actual Loops": 1,
                            "Recheck Cond": "(dx = 'Jtf34kNZhzP'::bpchar)",
                            "Rows Removed by Index Recheck": 0,
                            "Filter": "((uidlevel1 = 'ImspTQPwCqd'::bpchar) AND (yearly = '2022'::text) AND (year = 2022))",
                            "Rows Removed by Filter": 0,
                            "Exact Heap Blocks": 1165,
                            "Lossy Heap Blocks": 0,
                            "Plans": [
                                {
                                    "Node Type": "Bitmap Index Scan",
                                    "Parent Relationship": "Outer",
                                    "Parallel Aware": false,
                                    "Async Capable": false,
                                    "Index Name": "in_dx_ax_2022_Eb64F",
                                    "Startup Cost": 0.0,
                                    "Total Cost": 189.27,
                                    "Plan Rows": 17179,
                                    "Plan Width": 0,
                                    "Actual Startup Time": 1.765,
                                    "Actual Total Time": 1.765,
                                    "Actual Rows": 17462,
                                    "Actual Loops": 1,
                                    "Index Cond": "(dx = 'Jtf34kNZhzP'::bpchar)"
                                }
                            ]
                        }
                    ]
                }
            }
        ]
    },
    "width": 0,
    "rows": [],
    "height": 0,
    "headerWidth": 2
}

This response displays the execution plan that the PostgreSQL planner generates for the supplied statement.

The execution plan shows how the table(s) referenced by the statement will be scanned: by plain sequential scan, index scan,and if multiple tables are referenced, what joins will be used to bring together the required rows from each input table.

The most critical part of the display is the estimated statement execution cost, which is the query planner's estimate at how long it will take to run the statement.

All entry points are secured by authorization. The F_PERFORM_ANALYTICS_EXPLAIN role is required.

Analytics explain¶

/api/analytics/explain

Event analytics explain¶

/api/analytics/event/aggregate/{program}/explain

/api/analytics/event/query/{program}/explain

Enrollment analytics explain¶

/api/analytics/enrollment/query/{program}/explain