Overview

The IHME Portal API is REST-based. It has predictable resource-oriented endpoints, uses standard HTTP response codes, authentication, and verbs.

Base URL

The API works over HTTPS and is accessed from https://portal-api.ihme.services.

Authentication

The IHME Portal API uses the standard HTTP Authorization header to pass authentication information. The header has the following form:

Authorization: IHME accessKey:signature

IHME Portal users can issue an access key and secret key on the API Access tab on the Profile page. If you don't see such tab, please contact your organization manager to enable API access for you.

The accessKey identifies the access key that was used to compute the signature and, indirectly, the user making the request.

The signature is the HMAC-SHA256 of the request, and so the signature part of the Authorization header will vary from request to request. If the request signature calculated by the system matches the signature included with the request, the requester will have demonstrated possession of the secret key. The request will then be processed under the identity, and with the authority, of the user to whom the key was issued.

Following is a pseudocode that illustrates the construction of the Authorization request header.

Authorization = "IHME " + accessKey + ":" + signature

signature = base64_encode(hmac_sha256(base64_decode(secretKey), utf8(stringToSign)))

stringToSign = "GET " +
    resource + 
    queryString + " " +
    date

Where:

• resource is the requested HTTP resource starting / (e.g. /metrics)

• queryString is the requested query string, starting with ?. Ensure that the order of query string parameters in stringToSign is the same as in the actual request (e.g. ?foo=bar)

• date is the current date in the YYYY-MM-DD format

Responses

By default, all data from the server is sent as JSON. Successful API responses contain the data property, which contains the response data:

{
    "data": <ResponseData>
}

Pagination

Requests that potentially may return an unlimited number of items are paginated. In addition to the endpoint-specific parameters they accept the following pagination parameters:

Parameter	Description
page	Specifies the page, default value is 1
per_page	Specifies the number of items per page, default value is 25

The response contains pagination information and has the following structure:

{
    "data": {
        "results": [ <ItemObject> ],
        "paging": {
            "page": <int>,
            "per_page": <int>,
            "total_count": <int>,
        }
    }
}

Data responses

To optimize work with data which can be big in size, data responses have a special structure:

{
    "data": {
        "columns": [ <string> ],
        "records": [ <number> ]
    }
}

For example:

{
    "data": {
        "columns": ["location_id", "year", "gender_id", "age_group_id", "cause_id", "value", "lower", "upper", "measure_id", "metric_id", "round_id"],
        "records": [
            [1, 2017, 3, 22, 345, 8.112419244347244, 5.760552147049214, 10.987782249868815, 1, 3, 9],
            [1, 2016, 3, 22, 345, 8.284266197192725, 5.874752706281531, 11.161025320022823, 1, 3, 9],
            ...,
            [1, 1990, 3, 22, 345, 12.466667314178515, 8.55202293100806, 17.09510789769929, 1, 3, 9]
        ]
    }
}

CSV Data responses

Optionally, the data can be requested in CSV by passing text/csv in the standard Accept header. Because CSV format is less versatile than JSON, paginated API endpoints cannot return data in CSV.

The data response from the example above requested as CSV would be:

location_id, year, gender_id, age_group_id, cause_id, value, lower, upper, measure_id, metric_id, round_id
1, 2017, 3, 22, 345, 8.112419244347244, 5.760552147049214, 10.987782249868815, 1, 3, 9
1, 2016, 3, 22, 345, 8.284266197192725, 5.874752706281531, 11.161025320022823, 1, 3, 9
...
1, 1990, 3, 22, 345, 12.466667314178515, 8.55202293100806, 17.09510789769929, 1, 3, 9

Errors

IHME Portal API uses conventional HTTP response codes to indicate the success or failure of an API request. Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.). Codes in the 5xx range indicate an error with IHME's servers (these are rare).

Error response body has the following structure:

{
    "message": <string>,
    "code": <int>
}

Where:

• message is a text providing more details about the error

• code is the error code that duplicates the HTTP response code

Some bad request (HTTP code 400) errors contain a detailed explanation about the field that caused the error:

{
    "message": <string>,
    "fields": {
        "<field_name>": <string>
    },
    "code": <int>
}