UNESCO Institute for Statistics (UIS)

## Table of contents - [Introduction](#introduction) - [License](#license) - [Rate limiting and caching](#rate-limiting-and-caching) - [Bulk Data Download](#bulk-data-download) - [Endpoints overview](#endpoints-overview) - [OpenAPI Specification](#openapi-specification) - [Changelog](#api-changelog) ## Introduction This API offers programmatic access to the data of the UNESCO Institute for Statistics (UIS). The data is available in different formats and can be accessed through different endpoints. ### API training session Check out the [API training session website](https://tcg.uis.unesco.org/api_trainings/) for the video recording of the API training session and related materials. ## License The data is licensed under the [Creative Commons Attribution-ShareAlike 4.0 International](https://creativecommons.org/licenses/by-sa/4.0/) license. Visit the [Terms and conditions page](https://databrowser.uis.unesco.org/terms-and-conditions) for more information. ## Rate limiting and caching There is currently no rate limiting in place. The API relies heavily on caching to ensure that the data is served as quickly as possible. To ensure your usage of the API takes full advantage of caching, ensure that the query parameters are used in the same order as the caching is done on the full URL used to query data. ### Data response limits The API will only return 100'000 records for each query, if more data is requested, the API call with fail with a `400` http status code. If you need more data, consider using the [Bulk Data Download](#bulk-data-download) or making multiple queries. ### Special considerations for browser based usage The API can be queried directly from the browser as the CORS headers as set to allow requests from any origin. For ideal performance always include an explicit `version` parameter in the query so that the response can be cached by the browser of each client. You can use the [default version endpoint](/operations/getPublishedDefaultVersion) to get the current default version. ## Bulk Data Download The Bulk Data Download Service (BDDS) allows users to download aggregated UIS datasets as flat files. Visit the [Bulk Data Download Service page](https://databrowser.uis.unesco.org/resources/bulk) for more information. ## Endpoints overview ### Version endpoints The [default version endpoint](/operations/getPublishedDefaultVersion) returns the current default data version (newest published) and the [list versions endpoint](/operations/listPublishedVersions) returns all published versions and can be used to query data for a specific data version. ### Data endpoints The main [indicator data endpoint](/operations/getIndicatorData) offers access to the data records and supports a range of different filter options. This endpoint always return JSON data and should be used for most programmatic integrations. The [indicator data export endpoint](/operations/exportIndicatorData) offers the same data and filter options as the indicator data endpoint but also offers results in CSV and EXCEL formats. This endpoint always returns a ZIP file with the requested data as well as a README.md file. ### Definitions endpoints The [list geo units endpoint](/operations/listGeoUnits) returns a list of all available geo units and the [list indicators endpoint](/operations/listIndicators) returns a list of all available indicators. ## OpenAPI Specification This documentation is generated from the OpenAPI specifications of the API. The specification can be downloaded either via the `Export` dropdown on the top right of this page or via this url: [https://api.uis.unesco.org/api/public/openapi/schema.json](https://api.uis.unesco.org/api/public/openapi/schema.json) ## API Changelog ### 2024-09-11 - Version 1.0.0 Initial release of the UIS Data API ### 2024-09-17 - Version 1.0.1 Extended documentation to include query examples for the geo unit and indicator definitions endpoints as well as the indicator data endpoints. ### 2024-09-26 - Version 1.0.2 Added links to the [API training session](#api-training-session) recording/materials and added extended examples file to the [indicator data endpoint](/operations/getIndicatorData) documentation page.