unesco_reader.api

Wrapper for the UNESCO API

This module wraps the API endpoints that exist in the UIS API. For more information about the API visit: https://api.uis.unesco.org/api/public/documentation/

Endpoints:

  • get_data: Get indicator data

  • get_geo_units: Get available geo units

  • get_indicators: Get available indicators

  • get_versions: Get all published data versions

  • get_default_version: Get the current default data version

Attributes

logger

API_URL

TIMEOUT

RETRY_DELAY

_RETRYABLE_STATUS_CODES

_max_retries

Functions

set_max_retries(→ None)

Set the number of retries for transient network errors.

_check_valid_version(→ None)

Check if the version is valid. If the version is not None, it must be a string and must be a valid version in the API

_check_for_too_many_records(→ None)

Check if too many records have been requested.

_make_request(→ dict | list)

Make a request to an API endpoint and return the response object

_convert_bool_to_string(→ str | None)

Convert a boolean to a string. If the value is None, return None

get_data(→ dict)

Function to get indicator data. Wrapper for the indicator data endpoint

get_geo_units(→ list[dict])

Get geo units

get_indicators(→ list[dict])

Get available indicators

get_versions(→ list[dict])

Get all published data versions

get_default_version(→ dict)

Get the current default data version

Module Contents

unesco_reader.api.logger
unesco_reader.api.API_URL: str = 'https://api.uis.unesco.org'
unesco_reader.api.TIMEOUT: int = 30
unesco_reader.api.RETRY_DELAY: float = 1.0
unesco_reader.api._RETRYABLE_STATUS_CODES
unesco_reader.api._max_retries: int = 1
unesco_reader.api.set_max_retries(retries: int) → None

Set the number of retries for transient network errors.

Controls how many times a request is retried on timeouts, connection errors, and 502/503/504 responses before raising an exception. Set to 0 to disable retries.

Parameters:

retries – Number of retries. Must be a non-negative integer. Default is 1.

Raises:

ValueError – If retries is negative.

unesco_reader.api._check_valid_version(version: str | None) → None

Check if the version is valid. If the version is not None, it must be a string and must be a valid version in the API

Parameters:

version – The version to check

Raises:

ValueError – If the version is not valid

unesco_reader.api._check_for_too_many_records(response: requests.Response) → None

Check if too many records have been requested.

If too many records have been requested or the URI is too long, raise an error. A maximum of 100 000 records can be returned in a single query. If more records are requested, an error is raised. If this error occurs, the response is 400 and the message is {“message”:”Too much data requested (224879 records), please reduce the amount of records queried to less than 100000 by using the available filter options.”,”error”:”Bad Request”,”statusCode”:400}

If the URI is too long, it means too many parameters have been passed to the API and an error is raised.

Parameters:

response – The response object from the API

Raises:
unesco_reader.api._make_request(endpoint: str, params: dict | None = None) → dict | list

Make a request to an API endpoint and return the response object

Parameters:

  • endpoint – The endpoint to make the request to

  • params – Parameters to pass to the endpoint

Returns:

The response object as a dictionary

unesco_reader.api._convert_bool_to_string(value: bool | None) → str | None

Convert a boolean to a string. If the value is None, return None

unesco_reader.api.get_data(indicator: str | list[str] | None = None, geoUnit: str | list[str] | None = None, start: int | None = None, end: int | None = None, indicatorMetadata: bool = False, footnotes: bool = False, geoUnitType: unesco_reader.config.GeoUnitType | None = None, version: str | None = None) → dict

Function to get indicator data. Wrapper for the indicator data endpoint

At least an indicator or a geo_unit must be provided.

For more information about this endpoint visit: https://api.uis.unesco.org/api/public/documentation/operations/getIndicatorData

Parameters:

  • indicator – IDs of the requested indicators. Returns all available indicators if not provided.

  • geoUnit – IDs of the requested geographies (countries or regions). Returns all available geographies if not provided.

  • start – The start year to request data for. Includes the year itself. Default is the earliest available year.

  • end – The end year to request data for. Includes the year itself. Default is the latest available year

  • indicatorMetadata – Include indicator metadata in the response. Default is False

  • footnotes – Include footnotes (per data point) in the response. Default is False

  • geoUnitType – The type of geography to request data for. Allowed values are NATIONAL and REGIONAL If a geo_unit is provided, this parameter is ignored. Default is both national and regional data

  • version – The API data version to request. If not provided, defaults to the current default version.

Returns:

A dictionary with the response data

unesco_reader.api.get_geo_units(version: str | None = None) → list[dict]

Get geo units

Get all available geo units for a given API data version (or the current default version if no explicit version is provided).

Parameters:

version – The API data version to query. If not provided, defaults to the current default version.

Returns:

A list of dictionaries with geo units

unesco_reader.api.get_indicators(disaggregations: bool = False, glossaryTerms: bool = False, version: str | None = None) → list[dict]

Get available indicators

Get all available indicators, optionally with glossary terms and disaggregations, for the given API data version (or the current default version if no explicit version is provided).

Parameters:

  • disaggregations – Include disaggregations in the response. Default is False

  • glossaryTerms – Include glossary terms in the response. Default is False

  • version – The API data version to query. If not provided, the current default version is used.

Returns:

A list of dictionaries with the available indicators

unesco_reader.api.get_versions() → list[dict]

Get all published data versions

Returns:

A list of dictionaries with the different data versions and their metadata

unesco_reader.api.get_default_version() → dict

Get the current default data version

Returns:

A dictionary with the default data version and its metadata