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.

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: Optional[Sequence[str]] = None, progress: bool = False, normalize_gas_names: bool = True) pandas.core.frame.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.

Returns

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: Optional[Sequence[int]] = None, classifications: Optional[Sequence[str]] = None, measure_ids: Optional[Sequence[int]] = None, gases: Optional[Sequence[str]] = None, batch_size: int = 1000, progress: bool = False, normalize_gas_names: bool = True) pandas.core.frame.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.

Returns

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.

unfccc_di_api.tests

Unit test package for unfccc_di_api.

Code coverage metrics:

Coverage metrics