1.36 Interpretations

For resources related to data analysis in DHIS 2, such as pivot tables, charts, maps, event reports and event charts, you can write and share data interpretations. An interpretation can be a comment, question, observation or interpretation about a data report or visualization.

/api/26/interpretations

1.36.1 Reading interpretations

To read interpretations we will interact with the /api/26/interpretations resource. A typical GET request using field filtering can look like this:

GET /api/26/interpretations?fields=*,comments[id,text,user]

The output in JSON response format could look like below (additional fields omitted for brevity):

{
    "interpretations": [{
        "id": "XSHiFlHAhhh",
        "created": "2013-05-30T10:24:06.181+0000",
        "text": "Data looks suspicious, could be a data entry mistake.",
        "type": "REPORT_TABLE",
        "likes": 2,
        "user": {
          "id": "uk7diLujYif"
        },
        "reportTable": {
          "id": "LcSxnfeBxyi"
        }
    }, {
        "id": "kr4AnZmYL43",
        "created": "2013-05-29T14:47:13.081+0000",
        "text": "Delivery rates in Bo looks high.",
        "type": "CHART",
        "likes": 3,
        "user": {
          "id": "uk7diLujYif"
        },
        "chart": {
          "id": "HDEDqV3yv3H"
        },
        "comments": [{
            "id": "iB4Etq8yTE6",
            "text": "This report indicates a surge",
            "user": {
                "id": "B4XIfwOcGyI"
            }, {
            "id": "iB4Etq8yTE6",
            "text": "Likely caused by heavy rainfall",
            "user": {
                "id": "B4XIfwOcGyI"
            }]
        }
    }]
}
Interpretation fields
Field Description
id The interpretation identifier.
created The time of when the interpretation was created.
type The type of analytical object being interpreted. Valid options: REPORT_TABLE, CHART, MAP, EVENT_REPORT, EVENT_CHART, DATASET_REPORT.
user Association to the user creating the interpretation.
reportTable Association to the report table if type is REPORT_TABLE.
chart Association to the chart if type is CHART.
map Association to the map if type is MAP.
eventReport Association to the event report is type is EVENT_REPORT.
eventChart Association to the event chart if type is EVENT_CHART.
dataSet Association to the data set if type is DATASET_REPORT.
comments Array of comments for the interpretation. The text field holds the actual comment.

For all analytical objects you can append /data to the URL to retrieve the data associated with the resource (as apposed to the metadata). As an example, by following the map link and appending /data one can retrieve a PNG (image) representation of the thematic map through the following URL:

https://play.dhis2.org/demo/api/26/maps/bhmHJ4ZCdCd/data

1.36.2 Writing interpretations

When writing interpretations you will supply the interpretation text as the request body using a POST request with content type “text/plain”. The URL pattern looks like the below, where {object-type} refers to the type of the object being interpreted, and {object-id} refers to the identifier of the obejct being interpreted.

/api/26/interpretations/{object-type}/{object-id}

Valid options for object type are reportTable , chart , map , eventReport , eventChart and dataSetReport .

Some valid examples for interpretations are listed below.

/api/26/interpretations/reportTable/yC86zJxU1i1
/api/26/interpretations/chart/ZMuYVhtIceD
/api/26/interpretations/map/FwLHSMCejFu
/api/26/interpretations/eventReport/xJmPLGP3Cde
/api/26/interpretations/eventChart/nEzXB2M9YBz
/api/26/interpretations/dataSetReport/tL7eCjmDIgM

As an example we will start by writing an interpretation for the chart with identifier EbRN2VIbPdV . To write chart interpretations we will interact with the /api/26/interpretations/chart/{chartId} resource. The interpretation will be the request body. Based on this we can put together the following request using cURL:

curl -d "This chart shows a significant ANC 1-3 dropout" -X POST
  "https://play.dhis2.org/demo/api/26/interpretations/chart/EbRN2VIbPdV"
  -H "Content-Type:text/plain" -u admin:district

Notice that the response provides a Location header with a value indicating the location of the created interpretation. This is useful from a client perspective when you would like to add a comment to the interpretation.

1.36.3 Updating and removing interpretations

To update an existing interpretation you can use a PUT request where the interpretation text is the request body using the following URL pattern, where {id} refers to the interpretation identifier:

/api/26/interpretations/{id}

Based on this we can use curl to update the interpretation:

curl -d "This charts shows a high dropout" -X PUT
  "https://play.dhis2.org/demo/api/26/interpretations/chart/EV08iI1cJRA"
  -H "Content-Type:text/plain" -u admin:district

You can use the same URL pattern as above using a DELETE request to remove the interpretation.

1.36.4 Creating interpretation comments

When writing comments to interpretations you will supply the comment text as the request body using a POST request with content type “text/plain”. The URL pattern looks like the below, where {interpretation-id} refers to the interpretation identifier.

/api/26/interpretations/{interpretation-id}/comments

Second, we will write a comment to the interpretation we wrote in the example above. By looking at the interpretation response you will see that a Location header is returned. This header tells us the URL of the newly created interpretation and from that we can read its identifier. This identifier is randomly generated so you will have to replace the one in the command below with your own. To write a comment we can interact with the /api/26/interpretations/{id}/comments" resource like this:

curl -d "An intervention is needed" -X POST
  "https://play.dhis2.org/demo/api/26/interpretations/j8sjHLkK8uY/comments"
  -H "Content-Type:text/plain" -u admin:district -v

1.36.5 Updating and removing interpretation comments

To updating an interpretation comment you can use a PUT request where the comment text is the request body using the following URL pattern:

/api/26/interpretations/{interpretation-id}/comments/{comment-id}

Based on this we can use curl to update the comment:

curl -d "I agree with that." -X PUT
  https://play.dhis2.org/demo/api/26/interpretations/j8sjHLkK8uY/comments/idAzzhVWvh2"
  -H "Content-Type:text/plain" -u admin:district -v

You can use the same URL pattern as above using a DELETE request to the remove the interpretation comment.

1.36.6 Liking interpretations

To like an interpretation you can use an empty POST request to the like resource:

POST /api/26/interpretations/{id}/like

A like will be added for the currently authenticated user. A user can only like an interpretation once.

To remove a like for an interpretation you can use a DELETE request to the same resource as for the like operation.

The like status of an intepretation can be viewed by looking at the regular Web API representation:

GET /api/26/interpretations/{id}

The like information is found in the likes field, which represents the number of likes, and the likedBy array, which enumerates the users who have liked the interpretation.

{
    "id": "XSHiFlHAhhh",
    "text": "Data looks suspicious, could be a data entry mistake.",
    "type": "REPORT_TABLE",
    "likes": 2,
    "likedBy": [{
        "id": "k7Hg12fJ2f1"
    }, {
        "id: "gYhf26fFkjFS"
    }]
}