unesco_reader.api ================= .. py:module:: unesco_reader.api .. autoapi-nested-parse:: 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 ---------- .. autoapisummary:: unesco_reader.api.logger unesco_reader.api.API_URL unesco_reader.api.TIMEOUT unesco_reader.api.RETRY_DELAY unesco_reader.api._RETRYABLE_STATUS_CODES unesco_reader.api._max_retries Functions --------- .. autoapisummary:: unesco_reader.api.set_max_retries unesco_reader.api._check_valid_version unesco_reader.api._check_for_too_many_records unesco_reader.api._make_request unesco_reader.api._convert_bool_to_string unesco_reader.api.get_data unesco_reader.api.get_geo_units unesco_reader.api.get_indicators unesco_reader.api.get_versions unesco_reader.api.get_default_version Module Contents --------------- .. py:data:: logger .. py:data:: API_URL :type: str :value: 'https://api.uis.unesco.org' .. py:data:: TIMEOUT :type: int :value: 30 .. py:data:: RETRY_DELAY :type: float :value: 1.0 .. py:data:: _RETRYABLE_STATUS_CODES .. py:data:: _max_retries :type: int :value: 1 .. py:function:: 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. :param retries: Number of retries. Must be a non-negative integer. Default is 1. :raises ValueError: If retries is negative. .. py:function:: _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 :param version: The version to check :raises ValueError: If the version is not valid .. py:function:: _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. :param response: The response object from the API :raises TooManyRecordsError: If too many records have been requested :raises TooManyRecordsError: If the URI is too long .. py:function:: _make_request(endpoint: str, params: dict | None = None) -> dict | list Make a request to an API endpoint and return the response object :param endpoint: The endpoint to make the request to :param params: Parameters to pass to the endpoint :returns: The response object as a dictionary .. py:function:: _convert_bool_to_string(value: bool | None) -> str | None Convert a boolean to a string. If the value is None, return None .. py:function:: 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 :param indicator: IDs of the requested indicators. Returns all available indicators if not provided. :param geoUnit: IDs of the requested geographies (countries or regions). Returns all available geographies if not provided. :param start: The start year to request data for. Includes the year itself. Default is the earliest available year. :param end: The end year to request data for. Includes the year itself. Default is the latest available year :param indicatorMetadata: Include indicator metadata in the response. Default is False :param footnotes: Include footnotes (per data point) in the response. Default is False :param 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 :param version: The API data version to request. If not provided, defaults to the current default version. :returns: A dictionary with the response data .. py:function:: 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). :param version: The API data version to query. If not provided, defaults to the current default version. :returns: A list of dictionaries with geo units .. py:function:: 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). :param disaggregations: Include disaggregations in the response. Default is False :param glossaryTerms: Include glossary terms in the response. Default is False :param 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 .. py:function:: get_versions() -> list[dict] Get all published data versions :returns: A list of dictionaries with the different data versions and their metadata .. py:function:: get_default_version() -> dict Get the current default data version :returns: A dictionary with the default data version and its metadata