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: Optional[Sequence[int]] = None, classifications: Optional[Sequence[str]] = None, measure_ids: Optional[Sequence[int]] = None, gases: Optional[Sequence[str]] = 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: 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.
- 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: 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.
- Return type
pandas.DataFrame
Notes
Further documentation about the meaning of parties, categories, classifications, measures and gases is available at the UNFCCC documentation.
unfccc_di_api.tests
Unit test package for unfccc_di_api.
Code coverage metrics: