The enrollment analytics API lets you access aggregated event data and query enrollments with their event data captured in DHIS2. This resource lets you retrieve data for a program based on program stages and data elements - in addition to tracked entity attributes. When querying event data for a specific programstages within each enrollment, the data element values for each program stage will be returned as one row in the response from the api. If querying a data element in a program stage that is repeatable, the newest data element value will be used for that data element in the api reponse.
Enrollment dimensions include data elements, attributes, organisation units and periods. The query analytics resource will simply return enrollments matching a set of criteria and does not perform any aggregation.
| Dimension | Dimension id | Description |
|---|---|---|
| Data elements in program stages | <program stage id>.<data element id> |
Data element identifiers must include the program stage when querying data for enrollments. |
| Attributes | <id> | Attribute identifiers |
| Periods | pe | ISO periods and relative periods, see “date and period format” |
| Organisation units | ou | Organisation unit identifiers and keywords USER_ORGUNIT, USER_ORGUNIT_CHILDREN, USER_ORGUNIT_GRANDCHILDREN, LEVEL-<level> and OU_GROUP-<group-id> |
The analytics/enrollments/query resource lets you query for captured enrollments. This resource does not perform any aggregation, rather it lets you query and filter for information about enrollments.
/api/32/analytics/enrollments/queryYou can specify any number of dimensions and any number of filters in a query. Dimension item identifiers can refer to any of data elements in program stages, tracked entity attributes, fixed and relative periods and organisation units. Dimensions can optionally have a query operator and a filter. Enrollment queries should be on the format described below.
/api/32/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>For example, to retrieve enrollments in the from the “Antenatal care” program from January 2019, where the “First name” is picked up from attributes, “Chronic conditions” and “Smoking” data elements are included from the first program stage, and “Hemoglobin value” from the follou program stage - and only women that has “Cronic conditions” would be icluded, you can use the following query:
/api/32/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-31To retrieve enrollments in the from the “Antenatal care” program from last month(relative to the point in time the query is executed), where the “Chronic conditions” and “Smoking” data elements are included from the first program stage, and “Hemoglobin value” from the folloup program stage - only including smoking women with hemoglobin less than 20:
api/32/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_MONTHSorting can be applied to the query for the enrollment and incident dates of the enrollment:
/api/32/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=DESCENDANTSPaging can be applied to the query by specifying the page number and the page size parameters. If page number is specified but page size is not, a page size of 50 will be used. If page size is specified but page number is not, a page number of 1 will be used. To get the second page of the response with a page size of 10 you can use a query like this:
api/32/analytics/enrollments/query/WSGAb5XwJ3Y.json?dimension=ou:ImspTQPwCqd
&dimension=WZbXY0S00lP.de0FEHSIoxh&dimension=w75KJ2mc4zz&dimension=pe:LAST_MONTH
&dimension=WZbXY0S00lP.sWoqcoByYmD&pageSize=10&page=2Filters can be applied to data elements, person attributes and person identifiers. The filtering is done through the query parameter value on the following format:
&dimension=<item-id>:<operator>:<filter-value>As an example, you can filter the “Weight” data element for values greater than 2000 and lower than 4000 like this:
&dimension=WZbXY0S00lP.UXz7xuGCEhU:GT:2000&dimension=WZbXY0S00lP.UXz7xuGCEhU:LT:4000You can filter the “Age” attribute for multiple, specific ages using the IN operator like this:
&dimension=qrur9Dvnyt5:IN:18;19;20You can specify multiple filters for a given item by repeating the operator and filter components, all separated with semi-colons:
&dimension=qrur9Dvnyt5:GT:5:LT:15The available operators are listed below.
| Operator | Description |
|---|---|
| EQ | Equal to |
| GT | Greater than |
| GE | Greater than or equal to |
| LT | Less than |
| LE | Less than or equal to |
| NE | Not equal to |
| LIKE | Like (free text match) |
| IN | Equal to one of multiple values separated by “;” |
The analytics enrollment query API let you specify a range of query parameters.
| Query parameter | Required | Description | Options (default first) |
|---|---|---|---|
| program | Yes | Program identifier. | Any program identifier |
| startDate | No | Start date for enrollments. | Date in yyyy-MM-dd format |
| endDate | No | End date for enrollments. | Date in yyyy-MM-dd format |
| dimension | Yes | Dimension identifier including data elements, attributes, program indicators, periods, organisation units and organisation unit group sets. Parameter can be repeated any number of times. Item filters can be applied to a dimension on the format <item-id>:<operator>:<filter>. Filter values are case-insensitive. | Operators can be EQ | GT | GE | LT | LE | NE | LIKE | IN |
| filter | No | Dimension identifier including data elements, attributes, periods, organisation units and organisation unit group sets. Parameter can be repeated any number of times. Item filters can be applied to a dimension on the format <item-id>:<operator>:<filter>. Filter values are case-insensitive. | |
| programStatus | No | Specify enrollment status of enrollments to include. | ACTIVE | COMPLETED | CANCELLED |
| relativePeriodDate | string | No | Date identifier e.g: “2016-01-01”. Overrides the start date of the relative period |
| ouMode | No | The mode of selecting organisation units. Default is DESCENDANTS, meaning all sub units in the hierarchy. CHILDREN refers to immediate children in the hierarchy; SELECTED refers to the selected organisation units only. | DESCENDANTS, CHILDREN, SELECTED |
| asc | No | Dimensions to be sorted ascending, can reference enrollment date, incident date, org unit name and code. | ENROLLMENTDATE | INCIDENTDATE| OUNAME | OUCODE |
| desc | No | Dimensions to be sorted descending, can reference enrollment date, incident date, org unit name and code. | ENROLLMENTDATE | INCIDENTDATE| OUNAME | OUCODE |
| hierarchyMeta | No | Include names of organisation unit ancestors and hierarchy paths of organisation units in the metadata. | false | true |
| coordinatesOnly | No | Whether to only return enrollments which have coordinates. | false | true |
| page | No | The page number. Default page is 1. | Numeric positive value |
| pageSize | No | The page size. Default size is 50 items per page. | Numeric zero or positive value |
The default response representation format is JSON. The requests must be using the HTTP GET method. The following response formats are supported.
As an example, to get a response in Excel format you can use a file extension in the request URL like this:
/api/32/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=DESCENDANTSThe default response JSON format will look similar to this:
{
"headers": [
{
"name": "pi",
"column": "Enrollment",
"valueType": "TEXT",
"type": "java.lang.String",
"hidden": false,
"meta": true
},
{
"name": "tei",
"column": "Tracked entity instance",
"valueType": "TEXT",
"type": "java.lang.String",
"hidden": false,
"meta": true
},
{
"name": "enrollmentdate",
"column": "Enrollment date",
"valueType": "DATE",
"type": "java.util.Date",
"hidden": false,
"meta": true
},
{
"name": "incidentdate",
"column": "Incident date",
"valueType": "DATE",
"type": "java.util.Date",
"hidden": false,
"meta": true
},
{
"name": "geometry",
"column": "Geometry",
"valueType": "TEXT",
"type": "java.lang.String",
"hidden": false,
"meta": true
},
{
"name": "longitude",
"column": "Longitude",
"valueType": "NUMBER",
"type": "java.lang.Double",
"hidden": false,
"meta": true
},
{
"name": "latitude",
"column": "Latitude",
"valueType": "NUMBER",
"type": "java.lang.Double",
"hidden": false,
"meta": true
},
{
"name": "ouname",
"column": "Organisation unit name",
"valueType": "TEXT",
"type": "java.lang.String",
"hidden": false,
"meta": true
},
{
"name": "oucode",
"column": "Organisation unit code",
"valueType": "TEXT",
"type": "java.lang.String",
"hidden": false,
"meta": true
},
{
"name": "ou",
"column": "Organisation unit",
"valueType": "TEXT",
"type": "java.lang.String",
"hidden": false,
"meta": true
},
{
"name": "de0FEHSIoxh",
"column": "WHOMCH Chronic conditions",
"valueType": "BOOLEAN",
"type": "java.lang.Boolean",
"hidden": false,
"meta": true
},
{
"name": "sWoqcoByYmD",
"column": "WHOMCH Smoking",
"valueType": "BOOLEAN",
"type": "java.lang.Boolean",
"hidden": false,
"meta": true
}
],
"metaData": {
"pager": {
"page": 2,
"total": 163,
"pageSize": 4,
"pageCount": 41
},
"items": {
"ImspTQPwCqd": {
"name": "Sierra Leone"
},
"PFDfvmGpsR3": {
"name": "Care at birth"
},
"bbKtnxRZKEP": {
"name": "Postpartum care visit"
},
"ou": {
"name": "Organisation unit"
},
"PUZaKR0Jh2k": {
"name": "Previous deliveries"
},
"edqlbukwRfQ": {
"name": "Antenatal care visit"
},
"WZbXY0S00lP": {
"name": "First antenatal care visit"
},
"sWoqcoByYmD": {
"name": "WHOMCH Smoking"
},
"WSGAb5XwJ3Y": {
"name": "WHO RMNCH Tracker"
},
"de0FEHSIoxh": {
"name": "WHOMCH Chronic conditions"
}
},
"dimensions": {
"pe": [],
"ou": [
"ImspTQPwCqd"
],
"sWoqcoByYmD": [],
"de0FEHSIoxh": []
}
},
"width": 12,
"rows": [
[
"A0cP533hIQv",
"to8G9jAprnx",
"2019-02-02 12:05:00.0",
"2019-02-02 12:05:00.0",
"",
"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",
"",
"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",
"",
"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",
"",
"0.0",
"0.0",
"Korbu MCHP",
"OU_678893",
"m73lWmo5BDG",
"",
"1"
]
],
"height": 4
}The headers section of the response describes the content of the query result. The enrollment unique identifier, the tracked entity instance identifier, the enrollment date, the incident date, geometry, latitude, logitude, the organisation unit name and the organisation unit code appear as the first dimensions in the response and will always be present. Next comes the data elements,and tracked entity attributes which were specified as dimensions in the request, in this case the “WHOMCH Chronic conditions” and “WHOMCH smoking” data element dimensions. The header section contains the identifier of the dimension item in the “name” property and a readable dimension description in the “column” property.
The metaData section, ou object contains the identifiers of all organisation units present in the response mapped to a string representing the hierarchy. This hierarchy string lists the identifiers of the ancestors (parents) of the organisation unit starting from the root. The names object contains the identifiers of all items in the response mapped to their names.
The rows section contains the enrollments produced by the query. Each row represents exactly one enrollment.