Analytika¶

Analytika¶

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

Parametry požadavku databázového dotazu¶

Prostředek pro analýzu umožňuje určit řadu parametrů dotazu:

Tabulka: Parametry databázového dotazu

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.

Parametr filtr určuje, které dimenze mají být použity jako filtry pro data získaná v analytickém dotazu. Lze zadat libovolný počet filtrů. Parametr filter by se měl opakovat pro každý filtr, který se má v dotazu použít. Filtr se od dimenze liší tím, že dimenze filtru nebudou součástí obsahu odpovědi dotazu a že agregované hodnoty v odpovědi budou sbaleny na dimenze filtru. Jinými slovy, data v odpovědi budou agregována na dimenze filtru, ale filtry nebudou zahrnuty jako dimenze ve skutečné odpovědi. Jako příklad můžete pro dotaz na určité datové prvky filtrované podle období a organizačních jednotek použít následující adresu 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

Rozměry a položky¶

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:

Tabulka: Dimenze a položky dimenzí

Při navrhování analytických dotazů není nutné si uvědomovat, které objekty se používají pro různé dynamické dimenze. Úplný seznam dynamických dimenzí můžete získat na této adrese URL ve webovém rozhraní 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

Níže je uvedeno několik věcí, na které je třeba dávat pozor při používání analytických zdrojů.

• 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 položky rozměrů jsou specifikovány.

• For the period dimension, the dimension items are ISO period identifikátory a/nebo relativní období. Podívejte se prosím do sekce above called "Date and period format" for the period format and dostupná relativní období.

• For the organisation unit dimension, you can specify the items to be organizační jednotku nebo dílčí jednotky organizační jednotky associated with the user currently authenticated for the request pomocí klíčů USER_ORGUNIT nebo USER_ORGUNIT_CHILDREN jako položek, 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.

Dimenze dx¶

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

Tabulka: Typy rozměrů dat dx

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

Syntaxi skupiny lze použít i s jakoukoli jinou položkou. Příklad vypadá takto:

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

Formáty odpovědí¶

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

• json (application/json)

• jsonp (application/javascript)

• xml (application/xml)

• csv (application/csv)

• html (text/html)

• html+css (text/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

Odpověď JSON bude vypadat takto:

{
  "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
}

Odpověď představuje tabulku rozměrových dat. Pole záhlaví poskytuje přehled o tom, které sloupce jsou v tabulce obsaženy a co obsahují. Vlastnost sloupec zobrazuje identifikátor rozměru sloupce, nebo pokud sloupec obsahuje míry, slovo "Hodnota". Vlastnost meta je pravdivá, pokud sloupec obsahuje položky dimenze, nebo nepravdivá, pokud sloupec obsahuje míru (agregované hodnoty dat). Vlastnost jméno je podobná vlastnosti sloupce, s tím rozdílem, že v případě, že sloupec obsahuje míru, zobrazuje slovo "hodnota". Vlastnost type udává typ třídy Java pro hodnoty sloupce.

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.

Pole rows obsahuje rozměrovou tabulku dat. Obsahuje sloupce s položkami dimenze (identifikátory objektů nebo období) a sloupec s agregovanými hodnotami dat. Výše uvedená příkladová odpověď obsahuje sloupec s údaji/indikátory, sloupec s periodou a sloupec s hodnotou. První sloupec obsahuje identifikátory ukazatelů, druhý obsahuje identifikátory období ISO a třetí obsahuje hodnoty agregovaných dat.

Omezení a validace¶

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:

{
  "httpStatus": "Conflict",
  "httpStatusCode": 409,
  "status": "ERROR",
  "message": "Only a single indicator can be specified as filter",
  "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.

Formát sady datových hodnot¶

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.

Jako příklad lze v cílovém systému určit indikátor, který shrne data pro více datových prvků a importuje tato data pro jeden datový prvek v cílovém systému. Jako další příklad lze agregovat data shromážděná na úrovni organizační jednotky 4 v cílovém systému na úroveň 2 a importovat tato data do cílového systému.

Ze zdroje dataValueSet můžete načíst data v surovém formátu sady datových hodnot:

/api/analytics/dataValueSet

Jsou podporovány následující reprezentace prostředků:

• json (application/json)

• xml (application/xml)

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

• Data (dx)

• Období (pe)

• Organizační jednotka (ou)

Jakákoli jiná dimenze bude ignorována. Filtry budou použity jako u běžných analytických požadavků. Lze zadat jakýkoli typ datové dimenze, včetně indikátorů, datových prvků, operandů datových prvků, datových sad a indikátorů programu.

Příklad požadavku, který agreguje data pro určité ukazatele, období a organizační jednotky a vrací je jako běžné hodnoty dat v XML, vypadá takto:

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

Při použití schémat identifikátorů založených na atributech pro export hrozí riziko vzniku duplicitních datových hodnot. Pro účely ladění lze použít logický parametr dotazu duplicatesOnly, který vrací pouze duplicitní hodnoty dat. Tuto odpověď lze použít k vyčištění duplicit:

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

Formát surových dat¶

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

Jsou podporovány následující reprezentace prostředků:

• json (application/json)

• csv (application/csv)

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

Tabulka: Parametry databázového dotazu

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=NAME

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.

Ladění¶

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

Analýza události¶

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

Rozměry a položky¶

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.

Tabulka: Dimenze události

Parametry požadavku databázového dotazu¶

Rozhraní API pro analytickou událost umožňuje určit rozsah parametrů dotazu.

Tabulka: Parametry dotazu pro dotaz události i souhrnnou analýzu

Tabulka: Parametry dotazu pouze pro analýzu dotazů událostí

Tabulka: Parametry dotazu pouze pro agregovanou analýzu událostí

Tabulka: Parametry dotazu pouze pro analýzu událostí clusteru

Analýza dotazů na události¶

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>

Chcete-li například získat události z programu "Ústavní nemocnost a úmrtnost" mezi lednem a říjnem 2016, kde jsou zahrnuty datové prvky "Pohlaví" a "Věk" a dimenze "Věk" je filtrována na "18", můžete použít následující dotaz:

/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

Filtrování¶

Filtry lze použít na datové prvky, atributy osob a identifikátory osob. Filtrování se provádí pomocí hodnoty parametru dotazu v následujícím formátu:

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

Jako příklad můžete filtrovat datový prvek "Váha" pro hodnoty větší než 2000 a nižší než 4000 takto:

&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

Můžete zadat více filtrů pro danou položku opakováním operátoru a součástí filtru, všechny oddělené středníky:

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

Dostupné operátory jsou uvedeny níže.

Tabulka: Operátory filtrů

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

převádí do následující logické podmínky:

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.

Příklad:

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

převádí do následující logické podmínky:

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

Formáty odpovědí¶

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

• json (application/json)

• jsonp (application/javascript)

• xls (application/vnd.ms-excel)

Například pro získání odpovědi ve formátu Excel můžete použít příponu souboru v URL požadavku takto:

/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

Výchozí formát odpovědi JSON bude vypadat podobně jako tento:

{
  "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

Agregovaná analýza událostí¶

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

Agregovaný zdroj událostí nevrací samotné informace o událostech, ale spíše souhrnný počet událostí, které odpovídají dotazu. Rozměry událostí zahrnují datové prvky, atributy osob, identifikátory osob, období a organizační jednotky. Agregátní dotazy na události by měly být ve formátu popsaném níže.

/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

Chcete-li zadat "Ženy" jako filtr pro "Pohlaví" pro datovou odpověď, což znamená, že "Pohlaví" nebude součástí odpovědi, ale bude filtrovat souhrnná čísla v ní, můžete použít následující syntaxi:

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

Sady rozsahů / legend¶

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>

Příklad vypadá takto:

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

Formáty odpovědí¶

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.

Analýza shluků událostí¶

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

Počet a rozsah analýzy událostí¶

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

Odpověď poskytne počet a rozsah ve formátu JSON:

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

Omezení a validace¶

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:

{
  "httpStatus": "Conflict",
  "httpStatusCode": 409,
  "status": "ERROR",
  "message": "At least one organisation unit must be specified",
  "errorCode": "E7200"
}

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

Analytika zápisu¶

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.

Rozměry a položky¶

Dimenze zápisu zahrnují datové prvky, atributy, organizační jednotky a období. Prostředek pro analýzu dotazů jednoduše vrátí zápisy odpovídající sadě kritérií a neprovádí žádnou agregaci.

Tabulka: Rozměry pro zápis

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.

Analýza dotazů na zápis¶

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

V dotazu můžete zadat libovolný počet dimenzí a libovolný počet filtrů. Identifikátory položky dimenze mohou odkazovat na kterýkoli z datových prvků ve fázích programu, trasované atributy entity, pevná a relativní období a organizační jednotky. Dimenze mohou volitelně mít operátor dotazu a filtr. Dotazy k registraci by měly být ve formátu popsaném níže.

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

Například k načtení zápisů z programu „Antenatální péče“ z ledna 2019, kde je z atributů převzato „Jméno“, jsou od první fáze programu zahrnuty datové prvky „Chronické stavy“ a „Kouření“ a „Hodnota hemoglobinu“ z následující programové fáze a zahrnuty by byly pouze ženy, které mají „Chronické stavy“, můžete použít následující dotaz:

/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

Chcete-li načíst registrace z programu „Předporodní péče“ z minulého měsíce (ve vztahu k okamžiku, kdy je dotaz proveden), kde jsou od první fáze programu zahrnuty datové prvky „Chronické stavy“ a „Kouření“, a „Hodnota hemoglobinu“ od fáze následného programu, zahrnuje pouze kouřící ženy s hemoglobinem nižším než 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

Řazení lze použít na dotaz pro data zápisu a incidentů zápisu:

/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

Stránkování lze na dotaz použít zadáním čísla stránky a parametrů velikosti stránky. Pokud je zadáno číslo stránky, ale velikost stránky není, použije se velikost stránky 50. Pokud je zadána velikost stránky, ale číslo stránky není, použije se číslo stránky 1. Chcete-li získat druhou stránku odpovědi s velikostí stránky 10, můžete použít dotaz, jako je tento:

/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

Filtrování¶

Filtry lze použít na datové prvky, atributy osob a identifikátory osob. Filtrování se provádí pomocí hodnoty parametru dotazu v následujícím formátu:

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

Jako příklad můžete filtrovat datový prvek "Váha" pro hodnoty větší než 2000 a nižší než 4000 takto:

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

Atribut "Věk" můžete filtrovat pro více konkrétních věků pomocí operátoru IN takto:

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

Můžete zadat více filtrů pro danou položku opakováním operátoru a součástí filtru, všechny oddělené středníky:

&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¶

Speciální klíčové slovo NV lze použít k filtrování podle hodnot null

Filtr podle AGE je null

&dimension=qrur9Dvnyt5:EQ:NV

Filtr podle AGE není nulový

&dimension=qrur9Dvnyt5:NE:NV

Filtr podle AGE je 18, 19 nebo je nulový

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

NV lze použít s operátory EQ, NE a IN

Operators¶

Dostupné operátory jsou uvedeny níže.

Tabulka: Operátory filtrů

Parametry požadavku databázového dotazu¶

Rozhraní API pro analytický dotaz na zápis umožňuje určit rozsah parametrů dotazu.

Tabulka: Parametry dotazu pro koncový bod dotazu registrace

Formáty odpovědí¶

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

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

Například pro získání odpovědi ve formátu Excel můžete použít příponu souboru v URL požadavku takto:

/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

Výchozí formát odpovědi JSON bude vypadat podobně jako tento:

{
  "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.

Analýza napříč vztahy TEI s indikátory programu¶

Neagregační zápisové analytické API také podporuje propojení indikátorů programu s typy vztahů, aby se zobrazil výsledek výpočtu konkrétního indikátoru programu použitého na související entity uvedené instance trasované entity.

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>

Chcete-li například načíst seznam zápisů z programu „WHO RMNCH Tracker“ pro leden 2019 a zobrazit počet případů malárie propojených s tímto zápisem podle typu vztahu „případ malárie spojený s osobou“, můžete použít následující dotaz

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

API podporuje použití indikátorů programu, které nejsou spojeny s "hlavním" programem (to je ID programu zadané za /query/).

Dimenze¶

Five resources allow to easily retrieve data dimensions:

• Event Query data dimensions/analytics/events/query/dimensions
• Dimenze souhrnných dat událostí /analytics/events/aggregate/dimensions
• Datové dimenze dotazu pro zápis /analytics/enrollments/query/dimensions
• Dimenze souhrnných dat pro registraci /analytics/enrollments/aggregate/dimensions
• Tracked Entities query data dimensions) /analytics/teis/query/dimensions

Výše uvedené zdroje sdílejí následující parametr požadavku:

Filtry dimenzí¶

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.

Podporované hodnoty pole field jsou:

• id/uid – id dimenze
• code - kód rozměru
• valueType – typ hodnoty dimenze
• name – název dimenze
• dimensionType - the type of the dimension
  • DATA_ELEMENT
  • PROGRAM_INDICATOR
  • PROGRAM_ATTRIBUTE
  • CATEGORY
  • CATEGORY_OPTION_GROUP_SET
• displayName - displayName dimenze
• displayShortName – displayShortName dimenze

Podporované op hodnoty jsou:

• startsWith - pole začíná na
• !startsWith - pole nezačíná
• endsWith - pole končí na
• !endsWith - field does not end with-
• eq – rovná se
• ieq - rovná se ignorování velkých a malých písmen
• ne – nerovná se
• like - obsahuje
• !like - neobsahuje
• jako - obsahuje, ignorování velkých a malých písmen
• !like - neobsahuje ignorování velkých a malých písmen

Event analytics dimensions¶

Dimenze analýzy dotazů událostí¶

Zdroj /analytics/events/query/dimensions?programStageId=... přijímá povinnou fázi programu sledování a vrací následující dimenze dat:

• Indikátory programu spojené s programem (odvozeno z programStageId)
• Data elements of supported types in the program stage
• Tracked entity attributes of supported types associated with the program (derived from programStageId)
• Kategorie v kombinaci kategorií spojených s programem (odvozeno z programStageId)
• Sady skupin možností kategorie typu ATTRIBUTE

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

Dimenze souhrnu událostí¶

Zdroj /analytics/events/aggregate/dimensions?programStageId=... přijímá povinný parametr programStageId a vrací následující datové dimenze:

• Data elements of supported types in the program stage
• Tracked entity attributes of supported types associated with the program (derived from programStageId)
• Kategorie v kombinaci kategorií spojených s programem (odvozeno z programStageId)
• Sady skupin možností kategorie typu ATTRIBUTE přidružené k programu (odvozeno z 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¶

Dimenze analýzy dotazů zápisu¶

Zdroj /analytics/enrollments/query/dimensions?programId=... přijímá povinné ID sledovacího programu a vrací následující datové dimenze:

• Indikátory programu připojené k programu
• 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.

Dimenze souhrnu zápisu{ #webapi_enrollment_aggregate_analytics_dimension }¶

Zdroj /analytics/enrollments/aggregate/dimensions?programId=... přijímá povinné ID trasovacího programu odkazující na program s registrací a vrací následující dimenze dat:

• 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)"
      }
   ]
}

Analytika Organizační jednotky¶

Rozhraní API pro analýzu organizačních jednotek poskytuje statistiku o organizačních jednotkách klasifikovaných podle sad skupin organizačních jednotek, tj. Počty organizačních jednotek na skupinu organizačních jednotek v rámci sad skupin organizačních jednotek.

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

API vyžaduje alespoň jednu organizační jednotku a alespoň jednu sadu skupin organizačních jednotek. Lze poskytnout více organizačních jednotek a skupinových skupin oddělených středníkem.

Parametry požadavku databázového dotazu¶

Prostředek analytiky organizační jednotky vám umožní určit řadu parametrů dotazu:

Tabulka: Parametry analytického dotazu organizační jednotky

Odpověď bude obsahovat sloupec pro nadřazenou organizační jednotku, sloupce pro každou skupinu organizačních jednotek jako část požadavku a sloupec pro počet. Statistiky zahrnují počet organizačních jednotek, které jsou součástí podhierarchie organizačních jednotek uvedených v požadavku. Odpověď obsahuje část metadat, která určuje název každé organizační jednotky a části skupiny organizační jednotky a části odpovědí, na kterou odkazují jejich identifikátory.

Výchozí odpověď je normalizována pomocí jediného sloupce count Odpověď lze vykreslit v rozložení tabulky zadáním alespoň jedné sady skupin organizačních jednotek pomocí parametru dotazu columns.

Formáty odpovědí¶

Koncový bod analytiky jednotky org podporuje následující formáty reprezentace:

• json (application/json)
• csv (application/csv)
• xls (application/vnd.ms-excel)
• pdf (application/pdf)

Příklady¶

Načtení analytiky organizačních jednotek pro organizační jednotku a sadu skupin organizačních jednotek:

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

Chcete-li načíst analytická data jednotky org pro dvě jednotky org a dvě sady skupin jednotek org:

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

Pokud chcete načíst analytická data organizační jednotky v režimu tabulky s jednou sadou skupin vykreslenou jako sloupce:

GET /api/orgUnitAnalytics?ou=fdc6uOvgoji;jUb8gELQApl;lc3eMKXaEfw;PMa2VCrupOd
  &ougs=J5jldMd8OHv&columns=J5jldMd8OHv

Omezení a validace¶

Možné chyby v ověření konkrétně pro analytické API org jednotky jsou popsány v tabulce níže. Relevantní jsou také některé chyby zadané pro agregované analytické API.

Zpráva o souboru dat¶

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

Parametry požadavku databázového dotazu¶

Požadavek podporuje následující parametry:

Tabulka: Parametry dotazu sestavy datové sady

Prostředek sestavy datové sady přijímá pouze požadavky GET. Typ obsahu odpovědi je application/json a vrací data v mřížce. Tento koncový bod funguje pro všechny typy datových sad, včetně výchozích, sekčních a vlastních formulářů.

Příklad požadavku na načtení přehledu pro měsíční soubor dat a organizační jednotku za říjen 2018 vypadá takto:

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

Příklad požadavku na načtení přehledu pro měsíční soubor dat a organizační jednotku za říjen, listopad a prosinec 2018 vypadá takto:

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

Chcete-li získat sestavu datové sady s filtrem, můžete použít parametr filter. V tomto případě je filtr založen na sadě skupin org jednotek a dvou skupinách org jednotek:

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

Formáty odpovědí¶

Koncový bod sestavy datové sady podporuje výstup v následujících formátech. Konkrétní koncový bod můžete načíst pomocí přípony souboru nebo záhlaví HTTP Accept.

• json (application/json)
• pdf (application/pdf)
• xls (application/vnd.ms-excel)

Vlastní formuláře¶

Pro datové sady s vlastními formuláři HTML je k dispozici vyhrazený koncový bod. Tento koncový bod vrací obsah formuláře HTML s typem obsahu text/html s vloženými daty. Všimněte si, že koncový bod sestavy obecné sady dat můžete použít také pro sady dat s vlastními formuláři; to však vrátí zprávu ve formátu JSON jako mřížku. Tento koncový bod funguje pouze pro datové sady s vlastními formuláři HTML.

GET /api/dataSetReport/custom

Syntaxe pro tento koncový bod se jinak rovná koncovému bodu sestavy obecné sady dat. Chcete-li načíst vlastní sestavu datové sady HTML, můžete vystavit požadavek takto:

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

Nabízená analýza¶

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:

Tabulka: Vlastnosti analýzy tlaku

Analýza využití dat¶

Rozhraní API pro analýzu používání umožňuje přístup k informacím o tom, jak lidé používají DHIS2 na základě analýzy dat. Když uživatelé přistupují k oblíbeným položkám, zaznamená se událost. Událost se skládá ze jména uživatele, UID oblíbené položky, času, kdy k události došlo, a typu události. Různé typy událostí jsou uvedeny v tabulce.

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

Parametry požadavku databázového dotazu¶

Rozhraní API pro analýzu využití (statistiku dat) podporuje dvě operace:

• POST: creates a view event

• GET: načte agregované statistiky

Vytvoření události zobrazení (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, které vytváří nové zobrazení událostí grafů:

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.

Tabulka: Podporované typy událostí

Načíst agregovaný analytický přehled využití (GET)¶

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

Tabulka: Parametry dotazu pro agregovanou analýzu využití (statistiky dat)

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

Načíst hlavní oblíbené položky¶

Rozhraní API pro analýzu využití vám umožňuje načíst nejoblíbenější oblíbené položky používané v DHIS2 a podle uživatele.

Tabulka: Parametry dotazu na oblíbené položky

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

Pokud je zadáno uživatelské jméno, odpověď bude obsahovat pouze nejoblíbenější oblíbené uživatele.

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

Formát odpovědi¶

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

• json (application/json)

• xml (application/xml)

• html (text/html)

Databázový dotaz API, který požaduje odpověď na analýzu využití ve formátu XML:

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

Postup získání odpovědi na analýzu využití ve formátu JSON:

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

Odpověď JSON vypadá takto:

[
  {
    "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
  }
]

Načíst statistiky oblíbené položky¶

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
}

Geoprostorové prvky¶

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

Hodnotu souřadnic odezvy lze číst ze dvou vlastností, o kterých rozhoduje parametr coordinateField. - Vlastnost geometry OrganisationUnit: toto je výchozí chování, které se použije, když není zadán parametr coordinateField. - Atribut OrgansationUnit typu hodnoty GeoJSON: API použije zadaný coordinateField={attributeId} k získání souřadnic GeoJSON z této hodnoty atributu.

Chcete-li například načíst geografické prvky pro všechny organizační jednotky na úrovni 3, jak je uvedeno výše, ale získat souřadnice z atributu OrganisationUnit tJqtSV4quLb

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

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

Tabulka: Odezva geografických funkcí

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.

Jsou podporovány dva parametry: level (výchozí je 1) a parent (výchozí jsou kořenové organizační jednotky). Oba mohou být zahrnuty vícekrát. Nějaké příklady:

Získejte všechny funkce na úrovni 2 a 4:

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

Získejte všechny funkce na úrovni 3 s organizační jednotkou která určuje hranice:

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

Hooks analytické tabulky¶

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.

Hooks pole¶

Hooks analytické tabulky mají následující pole:

Tabulka: Pole pro hooks tabulky Analytics

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.

V následující tabulce jsou uvedeny platné kombinace fází, typů tabulek a dočasných tabulek.

Tabulka: Fáze, typy tabulek a dočasné tabulky

Vytváření hooks¶

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'"
}

Konverze 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

Tabulka: Parametry databázového dotazu

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

Příklad

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 vysvětluje¶

/api/analytics/explain

Analytika událostí vysvětluje¶

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

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

Analytika zápisu vysvětluje¶

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