Below are a series of direct REST API requests that can be placed after the host to return a JSON object or archive of JSON objects. All API requests are tested in Postman. Additional documentation can be found in the API section here, but a few of the most common requests are described below.
Authorization Headers
The authorization header must be refreshed every half hour for security reasons, so we recommend regenerating it for each request. This step is done for you automatically in the supported client libraries.
To do this on your own, for example to use in Postman, use the following Javascript, which is available to run directly here on JS Fiddle. Calling kapi.getAuthHeader() will return a new authorization header for subsequent requests.
|
var appId = ""; var n = ("0" + currentTime.getUTCDate()).slice(-2) + "-" + ("0" + (currentTime.getUTCMonth()+1)).slice(-2) + "-" + currentTime.getUTCFullYear().toString().substr(-2) + "-" + ("0" + currentTime.getUTCHours()).slice(-2); |
Note: The CryptoJS library is used to generate the token. You can use jsrsassign, which has an implementation for CryptoJS.HmacSHA1 and CryptoJS.enc.Base64 https://kjur.github.io/jsrsasign/.
Here is an example of an authorization header in Postman:
Get a list of all available datasets
Request: {host}/api/1.0/meta/dataset
Method: GET
Get Dataset Details
This request is usually used to retrieve and understand the structure of the dataset (see property “dimensions,” which tells you how many dimensions the dataset has and the IDs of each) and details such as data source, name, and description.
Request: /api/1.0/meta/dataset/<DatasetID>
Request example: /api/1.0/meta/dataset/qhblznb
Method: GET
Get Dataset Dimension Details
Note: Instead of dimension ID, you also can use dimension name, e.g., Country
Request: /api/1.0/meta/dataset/<DatasetID>/dimension/<DimensionID>
Request example: /api/1.0/meta/dataset/qhblznb/dimension/subject
Method: GET
This request is needed to understand the structure of each dimension. The Fields property contains a list of fields, which is useful to understand what metadata might be available for elements of the dataset. The Items property contains the full list of elements available within a dimension, metadata for each element is available under fields property of an appropriate item (see the example above). It also contains information on the Key (or ID) of each element, as well as its Name, Level (for building a hierarchy), and whether it contains data.
Get Data
Request: /api/1.0/data/<DatasetID>?<DimensionID>=<DimensionElementKey>&<DimensionID>=<DimensionElementKey>...
Request example: /api/1.0/data/qhblznb?country=1000000&subject=1000010&time=2018,2019
Method: GET
This approach is the easiest way to get the data and can be executed right from your browser. Several dimension elements keys can be provided, separated by commas. If no dimension members are specified, then all data for that dimension will be returned.
If you have a complex request, it is better to use ‘Get Pivot Data’. Also, the “Get Simple Dataset” request cannot be used with time-series.
Get a list of time-series in a dataset
There are two requests available: GET and POST.
Get the full list
Request: /api/1.0/data/dataset/<DatasetID>
Request example: /api/1.0/data/dataset/qhblznb
Method: GET
Get a filtered list
Request: /api/1.0/data/dataset/<DatasetID>
Request example: /api/1.0/data/dataset/qhblznb
Method: POST
Include Header Content-Type=application/json along with the usual authorization header.
The body should contain a list of dimensions with element keys for which you want a list of the available time-series.
Get Data by Time-series
Request: /api/1.0/data/get
Method: POST
Include Header Content-Type=application/json along with the usual authorization header.
The body should contain a list of dimensions with element keys for which you want a list of the available time-series. You may omit the StartDate, Frequency, and CustomFields and use only Timeseries and EndDate.
Get Raw Data
Request: /api/1.0/data/details
Method: POST
Include Header Content-Type=application/json along with the usual authorization header.
The body should specify the data you want to retrieve. You can list as many Members as you want in the Stub & Header, and only one in the Filter (or you can omit it).
Get Pivot Data
Request: /api/1.0/data/pivot
Method: POST
Include Header Content-Type=application/json along with the usual authorization header.
The body should specify the data you want to retrieve. You can list as many Members as you want to in the Stub & Header, and only one in the Filter (or you can omit it). It is similar to the body request for raw data.