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.
- non_annex_one_reader
The API reader object for non-Annex I parties.
- 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()
andUNFCCCApiReader.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.
- 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: