Analyses¶

Analyse¶

Pour accéder aux données analytiques et agrégées dans DHIS2, vous pouvez utiliser la ressource analyse. L'importance de la ressource "analyse" réside dans le fait qu'elle vous permet d'interroger et d'extraire des données agrégées pour toutes les dimensions de données disponibles. Par exemple, vous pouvez demander à la ressource "analyse" de vous fournir des valeurs agrégées pour un ensemble d'éléments de données, de périodes et d'unités d'organisation. Vous pouvez également récupérer les données agrégées d'une combinaison de dimensions en vous basant sur des éléments de données et des groupes d'unités d'organisation.

/api/analytics

Paramètres de requête¶

La ressource "analyse" vous permet de définir un ensemble de paramètres de requête :

Tableau : Paramètres de requête

Le paramètre de requête dimension définit les dimensions à inclure dans la requête d'analyse. Un nombre quelconque de dimensions peut être spécifié. Le paramètre "dimension" doit être répété pour chaque dimension à inclure dans la réponse à la requête. La réponse à la requête peut éventuellement contenir des valeurs agrégées pour toutes les combinaisons des éléments de dimension spécifiés.

Le paramètre filtre définit les dimensions à utiliser comme filtres pour les données extraites de la requête d'analyse. Un nombre quelconque de filtres peut être spécifié. Le paramètre "filtre" doit être répété pour chaque filtre à utiliser dans la requête. La différence entre un filtre et une dimension réside dans le fait que les dimensions du filtre ne font pas partie du contenu de la réponse à la requête et que les valeurs agrégées dans la réponse sont regroupées en fonction des dimensions du filtre. En d'autres termes, les données de la réponse seront agrégées selon les dimensions du filtre, mais les filtres ne seront pas inclus en tant que dimensions dans la réponse proprement dite. Par exemple, pour lancer une requête pour certains éléments de données filtrés par les périodes et les unités d'organisation, vous pouvez utiliser l'URL suivante :

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

Le paramètre de requête aggregationType (type d'agrégation) vous permet de définir l'opérateur d'agrégation à utiliser pour la requête. Par défaut, l'opérateur d'agrégation défini pour les éléments de données inclus dans la requête sera utilisé. Si votre requête ne contient aucun élément de données mais des groupes d'éléments de données, l'opérateur d'agrégation du premier élément de données du premier groupe sera utilisé. L'ordre des groupes et des éléments de données n'est pas défini. Ce paramètre de requête vous permet de remplacer l'opérateur d'agrégation par défaut et de définir un opérateur spécifique. Par exemple, vous pouvez le définir sur "count" (compter) avec l'URL suivante :

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

Le paramètre de requête measureCriteria (critères de mesure) vous permet de filtrer les plages d'enregistrements de données à renvoyer. Vous pouvez demander au système de ne renvoyer que les enregistrements dont les valeurs agrégées sont égales, supérieures, supérieures ou égales, inférieures ou inférieures ou égales à certaines valeurs. Vous pouvez spécifier un nombre quelconque de critères dans le format suivant, où criteria et value doivent être remplacés par des valeurs réelles :

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

À titre d'exemple, la requête suivante renverra uniquement les enregistrements pour lesquels la valeur est supérieure ou égale à 6 500 et inférieure à 33 000 :

/api/analytics?dimension=dx:fbfJHSPpUQD;cYeuwXTCPkU&dimension=pe:2014
  &dimension=ou:O6uvpzGd5pu;lc3eMKXaEfw&measureCriteria=GE:6500;LT:33000

Comme pour measureCriteria, le paramètre de requête preAggregationMeasureCriteria vous permet de filtrer les données avant que l'agrégation ne soit effectuée. Par exemple, la requête suivante n'agrège que les données dont la valeur initiale correspond aux critères définis :

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

Les paramètres startDate (date de début) et endDate (date de fin) peuvent être utilisés pour définir une plage de dates personnalisée pour l'agrégation. Lorsque vous définissez une plage de dates, vous ne pouvez pas définir de périodes relatives ou fixes en tant que dimension ou filtre. La plage de dates va filtrer la réponse de l'outil d'analyse. Vous pouvez l'utiliser comme ceci :

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

Pour que la ressource analytique génère les données sous forme d'un tableau tout fait, vous pouvez définir le paramètre tableLayout (présentation du tableau) en lui attribuant la valeur "true" (vrai). Au lieu de générer une source de données normalisée, la ressource analytique va maintenant générer les données dans un tableau. Vous pouvez utiliser les paramètres columns (colonnes) et rows (lignes) avec des identifiants de dimension séparés par des points-virgules en guise de valeurs pour indiquer ceux qui doivent apparaître dans les colonnes et ceux qui doivent apparaître dans les lignes du tableau. Les dimensions des colonnes et des lignes doivent être utilisées comme dimension de données dans la requête (et non comme filtre). Une telle requête peut ressembler à ceci :

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

Le paramètre order peut être utilisé pour les ressources analytiques afin de générer des données ordonnées. Les données seront classées dans l'ordre croissant (ou décroissant) des valeurs. Voici un exemple de requête permettant de classer les valeurs par ordre décroissant :

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

Dimensions et éléments¶

DHIS2 dispose d'un modèle de données multidimensionnel avec plusieurs dimensions de données fixes et dynamiques. Les dimensions fixes sont l'élément de données, la période (temps) et l'unité d'organisation. Vous pouvez ajouter des dimensions de manière dynamique à travers des catégories, des groupes d'options de catégories, des groupes d'unités d'organisation, des groupes d'éléments de données et des groupes d'unités d'organisation. Le tableau ci-dessous présente les dimensions de données disponibles dans DHIS2. Chaque dimension de données a un identifiant de dimension correspondant, et chaque dimension peut avoir un ensemble d'éléments de dimension :

Tableau : Dimensions et éléments de dimension

Il n'est pas nécessaire de savoir quels objets sont utilisés pour les différentes dimensions dynamiques lors de la conception des requêtes analytiques. Vous pouvez obtenir une liste complète des dimensions dynamiques en visitant cette URL dans l'API Web :

/api/dimensions

Si vous souhaitez extraire uniquement les éléments dimensionnels d'une dimension dynamique donnée, vous pouvez utiliser l'exemple ci-dessous. La pagination est désactivée par défaut. Elle peut être activée si le paramètre de pagination paging=true est ajouté à l'URL.

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

L'API /dimensions fournit également un point d'extrémité où les clients peuvent obtenir les recommandations pour un ensemble de dimensions spécifique. Par exemple :

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

In the example above, the response will contain the categories which are configured as data dimensions and associated, through data sets and category combos, with the data element fbfJHSPpUQD. In addition, all org unit group sets which are configured as data dimensions will be returned.

Le point d'extrémité peut accepter plusieurs éléments de données. Si l'on souhaite envoyer plusieurs éléments de données, ils doivent être séparés par un point virgule;. Par exemple :

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

Remarque

Ce point d'extrémité renvoie uniquement les dimensions qui peuvent être lues par l'utilisateur actuellement connecté. Il vérifiera si cet utilisateur peut lire les données ou les métadonnées de la dimension recommandée. Les dimensions non autorisées ne sont pas incluses dans la liste.

L'URL de base de la ressource analytique est /api/analytics. Pour demander des dimensions et des éléments de dimension spécifiques, vous pouvez utiliser une chaîne de requête au format suivant, où dim-id (identifiant de la dimension) et dim-item (élément de dimension) doivent être remplacés par des valeurs réelles :

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

Comme illustré ci-dessus, l'identifiant de la dimension est suivi de deux points, tandis que les éléments de la dimension sont séparés par des points-virgules. Par exemple, une requête portant sur deux éléments de données, deux périodes et deux unités d'organisation peut être effectuée à l'aide de l'URL suivante :

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

Pour obtenir des données ventilées par combinaisons d'options de catégorie au lieu des totaux des éléments de données, vous pouvez inclure la dimension de catégorie dans la chaîne de requête. Voici une exemple :

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

Au moment de sélectionner des éléments de données, vous pouvez également sélectionner tous les éléments de données d'un groupe en tant qu'éléments en utilisant la syntaxe DE_GROUP-<id> :

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

Au moment de sélectionner les taux de déclaration des ensembles de données, la syntaxe contient un identifiant d'ensemble de données suivi d'une mesure de taux de déclaration :

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

Pour obtenir des éléments de données de programme (de type Tracker), vous pouvez spécifier le programme pour chaque élément de données à l'aide de la syntaxe <program-id>.<dataelement-id> :

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

Pour obtenir des attributs de programme (attributs d'entités suivies), vous pouvez spécifier le programme pour chaque attribut à l'aide de la syntaxe <program.id>.<attribute-id> :

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

Pour obtenir des ensembles de groupes d'unités d'organisation et des éléments de données, vous pouvez utiliser l'URL ci-dessous. Remarquez que l'identifiant de l'ensemble de groupes est utilisé comme identifiant de dimension et les groupes comme éléments de dimension :

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

Pour obtenir des éléments de données et des catégories, vous pouvez utiliser l'URL suivante. Utilisez l'identifiant de la catégorie comme identifiant de dimension et les options de la catégorie comme éléments de dimension :

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

Pour effectuer une requête en utilisant des périodes relatives et des unités d'organisation associées à l'utilisateur actuellement connecté, vous pouvez utiliser l'URL suivante :

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

Lorsque vous sélectionnez des unités d'organisation pour une dimension, vous pouvez utiliser la syntaxe LEVEL-<level> pour sélectionner un niveau entier, éventuellement limité par un nombre quelconque d'unités d'organisation limites. La limite renvoie à un nœud supérieur dans une sous-hiérarchie, ce qui signifie que toutes les unités d'organisation au niveau indiqué sous l'unité d'organisation limite indiquée dans la hiérarchie seront incluses dans la réponse et sont fournies en tant qu'éléments de dimension d'unité d'organisation ordinaires. La valeur du niveau peut être un niveau numérique ou faire référence à l'identifiant de l'entité du niveau de l'unité d'organisation. Voici une requête simple pour toutes les unités d'organisation de niveau trois :

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

Une requête pour les niveaux trois et quatre avec deux unités d'organisation limites peut se présenté comme suit :

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

Lors de la sélection des unités d'organisation, vous pouvez également sélectionner toutes les unités d'organisation d'un groupe d'unités d'organisation, lesquelles seront incluses en tant qu'éléments de dimension. Vous pouvez le faire en utilisant la syntaxe OU_GROUP-<id>. Les unités d'organisation qui se trouvent dans les groupes peuvent éventuellement être limitées par un nombre quelconque d'unités d'organisation limites. Les éléments de niveau et de groupe peuvent être répétés autant de fois que nécessaire :

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

Vous pouvez utiliser des schémas d'identification pour la partie métadonnées de la réponse analytique avec la propriété outputIdScheme (schéma d'identification de la sortie). Vous pouvez utiliser l'identifiant, le code ou les attributs comme schéma d'identification. Voici un exemple :

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

Quelques éléments à prendre en compte lors de l'utilisation de la ressource analytique sont répertoriés ci-dessous.

• Les éléments de données, les indicateurs, les taux de déclaration des ensembles de données, les éléments de données de programme et les indicateurs de programme font partie d’une dimension de données commune, identifié comme "dx". Cela signifie que vous pouvez utiliser n'importe quelle élément de données, indicateur et identifiant d'ensemble de données avec l'identifiant de dimension "dx" dans la requête.

• Pour les dimensions "catégorie", "ensemble de groupes d'éléments de données" et "ensemble de groupes d'unités d'organisation", tous les éléments de dimension seront utilisés dans la requête si des éléments de dimension ne sont pas spécifiés.

• Pour la dimension de période, les éléments de dimension sont des identifiants de période ISO et/ou des périodes relatives. Consultez la section "Format de date et de période" plus haut, pour mieux comprendre le format des périodes et les périodes relatives disponibles.

• For the organization unit dimension, you can specify items as either the organization unit or its sub-units associated with the currently authenticated user. Use the keys USER_ORGUNIT for the organization unit itself or USER_ORGUNIT_CHILDREN for its sub-units. You may also specify organization unit identifiers directly or use a combination of both. The authenticated user must have permission to export and analyze data for the designated organization units.

• Pour la dimension d'unité d'organisation, vous pouvez spécifier le niveau hiérarchique et l'unité d'organisation limite à utiliser pour la requête en utilisant le format LEVEL-<level>-<boundary-id>. Par exemple, LEVEL-3-ImspTQPwCqd prend en compte toutes les unités d'organisation inférieures à l'unité d'organisation limite au niveau 3 de la hiérarchie.

• Pour la dimension d'unité d'organisation, les éléments de dimension sont les unités d'organisation et leur sous-hiérarchie - les données seront agrégées pour toutes les unités d'organisation situées en dessous de l'unité d'organisation spécifiée dans la hiérarchie.

• Vous ne pouvez pas spécifier d'éléments de dimension pour la dimension de combinaison d'options de catégorie. En lieu et place de cela, la réponse contiendra les éléments associés aux valeurs de données.

La dimension dx¶

La dimension dx est une dimension spéciale qui peut contenir tous les types de données suivants.

Tableau : Types de dimensions de données dx

Les éléments de tous les différents types dx peuvent être combinés dans une requête d'analyse. Voici un exemple :

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

La syntaxe de groupe peut également être utilisée avec n’importe quel autre élément. Voici un exemple :

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

Les opérandes d'élément de données peuvent éventuellement spécifier des combinaisons d'options d'attribut et utiliser des caractères génériques, par exemple pour spécifier toutes les valeurs des combinaisons d'options de catégorie :

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

Conseil

Pour apprendre à utiliser l'API d'analyse, vous pouvez utiliser l'application web DHIS2 Visualiseur de Données et créer un tableau croisé dynamique. Vous pouvez vous amuser avec des tableaux croisés dynamiques en utilisant les différentes dimensions et éléments et cliquer sur Télécharger > Source de données simples > JSON pour voir les appels de l'API analytique qui en résultent dans la barre d'adresse de votre navigateur web. >>>>

Formats de réponse¶

La réponse analytique contenant les données agrégées peut être renvoyée sous différents formats. Comme toujours, vous pouvez définir un format spécifique en ajoutant une extension de fichier à l'URL, via l'en-tête HTTP Accept ou via le paramètre de requête format. Le format par défaut est JSON. Les formats et types de contenu disponibles sont listés ci-dessous.

• json (application/json)

• jsonp (application/javascript)

• xml (application/xml)

• csv (application/csv)

• html (texte/html)

• html+css (texte/html)

• xls (application/vnd.ms-excel)

À titre d'exemple, vous pouvez demander une réponse analytique au format XML, en utilisant l'URL suivante :

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

La réponse JSON ressemblera à ceci :

{
  "headers": [
    {
      "name": "dx",
      "column": "Data",
      "valueType": "TEXT",
      "meta": true
    },
    {
      "name": "pe",
      "column": "Period",
      "valueType": "TEXT",
      "meta": true
    },
    {
      "name": "value",
      "column": "Value",
      "valueType": "NUMBER",
      "meta": false
    }
  ],
  "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
}

La réponse représente un tableau de données dimensionnelles. L'en-tête donne un aperçu des colonnes du tableau et de leur contenu. La propriété colonne indique l'identifiant de la dimension de la colonne ou, si la colonne contient des mesures, le mot "Value". La propriété métadonnées est définie sur vrai si la colonne contient des éléments de dimension ou faux si la colonne contient une mesure (valeurs de données agrégées). La propriété nom est similaire à la propriété "colonne", à la différence qu'elle affiche "valeur" lorsque la colonne contient une mesure. La propriété type indique le type de classe Java des valeurs de la colonne.

Les propriétés hauteur et largeur indiquent respectivement le nombre de colonnes et de lignes de données contenues dans la réponse.

La propriété périodes de métadonnées contient un tableau unique et ordonné des périodes contenues dans la réponse. La propriété unité d'organisation de métadonnées contient un tableau d'identifiants d'unités d'organisation contenues dans la réponse. La propriété noms de métadonnées permet d'obtenir une correspondance entre les identifiants utilisés dans la réponse et les noms des objets qu'ils représentent. Les clients peuvent utiliser cette propriété pour remplacer les identifiants de la réponse par des noms afin d'obtenir une représentation plus claire du tableau de données.

La rubrique lignes contient le tableau des données dimensionnelles. Ce dernier est fait de colonnes dans lesquelles figurent des éléments de dimension (identifiants d'objets ou de périodes) et une colonne dans laquelle figurent des valeurs de données agrégées. L'exemple de réponse ci-dessus comporte une colonne pour les données et les indicateurs, une colonne pour les périodes et une colonne pour les valeurs. La première colonne contient les identifiants d'indicateur, la deuxième contient les identifiants de période ISO et la troisième contient les valeurs de données agrégées.

Contraintes et validation¶

Les paramètres d'entrée que vous pouvez fournir à la ressource analytique sont soumis à plusieurs contraintes. Si l'une de ces contraintes n'est pas respectée, l'API renvoie une réponse 409 Conflict avec un message semblable à celui-ci :

{
  "httpStatus": "Conflict",
  "httpStatusCode": 409,
  "status": "ERROR",
  "message": "Only a single indicator can be specified as filter",
  "errorCode": "E7108"
}

Les champs httpStatus et httpStatusCode indiquent le statut HTTP et le code de statut conformément à la spécification HTTP. Le champ message fournit une description de l'erreur de validation lisible par l'homme. Le champ errorCode fournit un code lisible par une machine que les clients peuvent utiliser pour gérer les erreurs de validation. Les erreurs de validation potentielles pour l'API d'analyse des données agrégées sont décrites dans le tableau ci-dessous.

Format d'ensemble de valeurs de données¶

La ressource analytique dataValueSet permet de renvoyer des données agrégées dans le format "ensemble de valeurs de données". Ce format représente des valeurs de données brutes, par opposition aux données qui ont été agrégées en fonction des différentes dimensions. L'exportation de données agrégées sous la forme de valeurs de données régulières permet d'échanger des données entre systèmes lorsque le système cible contient des données d'une granularité plus fine que celles stockées par le système de destination.

Par exemple, il est possible de spécifier un indicateur dans le système cible qui va récapituler les données de plusieurs éléments de données, et d'importer ces données pour le compte d'un seul élément de données dans le système de destination. Autre exemple, l'on peut agréger les données collectées au niveau 4 de l'unité d'organisation dans le système cible au niveau 2 et importer ces données dans le système de destination.

Vous pouvez récupérer des données au format d'ensemble de valeurs de données brutes à partir de la ressource dataValueSet :

/api/analytics/dataValueSet

Les représentations de ressources suivantes sont prises en charge :

• json (application/json)

• xml (application/xml)

Lorsque vous utilisez le format d'ensemble de valeurs de données, exactement trois dimensions doivent être spécifiées en tant que dimensions analytiques avec au moins un élément de dimension pour chacune d'entre elles :

• Données (dx)

• Période (pe)

• Unité d'organisation (ou)

Toute autre dimension sera ignorée. Les filtres seront appliqués de la même manière que pour les demandes d'analyse ordinaires. Notez que tout type de dimension de données peut être spécifié, notamment les indicateurs, les éléments de données, les opérandes d'éléments de données, les ensembles de données et les indicateurs de programme.

Voici un exemple de requête qui agrège des données pour des indicateurs, des périodes et des unités d'organisation spécifiques et les renvoie sous forme de valeurs de données régulières au format XML :

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

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

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

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

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

Format de données brutes¶

La ressource analytique rawData permet de renvoyer les données stockées dans les tableaux de données analytiques sans qu'aucune agrégation ne soit effectuée. Cette ressource permet aux clients qui le souhaitent d'effectuer eux-mêmes des agrégations et des filtrages sans avoir à dénormaliser eux-mêmes les données existant dans les dimensions disponibles.

/api/analytics/rawData

Les représentations de ressources suivantes sont prises en charge :

• json (application/json)

• csv (application/csv)

Cette ressource respecte la syntaxe d'une ressource analytique ordinaire. Seul un sous-ensemble de paramètres de requête est pris en charge. En outre, les paramètres startDate et endDate sont disponibles. Les paramètres pris en charge sont énumérés dans le tableau ci-dessous.

Tableau : Paramètres de requête

Le paramètre de requête dimension définit les dimensions (colonnes du tableau) à inclure dans la réponse. Il peut éventuellement être limité par des éléments. Le paramètre de requête filter (filtre) définit les éléments et les dimensions (colonnes du tableau) qui doivent être utilisés pour filtrer la réponse.

Pour la dimension "unité d'organisation", la réponse contiendra les données associées à l'unité d'organisation et à toutes les unités d'organisation qui lui sont inférieures dans la hiérarchie (c'est-à-dire ses subordonnées). Ceci est différent de la ressource analytique ordinaire, où seules les unités d'organisation explicitement sélectionnées sont incluses dans la réponse.

Pour obtenir une réponse contenant des éléments de données, périodes et unités d'organisation spécifiques, ainsi que toutes les données relatives à deux dimensions personnalisées, vous pouvez lancer une requête de ce type :

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

Les paramètres startDate et endDate permettent de récupérer des données associées à toute période comprise entre ces dates. Avec cette méthode, nul besoin de définir explicitement toutes les périodes dans la requête :

/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

Le paramètre filter peut être utilisé pour filtrer une réponse sans inclure cette dimension dans la réponse, cette fois au format CSV :

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

Vous pouvez utiliser le paramètre outputIdScheme (schéma d'identification de la sortie) pour obtenir des données lisibles par l'homme, car il peut être défini sur NOM comme dans l'exemple suivant :

/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

La réponse de la ressource rawData est identique à celle de la ressource analytique ordinaire, à la différence qu'elle contient des données brutes et non agrégées qui peuvent être agrégées ultérieurement par des systèmes tiers.

Débogage¶

Lors du débogage des requêtes analytiques, il peut être utile d'examiner la source des valeurs de données de la réponse analytique agrégée. La ressource analytics/debug/sql fournira une instruction SQL qui renvoie le contenu recherché du tableau des valeurs de données. Vous pouvez produire cette instruction SQL en effectuant une requête GET avec le type de contenu "text/html" ou "text/plain" comme ci-dessous. La syntaxe des dimensions et des filtres est identique à celle des requêtes analytiques ordinaires :

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

Analyse d'événements¶

L'API d'analyse d'événements vous permet d'accéder à des données d'événements agrégées et d'interroger des événements capturés dans DHIS2. Cette ressource vous permet d'extraire des événements à partir d'un programme et éventuellement d'une étape de programme. Elle vous permet également d'extraire et de filtrer des événements en fonction des différentes dimensions d'événements.

/api/analytics/events

Dimensions et éléments¶

Les dimensions d'événements comprennent les éléments de données, les attributs, les unités d'organisation et les périodes. La ressource analytique des événements agrégés renvoie des informations agrégées telles que des chiffres issus de comptages ou des moyennes. La ressource analytique de requête renvoie simplement les événements correspondant à un ensemble de critères et n'effectue aucune agrégation. Vous pouvez spécifier des éléments de dimension sous la forme d'options à partir d'ensembles d'options et de légendes à partir d'ensembles de légendes, pour les éléments de données et les attributs qui y sont associés. Les dimensions des événements sont répertoriées dans le tableau ci-dessous.

Tableau : Dimensions d'événement

Paramètres de requête{ #webapi_event_analytics_request_query_parameters }¶

L'API d'événement analytique vous permet de définir un ensemble de paramètres de requête.

Tableau : Paramètres de requête pour la requête d'événement et l'analyse d'agrégation

Tableau : Paramètres de requête pour l'analyse des requêtes d'événement uniquement

Tableau : Paramètres de requête pour l'analyse agrégée des événements uniquement

Tableau : Paramètres de requête pour les analyses d'événements en grappes uniquement

Note

When coordinateField references a data element or tracked entity attribute of value type organisation unit, the organisation unit's own geometry is used, represented by its centroid. In addition to the EVENT, ENROLLMENT and TRACKER keywords, the raw analytics geometry column names eventgeometry, enrollmentgeometry, tegeometry and ougeometry are accepted directly (tegeometry only for programs with registration). The aliases pigeometry (enrollment), psigeometry (event) and teigeometry (tracked entity) are deprecated, retained only for backwards compatibility, and will be removed in a future release.

Analyse des requêtes d'événements¶

La ressource analytics/events/query vous permet d'effectuer des requêtes sur des événements capturés. Cette ressource n'effectue pas d'agrégation ; elle vous permet plutôt de lancer des requêtes et de filtrer les informations sur les événements.

/api/analytics/events/query

Vous pouvez spécifier un nombre quelconque de dimensions et de filtres dans une requête. Les identifiants d'éléments de dimension peuvent faire référence à des éléments de données, des attributs de personnes, des identifiants de personnes, des périodes fixes et relatives et des unités d'organisation. Les dimensions peuvent éventuellement être accompagnées d'un opérateur de requête et d'un filtre. Les requêtes d'événements doivent respecter le format décrit ci-dessous.

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

Par exemple, pour extraire des événements du programme "Morbidité et mortalité chez les patients hospitalisés" entre janvier et octobre 2016, où les éléments de données "Sexe" et "Âge" sont inclus et où la dimension "Âge" est filtrée sur "18 ans", vous pouvez utiliser la requête suivante :

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

Pour extraire les événements de l'étape "Naissance" du "Programme pour les enfants" entre mars et décembre 2016, où l'élément de données "Poids" est filtré pour les valeurs supérieures à 2000, vous pouvez utiliser ce qui suit :

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

Le tri peut être appliqué à la requête pour la date de l'événement et toutes les dimensions. Pour effectuer un tri par ordre décroissant sur la date de l'événement et par ordre croissant sur la dimension de l'élément de données "Âge", vous pouvez utiliser ceci :

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

Vous pouvez appliquer la pagination à la requête à travers les paramètres de numéro de page et de taille de page. Si le numéro de page est spécifié mais que la taille de la page ne l'est pas, la taille de page "50" sera utilisée. Si la taille de la page est spécifiée mais que le numéro de page ne l'est pas, le numéro de page "1" sera utilisé. Pour obtenir la troisième page de la réponse avec une taille de page de 20, vous pouvez utiliser la requête suivante :

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

Filtrage¶

Des filtres peuvent être appliqués aux éléments de données, aux attributs de personnes et aux identifiants de personnes. Le filtrage est effectué par le biais de la valeur du paramètre de la requête dans le format suivant :

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

À titre d'exemple, vous pouvez filtrer l'élément de données "Poids" pour les valeurs supérieures à 2000 et inférieures à 4000 comme suit :

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

Vous pouvez filtrer l'élément de données "Âge" pour plusieurs âges spécifiques à l'aide de l'opérateur IN comme dans l'exemple suivant :

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

Vous pouvez spécifier plusieurs filtres pour un élément donné en répétant les composants de l'opérateur et du filtre, tous séparés par des points-virgules :

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

Les opérateurs disponibles sont répertoriés ci-dessous.

Tableau : Opérateurs de filtre

Filtrage des champs de temps¶

Par défaut, les points d'extrémité query (requête) filtrent les périodes sur la base de eventDate (date de l'événement). Il est également possible de filtrer les entrées en fonction de lastUpdated (dernière mise à jour) ou de schedule (programmation), en utilisant le paramètre de requête timeField (champ de temps). Par exemple :

&timeField=LAST_UPDATED
&timeField=SCHEDULED_DATE

Conditions améliorées¶

Par défaut, enhancedConditions (conditions améliorées) est défini sur false. Cela signifie que toutes les conditions exprimées dans dimension et filtre sont considérées comme des conditions AND (et). Par exemple :

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

se traduit par la condition logique suivante :

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

Cependant, dans certains cas, il peut être nécessaire d'avoir plus de contrôle sur les conditions. Vous pouvez activer ce contrôle en définissant le paramètre de requête enhancedConditions sur true. En procédant ainsi, un client peut utiliser un séparateur spécial _OR_ pour joindre des conditions en utilisant l'opérateur logique OR (ou).

Exemple:

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

se traduit par la condition logique suivante :

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

Formats de réponse¶

Le format de représentation de réponse par défaut est JSON. Les requêtes doivent utiliser la méthode HTTP GET. Les formats de réponse suivants sont pris en charge.

• json (application/json)

• jsonp (application/javascript)

• xls (application/vnd.ms-excel)

À titre d'exemple, pour obtenir une réponse au format Excel, vous pouvez utiliser une extension de fichier dans l'URL de la requête comme ceci :

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

Vous pouvez définir le paramètre de requête hierarchyMeta (hiérarchie de métadonnées) sur "true" pour inclure les noms de toutes les unités d'organisation ascendantes dans la section métadonnées de la réponse :

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

Le format JSON de réponse par défaut ressemblera à ceci :

{
  "headers": [
    {
      "name": "psi",
      "column": "Event",
      "valueType": "TEXT",
      "hidden": false,
      "meta": false
    },
    {
      "name": "ps",
      "column": "Program stage",
      "valueType": "TEXT",
      "hidden": false,
      "meta": false
    },
    {
      "name": "eventdate",
      "column": "Event date",
      "valueType": "TEXT",
      "hidden": false,
      "meta": false
    },
    {
      "name": "storedby",
      "column": "Stored by",
      "valueType": "TEXT",
      "hidden": false,
      "meta": true
    },
    {
      "name": "lastupdated",
      "column": "Last Updated",
      "valueType": "DATE",
      "hidden": false,
      "meta": true
    },
    {
      "name": "createdbydisplayname",
      "column": "Created by (display name)",
      "valueType": "TEXT",
      "hidden": false,
      "meta": true
    },
    {
      "name": "lastupdatedbydisplayname",
      "column": "Last updated by (display name)",
      "valueType": "TEXT",
      "hidden": false,
      "meta": true
    },
    {
      "name": "coordinates",
      "column": "Coordinates",
      "valueType": "COORDINATE",
      "hidden": false,
      "meta": false
    },
    {
      "name": "ouname",
      "column": "Organisation unit name",
      "valueType": "TEXT",
      "hidden": false,
      "meta": false
    },
    {
      "name": "oucode",
      "column": "Organisation unit code",
      "valueType": "TEXT",
      "hidden": false,
      "meta": false
    },
    {
      "name": "ou",
      "column": "Organisation unit",
      "valueType": "TEXT",
      "hidden": false,
      "meta": false
    },
    {
      "name": "oZg33kd9taw",
      "column": "Gender",
      "valueType": "TEXT",
      "hidden": false,
      "meta": false
    },
    {
      "name": "qrur9Dvnyt5",
      "column": "Age",
      "valueType": "TEXT",
      "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"
    ]
  ]
}

La section en-têtes de la réponse décrit le contenu du résultat de la requête. L'identifiant unique de l'événement, l'identifiant de l'étape de programme, la date de l'événement, le nom de l'unité d'organisation, le code de l'unité d'organisation et l'identifiant de l'unité d'organisation apparaissent en tant que six premières dimensions dans la réponse et seront toujours présents. Viennent ensuite les éléments de données, les attributs et identifiants de personnes qui ont été définis comme dimensions dans la demande ; il s'agit dans ce cas précis des dimensions d'éléments de données "Sexe" et "Âge". L'identifiant de l'élément de dimension se trouve dans la propriété "nom" et une description lisible de la dimension dans la propriété "colonne" de la section d'en-têtes.

La section metaData, objet ou (unité d'organisation), contient les identifiants de toutes les unités d'organisation présentes dans la réponse, mis en correspondance avec une chaîne qui représente la hiérarchie. Cette chaîne hiérarchique énumère les identifiants des ascendants de l'unité d'organisation en commençant par la racine. L'objet noms contient les identifiants de tous les éléments de la réponse mis en correspondance avec leurs noms.

La section lignes contient les événements produits par la requête. Chaque ligne représente exactement un événement.

Pour que la ressource analytique des événements génère les données dans un tableau tout fait, vous pouvez renseigner les paramètres lignes et colonnes avec les identifiants des dimensions requises. Ces identifiants doivent être séparés par des points-virgules ; elles serviront de valeurs pour indiquer quelles dimensions doivent être utilisées comme colonnes ou lignes du tableau. Au lieu de générer une source de données simples et normalisées, la ressource analytique d'événements va maintenant générer les données dans un tableau. Dans la requête, les dimensions de colonnes et de lignes doivent figurer en tant que dimensions de données (et non en tant que filtre). Une telle requête peut ressembler à ceci :

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

Analyse agrégée des événements¶

La ressource /analytics/events/aggregate vous permet d'extraire des nombres agrégés d'événements capturés dans DHIS2. Cette ressource vous permet d'extraire des données agrégées liés à un programme spécifique ou éventuellement à une étape de programme. Elle vous permet également d'effectuer des filtrages en fonction de toute dimension d'événement.

/api/analytics/events/aggregate

La ressource d'agrégation des événements ne renvoie pas les informations relatives à l'événement lui-même, mais plutôt les nombres agrégés d'événements correspondant à la requête. Les dimensions d'événements comprennent les éléments de données, les attributs de personnes, les identifiants de personnes, les périodes et les unités d'organisation. Les requêtes d'agrégation des événements doivent respecter le format décrit ci-dessous.

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

Par exemple, pour extraire des nombres agrégés des événements du programme "Morbidité et mortalité chez les patients hospitalisés" entre janvier et octobre 2016, où les éléments de données "Sexe" et "Âge" sont inclus, avec l'élément de dimension "Âge" filtré sur "18 ans" et l'élément de dimension "Sexe" filtré sur "Femme", vous pouvez utiliser la requête suivante :

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

Pour extraire des données relatives à des périodes fixes et relatives au lieu des dates de début et de fin, dans ce cas, mai 2016 et les 12 derniers mois, et l'unité d'organisation associée à l'utilisateur actuel, vous pouvez utiliser la requête suivante :

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

Afin de spécifier "Femme" comme filtre pour le "Sexe" dans la réponse, ce qui signifie que "Sexe" ne fera pas partie de la réponse mais filtrera les nombres agrégés qu'il contient, vous pouvez utiliser la syntaxe suivante :

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

Pour spécifier l'unité d'organisation "Bo" et la période "2016" comme filtres, et le "Mode de sortie" et le "Sexe" comme dimensions, où le "Sexe" est filtré en fonction de l'élément "Masculin", vous pouvez utiliser la requête suivante :

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

Pour créer un "rapport de Top 3" pour le Mode de sortie, vous pouvez utiliser les paramètres de requête "limit" (limite) et sortOrder (ordre de tri) de la manière suivante :

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

Pour spécifier une dimension de valeur avec un type d'agrégation correspondant, vous pouvez utiliser les paramètres de requête "value" (valeur) et "aggregationType" (type d'aggrégation). En spécifiant une dimension de valeur, le moteur d'analyse renverra des valeurs agrégées pour les valeurs de cette dimension dans la réponse, plutôt que des nombres d'événements.

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

Pour que l'agrégation des analyses d'événements se fasse en fonction d'un élément de données ou d'un attribut spécifique de type 'date' ou 'date et heure', vous pouvez utiliser le paramètre timeField (champ de temps) :

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

Pour que l'agrégation des analyses d'événements se fasse en fonction d'un élément de données ou d'un attribut spécifique de type 'unité d'organisation', vous pouvez utiliser le paramètre orgUnitField (champ d'unité d'organisation) :

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

Voici quelques valeurs possibles pour le paramètre orgUnitField :

Plages / ensembles de légendes¶

Pour les requêtes d'agrégation, vous pouvez spécifier une plage ou un ensemble de légendes pour les éléments de données numériques et les dimensions d'attributs. L'objectif est de regrouper les valeurs numériques dans des plages. Par exemple, au lieu de générer des données pour un élément de données "Âge" pour des années différentes, vous pouvez regrouper les informations par tranche d'âge. Pour ce faire, l'élément de données ou l'attribut doit être associé à l'ensemble de légendes. Le format est décrit ci-dessous :

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

Voici donc un exemple :

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

Formats de réponse¶

Le format de représentation de réponse par défaut est JSON. Les requêtes doivent utiliser la méthode HTTP GET. La réponse va ressembler à ceci :

{
  "headers": [
    {
      "name": "oZg33kd9taw",
      "column": "Gender",
      "valueType": "TEXT",
      "meta": false
    },
    {
      "name": "qrur9Dvnyt5",
      "column": "Age",
      "valueType": "TEXT",
      "meta": false
    },
    {
      "name": "pe",
      "column": "Period",
      "valueType": "TEXT",
      "meta": false
    },
    {
      "name": "ou",
      "column": "Organisation unit",
      "valueType": "TEXT",
      "meta": false
    },
    {
      "name": "value",
      "column": "Value",
      "valueType": "TEXT",
      "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"
    ]
  ]
}

La limite maximale de lignes que peut comporter une réponse est de 10 000. Si la requête produit plus que la limite maximale, un code de statut 409 Conflict sera renvoyé.

Analyse des événements en grappes{ #webapi_event_clustering_analytics }¶

La ressource analytics/events/cluster fournit des données géospatiales en grappes. Une requête se présente comme suit :

/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

La réponse fournit le nombre de points sous-jacents, le point central et l'étendue de chaque grappe. Si le paramètre de requête includeClusterPoints (inclure des points en grappe) est défini sur 'true' (vrai), une chaîne contenant les identifiants des événements sous-jacents, séparés par des virgules, sera incluse dans la réponse. Voici un exemple de réponse :

{
  "headers": [
    {
      "name": "count",
      "column": "Count",
      "valueType": "INTEGER",
      "meta": false
    },
    {
      "name": "center",
      "column": "Center",
      "valueType": "TEXT",
      "meta": false
    },
    {
      "name": "extent",
      "column": "Extent",
      "valueType": "TEXT",
      "meta": false
    },
    {
      "name": "points",
      "column": "Points",
      "valueType": "TEXT",
      "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)",
      ""
    ]
  ]
}

Analyse du nombre d'événements et de la portée¶

La ressource analytics/events/count est utilisée pour les requêtes de géométrie afin d'obtenir le nombre et l'étendue (zone de délimitation) des événements pour une requête spécifique. La syntaxe de la requête est identique à celle de la ressource events/query. Voici l'exemple d'une requête :

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

La réponse va fournir le nombre et l'étendue dans le format JSON :

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

Contraintes et validation¶

Les paramètres d'entrée que vous pouvez fournir à la ressource d'analyse des événements sont soumis à plusieurs contraintes. Si l'une de ces contraintes n'est pas respectée, l'API renvoie une réponse 409 Conflict avec un message semblable à celui-ci :

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

Les erreurs de validation possibles pour l'API d'analyse d'événements sont décrites dans le tableau ci-dessous.

Analyse des inscriptions¶

L'API d'analyse des inscriptions vous permet d'accéder aux données agrégées des événements et d'interroger les inscriptions avec leurs données d'événements capturées dans DHIS2. Cette ressource vous permet d'extraire des données d'un programme à partir des étapes du programme et des éléments de données, en plus des attributs d'entités suivies. Lorsque vous effectuez une requête sur des données d'événements pour des étapes spécifiques d'un programme au sein de chaque inscription, les valeurs des éléments de données pour chaque étape du programme seront renvoyées dans une même ligne dans la réponse de l'API. Si vous effectuez une requête sur un élément de données dans une étape répétable du programme, la valeur la plus récente de l'élément de données sera utilisée pour cet élément de données dans la réponse de l'API.

Dimensions et éléments¶

Les dimensions d'inscription comprennent les éléments de données, les attributs, les unités d'organisation et les périodes. La ressource d'analyse des requêtes renvoie simplement les inscriptions correspondant à un ensemble de critères et n'effectue aucune agrégation.

Tableau : Dimensions dl'inscription

Étapes répétables¶

L'identifiant de l'élément de données doit inclure l'étape de programme. L'étape de programme peut être répétée. Par exemple, la dimension edqlbukwRfQ.vANAXwtLwcT peut faire référence à une étape de programme répétable. L'élément de données de cette étape est accessible via les paramètres d'index (entourés de [ ]).

Tableau : Possibilités d'indexation des étapes répétables

Avertissement : L'indexation d'une étape de programme non répétable entraîne une erreur de validation des paramètres.

Analyse des requêtes d'inscription¶

La ressource analytics/enrollments/query vous permet d'effectuer des requêtes sur des inscriptions capturés. Cette ressource n'effectue pas d'agrégation ; elle vous permet plutôt de lancer des requêtes et de filtrer les informations sur les inscriptions.

/api/analytics/enrollments/query

Vous pouvez spécifier un nombre quelconque de dimensions et de filtres dans une requête. Les identifiants d'éléments de dimension peuvent faire référence à tout élément de données dans des étapes de programme, des attributs de personnes, des périodes fixes et relatives et des unités d'organisation. Les dimensions peuvent éventuellement être accompagnées d'un opérateur de requête et d'un filtre. Les requêtes d'inscription doivent respecter le format décrit ci-dessous.

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

Par exemple, pour extraire des inscriptions au programme "Soins prénatals" à partir de janvier 2019, où le "Prénom" est tiré des attributs, les éléments de données "Maladies chroniques" et "Tabagisme" sont inclus à partir de la première étape du programme, la "Valeur de l'hémoglobine" à partir de l'étape suivante du programme, et où seules les femmes atteintes de "Maladies chroniques" sont incluses, vous pouvez utiliser la requête suivante :

/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

Pour extraire des inscriptions au programme "Soins prénatals" à partir du mois dernier (par rapport au moment où la requête est effectuée), où les éléments de données "Maladies chroniques" et "Tabagisme" sont inclus à partir de la première étape du programme, et "Valeur de l'hémoglobine" à partir de l'étape de suivi du programme, et où seules les femmes fumeuses avec un taux d'hémoglobine inférieur à 20 sont prises en compte :

/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

Un tri peut être appliqué à la requête pour les dates d'inscription et d'incident :

/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

Vous pouvez appliquer la pagination à la requête à travers les paramètres de numéro de page et de taille de page. Si le numéro de page est spécifié mais que la taille de la page ne l'est pas, la taille de page "50" sera utilisée. Si la taille de la page est spécifiée mais que le numéro de page ne l'est pas, le numéro de page "1" sera utilisé. Pour obtenir la deuxième page de la réponse avec une taille de page de 10, vous pouvez utiliser la requête suivante :

/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

Filtrage¶

Des filtres peuvent être appliqués aux éléments de données, aux attributs de personnes et aux identifiants de personnes. Le filtrage est effectué par le biais de la valeur du paramètre de la requête dans le format suivant :

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

À titre d'exemple, vous pouvez filtrer l'élément de données "Poids" pour les valeurs supérieures à 2000 et inférieures à 4000 comme suit :

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

Vous pouvez filtrer l'attribut "Âge" pour plusieurs âges spécifiques à l'aide de l'opérateur IN comme dans l'exemple suivant :

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

Vous pouvez spécifier plusieurs filtres pour un élément donné en répétant les composants de l'opérateur et du filtre, tous séparés par des points-virgules :

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

Filtrage des champs de temps¶

Par défaut, les points d'extrémité query (requête) filtrent les périodes sur la base de enrollmentDate (date d'inscription). Il est également possible de filtrer les entrées en fonction de lastUpdated (dernière mise à jour) en utilisant le paramètre de requête timeField (champ de temps). Par exemple :

&timeField=LAST_UPDATED

Mot-clé NV¶

Un mot-clé spécial NV peut être utilisé pour filtrer les valeurs null (nulles).

Le filtrage par l'ÂGE est nul

&dimension=qrur9Dvnyt5:EQ:NV

Le filtrage par l'ÂGE est non nul

&dimension=qrur9Dvnyt5:NE:NV

Le filtrage par l'ÂGE est 18, 19 ou est nul

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

NV peut être utilisé avec les opérateurs EQ, NE et IN.

Opérateurs¶

Les opérateurs disponibles sont répertoriés ci-dessous.

Tableau : Opérateurs de filtre

Paramètres de requête¶

L'API de requête d'inscription analytique vous permet de spécifier un ensemble de paramètres de requête.

Tableau : Paramètres de requête pour le point d'extrémité de la requête d'inscription

Formats de réponse¶

Le format de représentation de réponse par défaut est JSON. Les requêtes doivent utiliser la méthode HTTP GET. Les formats de réponse suivants sont pris en charge.

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

À titre d'exemple, pour obtenir une réponse au format Excel, vous pouvez utiliser une extension de fichier dans l'URL de la requête comme ceci :

/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

Le format JSON de réponse par défaut ressemblera à ceci :

{
  "headers": [
    {
      "name": "pi",
      "column": "Enrollment",
      "valueType": "TEXT",
      "hidden": false,
      "meta": true
    },
    {
      "name": "tei",
      "column": "Tracked entity instance",
      "valueType": "TEXT",
      "hidden": false,
      "meta": true
    },
    {
      "name": "enrollmentdate",
      "column": "Enrollment date",
      "valueType": "DATE",
      "hidden": false,
      "meta": true
    },
    {
      "name": "incidentdate",
      "column": "Incident date",
      "valueType": "DATE",
      "hidden": false,
      "meta": true
    },
    {
      "name": "storedby",
      "column": "Stored by",
      "valueType": "TEXT",
      "hidden": false,
      "meta": true
    },
    {
      "name": "lastupdated",
      "column": "Last Updated",
      "valueType": "DATE",
      "hidden": false,
      "meta": true
    },
    {
      "name": "storedby",
      "column": "Stored by",
      "valueType": "TEXT",
      "hidden": false,
      "meta": true
    },
    {
      "name": "createdbydisplayname",
      "column": "Created by (display name)",
      "valueType": "TEXT",
      "hidden": false,
      "meta": true
    },
    {
      "name": "lastupdatedbydisplayname",
      "column": "Last updated by (display name)",
      "valueType": "TEXT",
      "hidden": false,
      "meta": true
    },
    {
      "name": "geometry",
      "column": "Geometry",
      "valueType": "TEXT",
      "hidden": false,
      "meta": true
    },
    {
      "name": "longitude",
      "column": "Longitude",
      "valueType": "NUMBER",
      "hidden": false,
      "meta": true
    },
    {
      "name": "latitude",
      "column": "Latitude",
      "valueType": "NUMBER",
      "hidden": false,
      "meta": true
    },
    {
      "name": "ouname",
      "column": "Organisation unit name",
      "valueType": "TEXT",
      "hidden": false,
      "meta": true
    },
    {
      "name": "oucode",
      "column": "Organisation unit code",
      "valueType": "TEXT",
      "hidden": false,
      "meta": true
    },
    {
      "name": "ou",
      "column": "Organisation unit",
      "valueType": "TEXT",
      "hidden": false,
      "meta": true
    },
    {
      "name": "de0FEHSIoxh",
      "column": "WHOMCH Chronic conditions",
      "valueType": "BOOLEAN",
      "hidden": false,
      "meta": true
    },
    {
      "name": "sWoqcoByYmD",
      "column": "WHOMCH Smoking",
      "valueType": "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
}

La section en-têtes de la réponse décrit le contenu du résultat de la requête. L'identifiant unique de l'inscription, l'identifiant de l'instance d'entité suivie, la date de l'inscription, le nom de l'incident, la géométrie, la latitude, la longitude, le nom et le code de l'unité d'organisation apparaissent en tant que premières dimensions dans la réponse et seront toujours présents. Viennent ensuite les éléments de données, les attributs d'entité suivie qui ont été définis comme dimensions dans la demande ; il s'agit dans ce cas précis des dimensions d'éléments de données "WHOMCH maladies chroniques" et "WHOMCH fumeuses". L'identifiant de l'élément de dimension se trouve dans la propriété "nom" et une description lisible de la dimension dans la propriété "colonne" de la section d'en-têtes.

La section metaData, objet ou (unité d'organisation), contient les identifiants de toutes les unités d'organisation présentes dans la réponse, mis en correspondance avec une chaîne qui représente la hiérarchie. Cette chaîne hiérarchique énumère les identifiants des ascendants de l'unité d'organisation en commençant par la racine. L'objet noms contient les identifiants de tous les éléments de la réponse mis en correspondance avec leurs noms.

La section lignes contient les inscriptions produites par la requête. Chaque ligne représente exactement un inscription.

Analyse des relations entre les TEI et les indicateurs de programme¶

L'API d'analyse des inscriptions sans agrégation permet également de relier les indicateurs de programme aux types de relations, afin d'afficher le résultat du calcul d'un indicateur de programme spécifique, appliqué aux entités liées à l'instance d'entité suivie répertoriée.

Pour que la relation Indicateur de programme & Type de relation fonctionne, il faudra ajouter à l'API /api/analytics/enrollments/query, une nouvelle dimension qui contient les UID du type de relation et l'Indicateur de programme choisis :

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

Par exemple, pour extraire une liste d'inscriptions du programme "WHO RMNCH Tracker" pour janvier 2019 et afficher le nombre de cas de paludisme liés à cette inscription par le type de relation "Cas de paludisme lié à une personne", vous pouvez utiliser la requête suivante :

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

L'API permet d'utiliser des indicateurs de programme qui ne sont pas associés au programme "principal" (c'est-à-dire le programme dont l'ID est spécifié après /query/).

Tracked entity analytics¶

L'API d'analyse des entités suivies (ES) permet d'interroger les ES avec leurs données d'inscription et d'événement saisies dans DHIS2. Cette ressource permet d'extraire des données sur les ES, les inscriptions, les événements et les éléments de données dans plusieurs programmes, pour un type d'entité suivie donné.

Dimensions and items¶

Les dimensions des instances d'entités suivies comprennent les attributs de programme (attributs ES), les éléments de données, les unités d'organisation et différents types de périodes. La requête analytique renvoie simplement les ES correspondant à un ensemble de critères. Elle n'effectue aucune agrégation.

Tableau : Dimensions de l'ES

Décalage¶

Les dimensions qui font référence à des éléments dans des événements répétables peuvent inclure un décalage facultatif. Le décalage est utilisé pour spécifier la répétition de l'événement à utiliser. L'ordre des répétitions est basé sur la date de l'événement, l'événement le plus récent étant la dernière répétition. Le décalage est une valeur entière, où 0 correspond à la dernière répétition, -1 à l'avant-dernière, et ainsi de suite. Les valeurs positives font référence à la première (plus ancienne) répétition, à la deuxième répétition, et ainsi de suite. Le décalage est placé entre crochets [ ].

Exemple:

IpHINAT79UW.ZzYYXq4fJie.GQY2lXrypjO -- renvoie à la dernière répétition
IpHINAT79UW.ZzYYXq4fJie[-1].GQY2lXrypjO -- renvoie à l'avant-dernière répétition
IpHINAT79UW.ZzYYXq4fJie[2].GQY2lXrypjO -- renvoie à la deuxième répétition

Analyse des requêtes d'entités suivies (ES)¶

Le endpoint analytics/trackedEntities/query fournit des requêtes pour les ES saisies, permettant ainsi d'interroger et de filtrer les informations relatives aux ES, ainsi qu'à leurs inscriptions et événements respectifs. Il n'effectue aucune agrégation.

/api/41/analytics/trackedEntities/query

Vous pouvez spécifier un nombre quelconque de dimensions et de filtres dans une requête. Les identifiants des éléments de dimension peuvent faire référence à tout élément de données dans les étapes du programme, les attributs du programme, les attributs des entités suivies, les périodes fixes et relatives et les unités d'organisation. Les dimensions peuvent éventuellement être associées à un opérateur de requête et à un filtre. Les requêtes d'ES doivent être présentées dans le format décrit ci-dessous.

/api/41/analytics/trackedEntities/query/<tracked-entity-type-id>?dimension=ou:<ou-id>;<ou-id>&
    dimension=<item-id>&dimension=<item-id>:<operator>:<filter>

Par exemple, pour extraire les ES de type Personne des programmes "Enfant" et "Soins prénatals", où le "Prénom" est "Jacques" :

/api/41/analytics/trackedEntities/query/nEenWmSyUEp?program=IpHINAT79UW,WSGAb5XwJ3Y&dimension=IpHINAT79UW.w75KJ2mc4zz:eq:James

La pagination peut être appliquée à la requête en spécifiant les paramètres de numéro de page et de taille de page. Si le numéro de page est spécifié mais que la taille de la page ne l'est pas, la taille de page 50 sera utilisée. Si la taille de la page est spécifiée mais que le numéro de page ne l'est pas, le numéro de page 1 sera utilisé. Pour obtenir la deuxième page de la réponse avec une taille de page de 10, vous pouvez utiliser une requête comme celle-ci :

/api/41/analytics/trackedEntities/query/nEenWmSyUEp?program=IpHINAT79UW,WSGAb5XwJ3Y&dimension=IpHINAT79UW.w75KJ2mc4zz:eq:James
    &pageSize=10&page=2

Filtrage¶

Les filtres peuvent être appliqués aux éléments de données, aux attributs des entités suivies et aux identifiants des entités suivies. Le filtrage est effectué au moyen d'un paramètre de requête au format suivant :

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

Par exemple, vous pouvez filtrer l'élément de données "Poids du nourrisson (g)" du programme "Programme pour l'enfant" et de l'étape du programme "Bébé postnatal" en recherchant des valeurs supérieures à 2000 et inférieures à 4000. Le filtre est défini comme suit :

&dimension=IpHINAT79UW.ZzYYXq4fJie.GQY2lXrypjO:GT:2000&dimension=IpHINAT79UW.ZzYYXq4fJie.GQY2lXrypjO:LT:4000

Périodes¶

Contrairement aux endpoints d'inscription et de requête d'événement, l'endpoint de l'ES prend en charge plusieurs méthodes de spécification de la période à laquelle les données appartiennent. Elles sont basées sur différents paramètres date, comme indiqué ci-dessous :

Certaines périodes, mentionnées ci-dessus, peuvent être appliquées aux entités suivies, aux inscriptions ou aux événements, selon la manière dont elles sont exprimées.

Exemples :

• filtrer les ES qui ont été mis à jour au cours de l'année dernière :

lastUpdated=LAST_YEAR

• filtrer les ES dont la dernière inscription au programme "Programme pour enfants" a été mise à jour au cours de l'année dernière :

lastUpdated=IpHINAT79UW.LAST_YEAR

• filtrer les ES dont le dernier événement dans l'étape du programme " Bébé Postnatal ", dans la dernière inscription dans le programme " Programme Enfant " a été mis à jour au cours de l'année dernière :

lastUpdated=IpHINAT79UW.ZzYYXq4fJie.LAST_YEAR

• filtrer les ES dont la dernière inscription au "Programme pour enfants" a eu lieu au cours de l'année dernière :

enrollmentDate=IpHINAT79UW.LAST_YEAR

Request query parameters¶

L'API de requête analytique de l'ES prend en charge une série de paramètres de requête.

Tableau : Paramètres de requête pour le endpoint de l'ES

Dimensions¶

Vous pouvez extraire facilement les dimensions de données à partir de cinq ressources :

• Dimensions de données de la requête d'événement/analytics/events/query/dimensions
• Dimensions de données agrégées d'événement /analytics/events/aggregate/dimensions
• Dimensions de données de la requête d'inscription /analytics/enrollments/query/dimensions
• Dimensions de données agrégées d'inscription /analytics/enrollments/aggregate/dimensions
• Dimensions de données de la requête sur les entités suivies) /analytics/teis/query/dimensions

Les ressources mentionnées ci-dessus utilisent tous le paramètre de requête suivant :

Filtres de dimension¶

Les points d'extrémité des dimensions permettent de filtrer la sortie afin que la réponse ne porte que sur les éléments recherchés. Les filtres sont au format filter=field:op:value&filter=field:op:value&...&filter=field:op:value.

Les valeurs de champ prises en charge sont les suivantes :

• id/uid - identifiant de la dimension
• code - code de la dimension
• valueType - type de valeur de la dimension
• name - le nom de la dimension
• dimensionType - le type de dimension
  • DATA_ELEMENT
  • PROGRAM_INDICATOR
  • PROGRAM_ATTRIBUTE
  • CATEGORY
  • CATEGORY_OPTION_GROUP_SET (ensemble de groupes d'options de catégorie)
• displayName - nom d'affichage de la dimension
• displayShortName - nom d'affichage court pour la dimension

Les valeurs op prises en charge sont :

• startsWith - le champ commence par
• !startsWith - le champ ne commence pas par
• endsWith - le champ se termine par
• !endsWith - le champ ne se termine pas par-
• eq - égal
• ieq - équivaut à ignorer le cas
• ne - pas égal
• like - contient
• !like - ne contient pas
• ilike - contient des cas ignorés
• !ilike - ne contient pas des cas ignorés

Dimensions analytiques des événements¶

Dimensions analytiques des requêtes d'événement¶

La ressource /analytics/events/query/dimensions?programId={programId}&programStageId={programStageId} accepte :

• un programme tracker
• une étape de programme tracker
• le proramme et l'étape du programme

La combinaison du programme et de l'étape du programme est soumise à des contraintes :

• Si seul le programme est spécifié, la ressource renvoie les dimensions des données pour chaque étape de programme fourni.
• Si seul l'étape de programme est spécifié, la ressource renvoie les dimensions des données pour l'étape de programme fournie
• Si les deux éléments programme et étape de programme sont spécifiés, la ressource renvoie les dimensions des données pour létape de programme fournie si elle appartient au programme fourni. Sinon, elle renvoie une erreur.

les dimensions des données renvoyées sont les suivantes :

• Indicateurs de programme associés au programme (dérivés de l'ID de l'étape de programme)
• Éléments de données des types pris en charge dans l'étape de programme
• attributs d'entités suivies des types pris en charge associés au programme (dérivés de l'ID de l'étape de programme)
• Catégories dans la combinaison de catégories associée au programme (dérivés de l'ID de l'étape de programme)
• Ensembles de groupes d'options de catégorie de type ATTRIBUT

Tous les types de valeurs pour les éléments de données et les attributs d'entité suivie sont considérés comme des types pris en charge, à l'exception de IMAGE, FILE_RESOURCE et TRACKER_ASSOCIATE.

Dimensions agrégées d'événement¶

La ressource /analytics/events/aggregate/dimensions?programStageId=... accepte un paramètre obligatoire programStageId et renvoie les dimensions de données suivantes :

• Éléments de données des types pris en charge dans l'étape de programme
• attributs d'entités suivies des types pris en charge associés au programme (dérivés de l'ID de l'étape de programme)
• Catégories dans la combinaison de catégories associée au programme (dérivés de l'ID de l'étape de programme)
• Ensembles de groupes d'options de catégorie de type ATTRIBUT associés au programme (dérivés de l'ID de l'étape de programme)

Les éléments de données et les attributs d'entité suivie sont considérés comme des types pris en charge si leur type de valeur est l'un des suivants :

• NOMBRE
• INTERVALLE_UNITAIRE
• POURCENTAGE
• ENTIER
• ENTIER_POSITIF
• ENTIER_NÉGATIF
• ENTIER_ZÉRO_OU_POSITIF
• BOOLÉEN
• TRUE_ONLY (vrai uniquement)

Dimensions analytiques des inscriptions¶

Dimensions analytiques des requêtes d'inscription¶

La ressource /analytics/enrollments/query/dimensions?programId=... accepte un identifiant obligatoire d'un programme Tracker et renvoie les dimensions de données suivantes :

• Indicateurs de programme associés au programme
• Éléments de données des types pris en charge dans le programme, avec une étape de programme pour chaque élément de données
• Attributs d'entité suivie des types pris en charge associés au programme qui ne sont pas confidentiels

Tous les types de valeurs pour les éléments de données et les attributs d'entité suivie sont considérés comme des types pris en charge, à l'exception de IMAGE, FILE_RESOURCE et TRACKER_ASSOCIATE.

Dimensions agrégées d'inscription¶

La ressource /analytics/enrollments/aggregate/dimensions?programId=... accepte un identifiant obligatoire d'un programme Tracker, qui fait référence à un programme avec inscription, et renvoie les dimensions de données suivantes :

• Éléments de données des types pris en charge dans le programme, avec une étape de programme pour chaque élément de données
• Attributs d'entité suivie des types pris en charge associés au programme qui ne sont pas confidentiels

Les éléments de données et les attributs d'entité suivie sont considérés comme des types pris en charge si leur type de valeur est l'un des suivants :

• NOMBRE
• INTERVALLE_UNITAIRE
• POURCENTAGE
• ENTIER
• ENTIER_POSITIF
• ENTIER_NÉGATIF
• ENTIER_ZÉRO_OU_POSITIF
• BOOLÉEN
• TRUE_ONLY (vrai uniquement)

Dimensions analytiques des entités suivies¶

dimensions analytiques des requêtes d'entité suivie{ #webapi_teis_query_analytics_dimensions }¶

La ressource /analytics/teis/query/dimensions?trackedEntityType=TET accepte un identifiant obligatoire d'un type d'entité suivie TET et renvoie les dimensions de données suivantes :

pour chaque programme P associé à une instance d'entité suivie de type TET : - Indicateurs de programme associés au P - Éléments de données des types pris en charge dans le P, avec une étape de programme pour chaque élément de données - Attributs d'entité suivie des types pris en charge associés au programme qui ne sont pas confidentiels - attributs de programme du P

Tous les types de valeurs pour les éléments de données et les attributs d'entité suivie sont considérés comme des types pris en charge, à l'exception de IMAGE, FILE_RESOURCE et TRACKER_ASSOCIATE.

Exemple de requête et de réponse¶

GET /api/analytics/teis/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)"
    }
  ]
}

Analyse des unités d'organisation¶

L'API d'analyse des unités d'organisation fournit des statistiques sur les unités d'organisation classées par ensembles de groupes d'unités d'organisation, c'est-à-dire le nombre d'unités d'organisation dans chaque groupe au sein des ensembles de groupes d'unités d'organisation.

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

L'API requiert au moins une unité d'organisation et au moins un ensemble de groupes d'unités d'organisation. Plusieurs unités d'organisation et ensembles de groupes peuvent être fournis, séparés par un point-virgule.

Paramètres de requête{ #request-query-parameters }¶

La ressource analytique des unités d'organisation vous permet de spécifier un ensemble de paramètres de requête :

Tableau : Paramètres de requête analytique pour les unités d'organisation

La réponse contiendra une colonne pour l'unité d'organisation mère, des colonnes pour chaque groupe d'unités d'organisation faisant partie de la requête et une colonne pour le nombre d'unités d'organisation. Les statistiques comprennent le nombre d'unités d'organisation qui se trouvent en dessous des unités d'organisation spécifiées dans la requête. La réponse contient une section 'métadonnées' qui spécifie le nom de chaque unité d'organisation et de chaque groupe d'unités d'organisation qui font partie de la réponse. Elles sont référencées par leurs identifiants.

La réponse par défaut comporte une seule colonne count. Elle peut être présentée dans un tableau dans lequel au moins un groupe d'unités d'organisation est spécifié à l'aide du paramètre de requête columns.

Formats de réponse¶

Le point d'extrémité analytique des unités d'organisation rend en charge les formats de représentation suivants :

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

Exemples¶

Pour obtenir des analyses d'unité d'organisation pour une unité d'organisation et un ensemble de groupes d'unités d'organisation, utilisez ce qui suit :

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

Pour obtenir des données analytiques d'unité d'organisation pour deux unités d'organisation et deux ensembles de groupes d'unités d'organisation, utilisez ce qui suit :

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

Pour obtenir des données analytiques d'unité d'organisation dans un tableau avec un ensemble de groupes présenté dans des colonnes, utilisez ceci :

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

Contraintes et validation¶

Les éventuelles erreurs de validation spécifiques à l'API d'analyse des unités d'organisation sont décrites dans le tableau ci-dessous. Certaines erreurs spécifiées pour l'API d'analyse agrégée sont également concernées.

Rapport sur l'ensemble de données¶

Les rapports sur les ensembles de données peuvent être générés avec l'API Web, à l'aide de la ressource /dataSetReport. Cette ressource génère des rapports sur les ensembles de données et renvoie le résultat dans un un tableau HTML.

/api/dataSetReport

Paramètres de requête{ #request-query-parameters }¶

La requête prend en charge les paramètres suivants :

Tableau : Paramètres de la requête du rapport d'ensemble de données

La ressource du rapport sur les ensembles de données accepte uniquement les requêtes GET. Le contenu de la réponse est de type application/json et les données sont renvoyées dans une grille. Ce point d'extrémité fonctionne pour tous les types d'ensemble de données, notamment les formulaires par défaut, les formulaires à sections et les formulaires personnalisés.

Voici un exemple de requête d'extraction d'un rapport pour un ensemble de données mensuel et une unité d'organisation pour le mois d'octobre 2018 :

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

Voici un exemple de requête d'extraction d'un rapport pour un ensemble de données mensuel et une unité d'organisation pour octobre, novembre et décembre 2018 :

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

Pour obtenir un rapport sur un ensemble de données avec un filtre, vous pouvez utiliser le paramètre filter. Dans ce cas, le filtre se base sur un ensemble de groupes d'unités d'organisation et deux groupes d'unités d'organisation :

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

Formats de réponse¶

Le point d'extrémité du rapport sur l'ensemble de données prend en charge les formats de sortie suivants. Vous pouvez récupérer un point d'extrémité spécifique en utilisant l'extension du fichier ou l'en-tête HTTP Accept.

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

Formulaires personnalisés¶

Un point d'extrémité spécifique est disponible pour les ensembles de données avec des formulaires HTML personnalisés. Ce point d'extrémité renvoie le contenu du formulaire HTML avec le type de contenu text/html et les données y sont insérées. Vous pouvez également utiliser le point d'extrémité du rapport général sur les ensembles de données pour les ensembles de données avec des formulaires personnalisés. Cependant, ce point d'extrémité renverra le rapport au format JSON dans une grille. Ce point d'extrémité ne fonctionne que pour les ensembles de données avec des formulaires HTML personnalisés.

GET /api/dataSetReport/custom

La syntaxe de ce point d'extrémité est par ailleurs la même que celle du point d'extrémité du rapport général sur les ensembles de données. Pour récupérer un rapport HTML personnalisé sur un ensemble de données, vous pouvez effectuer la requête suivante :

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

Analyse push¶

L'API d'analyse push comprend des points d'extrémité qui permettent la prévisualisation d'un rapport d'analyse push par l'utilisateur connecté et le déclenchement manuel de la génération et de l'envoi de rapports d'analyse push par le système, en plus des opérations CRUD normales. Lorsque vous utilisez les points d'extrémité de création et de mise à jour pour l'analyse push, celle-ci est programmée pour s'exécuter selon les propriétés de l'analyse push. De même, lorsque vous supprimez ou mettez à jour une analyse push pour la désactiver, la tâche ne pourra plus être exécutée à l'avenir.

Pour obtenir l'aperçu d'une analyse push existante en HTML, vous pouvez effectuer une requête GET au point d'extrémité suivant :

/api/pushAnalysis/<id>/render

Pour déclencher manuellement une tâche d'analyse push, vous pouvez envoyer une requête POST au point d'extrémité suivant :

/api/pushAnalysis/<id>/run

Une analyse push comprend les propriétés suivantes, dont certaines sont nécessaires pour l'exécution automatique des tâches d'analyse push :

Tableau : Propriétés de l'analyse push

Analyse de l'utilisation des données¶

L'API d'analyse de l'utilisation vous permet d'accéder à des informations sur la manière dont les gens utilisent DHIS2 sur la base d'une analyse de données. Lorsque les utilisateurs accèdent aux favoris, un événement est enregistré. L'événement se compose du nom de l'utilisateur, de l'UID du favori, de la date de l'événement et du type d'événement. Les différents types d'événements sont répertoriés dans le tableau.

/api/dataStatistics

L'API d'analyse de l'utilisation vous permet de récupérer des instantanés agrégés sur l'analyse de l'utilisation, en fonction d'intervalles de temps donnés. L'API capture les visualisations des utilisateurs (par exemple le nombre de fois qu'un graphique ou un tableau croisé dynamique a été visualisé par un utilisateur) et les favoris d'analyse enregistrés (par exemple les graphiques et les tableaux croisés dynamiques favoris). DHIS2 capture des instantanés nocturnes qui sont ensuite agrégés à la demande.

Paramètres de requête{ #webapi_usage_analytics_request_query_parameters }¶

L'API d'analyse de l'utilisation (statistiques de données) prend en charge deux opérations :

• POST: crée un événement de visualisation

• GET: récupère les statistiques agrégées

Création des événements de visualisation (POST)¶

L'API d'analyse de l'utilisation vous permet de créer des visualisations d'événement. Le paramètre dataStatisticsEventType (type d'événement des statistiques de données) décrit le type de l'élément visualisé. Le paramètre de favori indique l'identifiant du favori concerné.

L'URL qui crée une nouvelle visualisation d'événement des graphiques :

POST /api/dataStatistics?eventType=CHART_VIEW&favorite=LW0O27b7TdD

Une opération de sauvegarde réussie renvoie un code de statut HTTP "201". Le tableau ci-dessous présente les types d'événements pris en charge.

Tableau : Types d'événements pris en charge

Récupération des rapports agrégés d'analyse de l'utilisation (GET)¶

L'API d'analyse de l'utilisation (statistiques de données) vous permet de spécifier certains paramètres de requête lorsque vous demandez un rapport agrégé.

Tableau : Paramètres de requête pour l'analyse agrégée de l'utilisation (statistiques de données)

Les paramètres 'date de début' et 'date de fin' spécifient la période pour laquelle les instantanés doivent être utilisés dans l'agrégation. Vous devez mettre les dates au format indiqué ci-dessus. Si aucun instantané n'est sauvegardé au cours de la période spécifiée, une liste vide est renvoyée. Le paramètre appelé 'intervalle' spécifie le type d'agrégation qui sera effectué.

Requête API qui crée une agrégation mensuelle :

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

Récupération des favoris¶

L'API d'analyse de l'utilisation vous permet de récupérer les principaux favoris utilisés dans DHIS2, et par utilisateur.

Tableau : Paramètres requête pour les principaux favoris

La requête API peut être utilisée sans nom d'utilisateur. Dans ce cas, elle trouvera les principaux favoris de tout le système.

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

Si le nom d'utilisateur est spécifié, la réponse ne contiendra que les principaux favoris de cet utilisateur.

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

Format de la réponse¶

Vous pouvez renvoyer les données agrégées dans une réponse d'analyse d'utilisation dans différents formats de représentation. Le format par défaut est JSON. Les formats et types de contenu disponibles sont les suivants :

• json (application/json)

• xml (application/xml)

• html (texte/html)

Requête API qui demande une réponse d'analyse d'utilisation au format XML :

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

Pour obtenir une réponse d'analyse d'utilisation au format JSON :

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

La réponse JSON ressemble à ceci :

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

Notez que le nombre de activeUsers (utilisateurs actifs) indique le nombre d'utilisateurs distincts qui ont eu des événements au cours de la période de temps demandée. Le nombre de users (utilisateurs) représente le nombre total d'utilisateurs dans le système (à la fois activés et désactivés).

Récupération des statistiques pour un favori¶

Vous pouvez obtenir le nombre de visualisations pour un favori spécifique en utilisant la ressource favoris, où {favorite-id} (Id du favori) doit être remplacé par l'identifiant du favori en question :

/api/dataStatistics/favorites/{favorite-id}.json

La réponse contiendra le nombre de visualisations pour le favori en question et ressemblera à ceci :

{
  "views": 3
}

Éléments géospatiaux¶

La ressource geoFeatures vous permet d'extraire des informations géospatiales de DHIS2. Les éléments géospatiaux sont stockées avec les unités d'organisation. La syntaxe utilisée pour extraire ces éléments est identique à la celle utilisée pour la dimension d'unité d'organisation de la ressource analytique. Nous vous recommandons de vous renseigner sur la ressource de l'API analytique avant de poursuivre la lecture de cette section. Vous devez utiliser le type de requête GET et seul le format de réponse JSON est pris en charge.

Par exemple, pour récupérer les éléments géospatiaux de toutes les unités d'organisation situées au niveau 3 de la hiérarchie des unités d'organisation, vous pouvez utiliser une requête GET avec l'URL suivante :

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

Pour récupérer les éléments géospatiaux des unités d'organisation à un niveau situé à l'intérieur d'une unité d'organisation (par exemple au niveau 2), vous pouvez utiliser l'URL suivante :

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

La valeur des coordonnées de la réponse peut être lue à partir de deux propriétés déterminées par le paramètre coordinateField (champ de coordonnées). - La propriété geometry de l'unité d'organisation : c'est le fonctionnement par défaut qui est appliqué lorsque le paramètre coordinateField n'est pas fourni. - L'attribut de l'unité d'organisation de type de valeur GeoJSON : l'API va utiliser le champ coordinateField={attributeId} fourni pour obtenir les coordonnées GeoJSON à partir de la valeur de cet attribut.

Par exemple, si vous voulez récupérer des éléments géospatiaux pour toutes les unités d'organisation au niveau 3 tel que mentionné plus haut, mais en obtenant les coordonnées à partir de l'attribut d'unité d'organisation tJqtSV4quLb, utilisez ceci :

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

La sémantique des propriétés de la réponse est décrite dans le tableau suivant :

Tableau : Réponse pour les éléments géospatiaux

GeoJSON¶

Pour exporter du GeoJSON, vous pouvez simplement ajouter .geosjon en tant qu'extension au point d'extrémité /api/organisationUnits, ou vous pouvez utiliser l'en-tête Accept avec application/json+geojson.

Deux paramètres sont pris en charge : level (1 par défaut) et parent (unités d'organisation racine par défaut). Les deux paramètres peuvent être ajoutés à plusieurs reprise. Quelques exemples :

Pour obtenir tous les éléments aux niveaux 2 et 4 :

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

Pour obtenir tous les éléments au niveau 3 avec une unité d'organisation limite :

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

Crochets pour tableaux analytiques¶

Les crochets de tableaux analytiques fournissent un mécanisme permettant d'appeler des scripts SQL au cours des différentes phases du processus de génération des tableaux analytiques. Ceci permet de personnaliser les données dans les tableaux de ressources et d'analyse, par exemple pour obtenir une logique spécifique pour les calculs et l'agrégation. Vous pouvez manipuler les crochets de tables analytiques à l'aide du point d'extrémité d'API suivant :

/api/analyticsTableHooks

L'API des crochets de tableaux analytiques prend en charge les opérations CRUD HTTP standard pour créer (POST), mettre à jour (PUT), récupérer (GET) et supprimer (DELETE) des entités.

Champs de crochets¶

Les crochets de tableaux analytiques comportent les champs suivants :

Tableau : Champs des crochets de tableaux analytiques

La phase ANALYTICS_TABLE_POPULATED a lieu après le remplissage du tableau analytique, mais avant la création des index et le remplacement du tableau temporaire par le tableau principale. Le script SQL va désormais faire référence au tableau analytique temporaire, par exemple analytics_temp, analytics_completeness_temp, analytics_event_temp_ebayegv0exc.

Ceci s'applique également à la phase RESOURCE_TABLE_POPULATED, qui a lieu après le remplissage du tableau de ressources, mais avant la création des index et le remplacement du tableau temporaire par le tableau principal. Le script SQL va désormais faire référence au tableau de ressources temporaire, par exemple _orgunitstructure_temp, _categorystructure_temp.

Vous ne devez définir qu'un seul champ entre resourceTableType et analyticsTableType. Vous le ferez en fonction de la phase définie.

Vous pouvez faire référence au tableau temporaire de la base de données qui correspond uniquement au type du tableau de crochets spécifié (les autres tableaux temporaires ne seront pas disponibles). Par exemple, si vous spécifiez ORG_UNIT_STRUCTURE comme type de tableau de ressources, vous ne pourrez faire référence qu'au tableau temporaire de la base de données _orgunitstructure_temp.

Le tableau suivant présente les combinaisons valables de phases, de types de tableaux et de tableaux temporaire.

Tableau : Phases, types de tableaux et tableaux temporaires

Création de crochets¶

You can create hooks with the Maintenance app or with the API.

Pour créer un crochet qui doit être exécuté après le remplissage des tableaux de ressources, vous pouvez effectuer la requête POST suivante en utilisant JSON comme type de contenu :

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

Pour créer un crochet qui doit être exécuté après le remplissage du tableau d'analyse des valeurs de données, vous pouvez effectuer la requête POST suivante en utilisant le format JSON :

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

Pour créer un crochet qui doit être exécuté après le remplissage des tableaux d'analyse d'événements, vous pouvez effectuer la requête POST suivante en utilisant le format JSON :

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

Conversion SVG¶

L'API Web fournit une ressource qui peut être utilisée pour convertir le contenu SVG dans des formats plus utilisés tels que PNG et PDF. Idéalement, cette conversion devrait avoir lieu côté client, mais toutes les technologies côté client ne sont pas en mesure d'effectuer cette tâche. Actuellement, les formats de sortie PNG et PDF sont pris en charge. Le contenu SVG lui-même doit être transmis avec un paramètre de requête svg, et un paramètre de requête facultatif filename peut être utilisé pour spécifier le nom de fichier de la pièce jointe à la réponse. Notez que l'extension du fichier doit être omise. Pour obtenir une réponse dans le format PNG, vous pouvez envoyer une requête POST à l'URL suivante avec pour type de contenu application/x-www-form-urlencoded. Ce processus est identique à la soumission d'un formulaire HTML classique.

api/svg.png

Pour obtenir la réponse dans le format PDF, vous pouvez envoyer une requête POST à l'URL suivante avec pour type de contenu application/x-www-form-urlencoded.

api/svg.pdf

Tableau : Paramètres de requête

Détection analytique des valeurs atypiques¶

L'API analytique de valeurs atypiques fournit des endpoints pour l'investigation de la qualité des données sur la base du score Z et du score Z modifié. Ces deux scores sont des mesures statistiques qui permettent d'analyser et d'interpréter les données dans le contexte des écarts par rapport à la valeur moyenne. Ils sont particulièrement utiles pour identifier les valeurs atypiques ou extrêmes dans un ensemble de données. L'API est mise en œuvre sous la forme d'un endpoint analytique unique :

• /api/analytics/outlierDetection

Requête¶

Paramètre de requête

Exemple de requête

GET api/analytics/outlierDetection?ds=BfMAe6Itzgt&ou=ImspTQPwCqd&startDate=2022-07-26&endDate=2022-10-26&algorithm=Z_SCORE&maxResults=30&orderBy=value&threshold=3.0&sortOrder=asc&outputIdScheme=code

Réponse¶

La réponse est fournie dans plusieurs formats de représentation. Le format par défaut est JSON. Les formats et types de contenu disponibles sont les suivants :

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

Exemple de réponse

{
  "headers":[
    {
      "name":"dx",
      "column":"Data",
      "valueType":"TEXT",
      "hidden":false,
      "meta":false
    },
    {
      "name":"dxname",
      "column":"Data name",
      "valueType":"TEXT",
      "hidden":false,
      "meta":false
    },
    {
      "name":"pe",
      "column":"Period",
      "valueType":"TEXT",
      "hidden":false,
      "meta":false
    },
    {
      "name":"pename",
      "column":"Period name",
      "valueType":"TEXT",
      "hidden":false,
      "meta":false
    },
    {
      "name":"ou",
      "column":"Organisation unit",
      "valueType":"TEXT",
      "hidden":false,
      "meta":false
    },
    {
      "name":"ouname",
      "column":"Organisation unit name",
      "valueType":"TEXT",
      "hidden":false,
      "meta":false
    },
    {
      "name":"ounamehierarchy",
      "column":"Organisation unit name hierarchy",
      "valueType":"TEXT",
      "hidden":false,
      "meta":false
    },
    {
      "name":"coc",
      "column":"Category option combo",
      "valueType":"TEXT",
      "hidden":false,
      "meta":false
    },
    {
      "name":"cocname",
      "column":"Category option combo name",
      "valueType":"TEXT",
      "hidden":false,
      "meta":false
    },
    {
      "name":"aoc",
      "column":"Attribute option combo",
      "valueType":"TEXT",
      "hidden":false,
      "meta":false
    },
    {
      "name":"aocname",
      "column":"Attribute option combo name",
      "valueType":"TEXT",
      "hidden":false,
      "meta":false
    },
    {
      "name":"value",
      "column":"Value",
      "valueType":"NUMBER",
      "hidden":false,
      "meta":false
    },
    {
      "name":"mean",
      "column":"Mean",
      "valueType":"NUMBER",
      "hidden":false,
      "meta":false
    },
    {
      "name":"stddev",
      "column":"Standard deviation",
      "valueType":"NUMBER",
      "hidden":false,
      "meta":false
    },
    {
      "name":"absdev",
      "column":"Absolute deviation",
      "valueType":"NUMBER",
      "hidden":false,
      "meta":false
    },
    {
      "name":"zscore",
      "column":"zScore",
      "valueType":"NUMBER",
      "hidden":false,
      "meta":false
    },
    {
      "name":"lowerbound",
      "column":"Lower boundary",
      "valueType":"NUMBER",
      "hidden":false,
      "meta":false
    },
    {
      "name":"upperbound",
      "column":"Upper boundary",
      "valueType":"NUMBER",
      "hidden":false,
      "meta":false
    }
  ],
  "metaData":{
    "maxResults":30,
    "count":3,
    "orderBy":"VALUE",
    "threshold":3.0,
    "algorithm":"Z_SCORE"
  },
  "rowContext":{

  },
  "width":18,
  "rows":[
    [
      "DE_22",
      "Q_Early breastfeeding (within 1 hr after delivery) at BCG",
      "202209",
      "September 2022",
      "OU_204860",
      "Sandaru CHC",
      "/Sierra Leone/Kailahun/Penguia/Sandaru CHC",
      "COC_292",
      "Fixed, <1y",
      "default",
      "default",
      "105.0",
      "18.3",
      "28.7",
      "86.7",
      "3.0",
      "-67.9",
      "104.4"
    ],
    [
      "DE_359706",
      "BCG doses given",
      "202208",
      "August 2022",
      "OU_595",
      "Ngalu CHC",
      "/Sierra Leone/Bo/Bargbe/Ngalu CHC",
      "COC_292",
      "Fixed, <1y",
      "default",
      "default",
      "220.0",
      "41.6",
      "57.4",
      "178.3",
      "3.1",
      "-130.7",
      "213.9"
    ],
    [
      "DE_35",
      "Yellow Fever doses given",
      "202209",
      "September 2022",
      "OU_1027",
      "Yemoh Town CHC",
      "/Sierra Leone/Bo/Kakua/Yemoh Town CHC",
      "COC_292",
      "Fixed, <1y",
      "default",
      "default",
      "466.0",
      "48.1",
      "114.2",
      "417.8",
      "3.6",
      "-294.6",
      "391.0"
    ]
  ],
  "headerWidth":18,
  "height":3
}

Les statistiques dans la réponse¶

Messages d'erreurs¶

All error messages are delivered with http status code 409.

The values in error messages are examples only.

Exemple de message d'erreur

{
  "httpStatus": "Conflict",
  "httpStatusCode": 409,
  "status": "ERROR",
  "message": "Start date and end date or relative period must be specified",
  "errorCode": "E2201"
}

Plan d'exécution des requêtes analytiques et coûts, y compris l'estimation du temps d'exécution¶

L'API analytique fournit des points d'extrémité permettant d'examiner les problèmes liés à la performance des requêtes. Il est implémenté dans tous les points d'extrémité d'analyse :

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

Exemple

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 will show the execution plan that the PostgreSQL planner generates for the supplied statement.

Le plan d'exécution indique comment le ou les tableau(x) référencé(s) dans l'instruction seront explorés : par un simple scan séquentiel, par un scan d'index, et si plusieurs tableaux sont référencés, quelles jointures seront utilisées pour rassembler les lignes requises à partir de chaque tableau d'entrée.

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

Tous les points d'entrée sont sécurisés par une autorisation. Le rôle F_PERFORM_ANALYTICS_EXPLAIN est requis.

Présentation de l'analyse¶

/api/analytics/explain

Présentation de l'analyse d'événements¶

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

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

Présentation de l'analyse d'inscriptions¶

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

Présentation de l'analyse des valeurs atypiques¶

/api/analytics/outlierDetection/explain