Getting the API Key
In order to use the UIS API you will need first to get a subscription key. Please follow to these steps in order to obtain your key:
- Click the Sign in link and sign up using a valid email address and verify your email address by clicking on the verification link sent to you by email.
- Click on Products on the main menu and select the ‘Starter’ product.
- Click the ‘Subscribe’ button under the ‘UIS SDMX API’
- Click ‘Confirm’.
- You should now be sent to your profile page where you’ll be able to see the API keys for UIS SDMX API.
Calling the API
The API endpoint is located at http(s)://api.uis.unesco.org/sdmx. The API definition is available in WADL and Swagger format and can be obtained by going to APIs > UIS SDMX API (You have to Sign in first) and clicking on the API definition button.
One of the basic queries is to retrieve the list of countries that is used in the UIS Data; for which you can use the following request:
The API subscription key can be specified either as a query string parameter like the above example or using the header parameter ‘Ocp-Apim-Subscription-Key’.
The default response format of the API is XML. It is possible to obtain the response in JSON by either specifying ‘format=sdmx-json’ in the query string or by setting the ‘Accept: application/vnd.sdmx.json’ in the header of the request.
As you can see in the response, the API is multilingual and country names are provided in multiple languages by default. In order to issue requests for a specific language to reduce the response message size, specify the locale either in the query string or by using the Accept-Language header. For example, to retrieve the country list in English, use:
The parameters for specifying the format and the locale are consistent across the API and can be applied to all endpoints.
The main goal for the API is to be able to query the datasets disseminated by the UIS. The UIS datasets are multidimensional cubes and are described using the SDMX information model.
In order to retrieve the list of UNESCO datasets that are available via the API, one must retrieve the list of the data flows, which is the SDMX term for datasets:
Once the data flow is known, one has to build a data query against it to retrieve the data. The data query has the following format:
The key contains the list of dimension values to retrieve the data for. The list of dimensions is available in the data structure definition (DSD) of the dataflow. For example, the following request retrieves the data structure definition for the innovation data flow (INNOV):
The list of dimensions can be seen in the DataStructure.dimensionList of the response message.
Each dimension contains reference to the concepts and code list that contain the list of valid values for the particular dimension. The following request retrieves the data structure definition (DSD) along with concepts and code lists for the INNOV dataset:
The order of the dimension in the dimension list is important to build the key because the key consists of the list of dimension values for each dimension separated by a ‘.’ and listing the dimension by the order they appear in the dimension list of the data structure definition (DSD). For example, the key ‘.....FIRM.AU+CN+IT...’ represents filtering the dataset by the Statistical unit=Manufacturing Firm [FIRM] and Reference Area=Australia, China and Italy [AU+CN+IT]. The following request retrieves the data for INNOV dataset using this key:
The data endpoint supports the following format parameters: ‘sdmx-compact-2.1, sdmx-generic-2.1, sdmx-compact-2.0, sdmx-generic-2.0, sdmx-json, csv’.
For more information about building a data query follow this tutorial.
For more information
The API and the SDMX Information model offer many options for retrieving data and metadata. The user guide will provide more in depth details about consuming the API. The SDMX RESTful Specifications is also a good source of information and contains useful tutorials.
You’re welcome to provide feedback and ask questions in the Feedback section of this portal.