API

unfccc_di_api

The API provided by the UNFCCC distinguishes between parties listed in Annex I and the other parties, likely because the reporting requirements for Annex I parties and non-Annex I parties differ substantially. This library provides a wrapper class UNFCCCApiReader which unifies both APIs so that you don’t have to worry about the status of a particular party. However, if you want to filter for specific variables and only query a subset of the data, you have to use the individual API objects for Annex I and non-Annex I parties, which are available at UNFCCCApiReader.annex_one_reader and UNFCCCApiReader.non_annex_one_reader, respectively.

exception unfccc_di_api.NoDataError(party_codes: Sequence[str], category_ids: Sequence[int] | None = None, classifications: Sequence[str] | None = None, measure_ids: Sequence[int] | None = None, gases: Sequence[str] | None = None)[source]: Query returned no data.

class unfccc_di_api.UNFCCCApiReader(*, base_url: str = 'https://di.unfccc.int/api/')[source]

Provides simplified unified access to the Flexible Query API of the UNFCCC data access for all parties.

Essentially encapsulates https://di.unfccc.int/flex_non_annex1 and https://di.unfccc.int/flex_annex1 .

parties

All parties, with their ID, code, and full name.

Type:: pandas.DataFrame

gases

The available gases and their IDs.

Type:: pandas.DataFrame

annex_one_reader

The API reader object for Annex I parties.

Type:: UNFCCCSingleCategoryApiReader

non_annex_one_reader

The API reader object for non-Annex I parties.

Type:: UNFCCCSingleCategoryApiReader

query(*, party_code: str, gases: Sequence[str] | None = None, progress: bool = False, normalize_gas_names: bool = True) → DataFrame[source]

Query the UNFCCC for data.

Parameters:

party_code (str) – ISO code of a party for which to query. For possible values, see parties.
gases (list of str, optional) – Limit the query to these gases. For possible values, see gases. Accepts subscripts (“N₂O”) as well as ASCII-strings (“N2O”). Default: query for all gases.
progress (bool) – Display a progress bar. Requires the tqdm library. Default: false.
normalize_gas_names (bool, optional) – If True, return gases as ASCII strings (“N2O”). Else, return native UNFCCC notation (“N₂O”). Default: true.

Return type:

pandas.DataFrame

Notes

If you need more fine-grained control over which variables to query for, including restricting the query to specific measures, categories, or classifications or to query for multiple parties at once, please see the corresponding methods UNFCCCApiReader.annex_one_reader.query() and UNFCCCApiReader.non_annex_one_reader.query().

class unfccc_di_api.UNFCCCSingleCategoryApiReader(*, party_category: str, base_url: str = 'https://di.unfccc.int/api/')[source]

Provides access to the Flexible Query API of the UNFCCC data access for a single category, either annexOne or nonAnnexOne.

Use this class if you want to do fine-grained queries for specific measures, categories, years, or classifications.

Essentially encapsulates https://di.unfccc.int/flex_non_annex1 or https://di.unfccc.int/flex_annex1 .

parties

All parties in this category, with their ID, code, and full name.

Type:: pandas.DataFrame

years

All years for which data is available, mapping the ID to the year.

Type:: pandas.DataFrame

category_tree

The available categories and their relationships. Use show_category_hierarchy() for displaying the category tree.

Type:: treelib.Tree

classifications

All classifications and their IDs.

Type:: pandas.DataFrame

measure_tree

The available measures and their relationsips. Use show_measure_hierarchy() for displaying the measure tree.

Type:: treelib.Tree

gases

The available gases and their IDs.

Type:: pandas.DataFrame

units

The available units and their IDs.

Type:: pandas.DataFrame

conversion_factors

Conversion factors between units for the specified gases.

Type:: pandas.DataFrame

variables

The available variables with the corresponding category, classification, measure, gas, and unit.

Type:: pandas.DataFrame

query(*, party_codes: Sequence[str], category_ids: Sequence[int] | None = None, classifications: Sequence[str] | None = None, measure_ids: Sequence[int] | None = None, gases: Sequence[str] | None = None, batch_size: int = 1000, progress: bool = False, normalize_gas_names: bool = True) → DataFrame[source]

Query the UNFCCC for data.

Parameters:

party_codes (list of str) – List of ISO codes of parties for which to query. For possible values, see parties.
category_ids (list of int, optional) – List of category IDs to query. For possible values, see show_category_hierarchy(). Default: query for all categories.
classifications (list of str, optional) – List of classifications to query. For possible values, see classifications. Default: query for all classifications.
measure_ids (list of int, optional) – List of measure IDs to query. For possible values, see show_measure_hierarchy(). Default: query for all measures.
gases (list of str, optional) – Limit the query to these gases. For possible values, see gases. Accepts subscripts (“N₂O”) as well as ASCII-strings (“N2O”). Default: query for all gases.
batch_size (int, optional) – Number of variables to query in a single API query in the same batch to avoid internal server errors. Larger queries are split automatically. The default is 1000, which seems to work fine.
progress (bool) – Display a progress bar. Requires the tqdm library. Default: false.
normalize_gas_names (bool, optional) – If True, return gases as ASCII strings (“N2O”). Else, return native UNFCCC notation (“N₂O”). Default: true.

Return type:

pandas.DataFrame

Notes

Further documentation about the meaning of parties, categories, classifications, measures and gases is available at the UNFCCC documentation.

show_category_hierarchy() → None[source]: Print the hierarchy of categories and their IDs.

show_measure_hierarchy() → None[source]: Print the hierarchy of measures and their IDs.

class unfccc_di_api.ZenodoReader(*, url: str = 'doi:10.5281/zenodo.10470862/parquet-only.zip', known_hash: str = 'md5:52dd6cc26f1c2eb3f8204c6a78d2e7ba')[source]

Provides simplified unified access to the data provided by the Flexible Query API of the UNFCCC data access, via the dataset stored at zenodo.

Essentially gives you the same API as the UNFCCCApiReader, but without complications due to the protection measures of the DI API. The advantage of using the ZenodoReader is that it works reliably without special measures, the disadvantage is that the data might be a bit older.

parties

All parties as a 3-letter iso code.

Type:: list[str]

query(*, party_code: str, gases: Sequence[str] | None = None, normalize_gas_names: bool = True) → DataFrame[source]

Query the dataset for party data.

Parameters:

party_code (str) – ISO code of a party for which to query. For possible values, see parties.
gases (list of str, optional) – Limit the query to these gases. Accepts subscripts (“N₂O”) as well as ASCII-strings (“N2O”). Default: query for all gases. Note that anything else than the default is not yet implemented and raises an error. Just request the whole dataset and filter using pandas’ normal functionality.
normalize_gas_names (bool, optional) – If True, return gases as ASCII strings (“N2O”). Else, return native UNFCCC notation (“N₂O”). Default: true. Note that anything else than the default is not implemented and raises an error. If you require unnormalized gas names, open an issue in the issue tracker at github so we can understand your use case.

Return type:

pandas.DataFrame

unfccc_di_api.tests

Unit test package for unfccc_di_api.

Code coverage metrics: