How to List Metadata and Refine Searches

Climatiq’s database boasts an extensive collection of 1M+ emission factors that cover a plethora of regions and sources. This guide provides a step-by-step tutorial on how to enumerate all the metadata (regions, sources, etc.) available on Climatiq, and further demonstrates how to fine-tune your searches.

The best tool at your disposal for navigating all of Climatiq’s emission factors is the /search endpoint. This endpoint does not only respond with emission factors, but also the possible_filters object.

The possible_filters object lists potential filters that if added to your query will still result in valid emission factors, and we’re going to be using the rest of this guide to explore how to use it. The below JSON is a truncated example of the possible_filter object for a search query for the activity ID electricity-supply_grid-source_supplier_mix. As shown, it enumerates over years, sources, regions, scopes and more.


{
    "year": [
        2022,
        2021,
        2020,
        2019,
        2018,
        2017,
        2016,
        2015,
        ...
    ],
    "source": [
        {
            "source": "ADEME",
            "datasets": [
                "Base Carbone"
            ]
        },
        {
            "source": "BEIS",
            "datasets": [
                "UK Government GHG Conversion Factors for Company Reporting"
            ]
        },
        ...
    ],
    "region": [
        {
            "id": "AE",
            "name": "United Arab Emirates"
        },
        {
            "id": "AFRICA",
            "name": "Africa"
        },
        {
            "id": "AL",
            "name": "Albania"
        },
        {
            "id": "AM",
            "name": "Armenia"
        },
        {
            "id": "AO",
            "name": "Angola"
        },
        {
            "id": "AR",
            "name": "Argentina"
        },
        {
            "id": "AT",
            "name": "Austria"
        },
        {
            "id": "AU",
            "name": "Australia"
        },
        ...
    ],
    "category": [
        "Electricity"
    ],
    "sector": [
        "Energy"
    ],
    "unit_type": [
        "Energy"
    ],
    "source_lca_activity": [
        "electricity_consumption",
        "electricity_generation",
        "electricity_generation-transmission_and_distribution",
        "fuel_upstream-plant_amortization-fuel_combustion-fugitive_emissions",
        ...
    ],
    "access_type": [
        "public"
    ],
    "data_quality_flags": [
        "partial_factor",
        "notable_methodological_variance"
    ],
    "scope": [
        "1",
        "2",
        "3",
        "3.1",
        ...
    ]
}

Listing All Values

If you send a search query without any additional filters, the possible_filters object will contain all the metadata Climatiq has to offer, such as region, source, or year. This is because in a search query where you have not applied any filters, each piece of metadata could potentially serve as a valid filter that would still yield legitimate emission factors.

As an example, for a query like the one below:


curl --request GET \
  --url 'https://api.climatiq.io/data/v1/search?data_version=^37' \
  --header "Authorization: Bearer $CLIMATIQ_API_KEY"

The possible_filters object will enumerate all regions, sources, etc. that Climatiq can provide.

possible_filters only return values you have access to

As possible_filters only returns metadata that will still lead to a valid emission factor when filtered on, there are two situations where Climatiq might have metadata, such as a region, that is not returned:

Metadata exclusive to paid datasets: Some datasets are premium and require explicit purchase, such as ecoinvent. If this dataset is not purchased on your account, ecoinvent will not appear as a source, nor will any regions that are exclusive to ecoinvent.
If all emission factors with a specific property have data quality issues: Climatiq by default filters out certain emission factors if they have data quality issues. This means that if all emission factors for a particular source or region have data quality issues, this source or region would not appear. If you want to use emission factors with those data quality issues, you will have to include them explicitly.

Narrowing Searches: A Practical Example

To illustrate this process, let’s consider a real-world application that assists users in obtaining emission factor data for their electricity usage. You know the activity ID you’re interested in is electricity-supply_grid-source_supplier_mix, but you need the user to specify a region and a data source.

Initial Search

For the initial search, let’s use the specific activity_id mentioned above:


curl --request GET \
  --url 'https://api.climatiq.io/data/v1/search?activity_id=electricity-supply_grid-source_supplier_mix&data_version=^37' \
  --header "Authorization: Bearer $CLIMATIQ_API_KEY"

By reading the returned possible_filters, we now have all regions where the given activity_id is valid. The possible_filters object from the API could look something like the below:


{
    "year": [
        2022,
        2021,
        ...
    ],
    "source": [
        {
            "source": "BEIS",
            "datasets": [
            "UK Government GHG Conversion Factors for Company Reporting"
            ]
        },
        {
            "source": "EPA",
            "datasets": [
            "eGRID",
            "GHG Emission Factors Hub"
            ]
        },
        ...
    ],
    "region": [
        {
            "id": "AE",
            "name": "United Arab Emirates"
        },
            ...
        {
            "id": "ZM",
            "name": "Zambia"
        },
        {
            "id": "ZW",
            "name": "Zimbabwe"
        }
    ],
    ...
}

Filtering by Region

We can then prompt the user for what region they’re interested in. Suppose the user selects ‘US’ as their region. We then refine the search to reflect this selection:


curl --request GET \
  --url 'https://api.climatiq.io/data/v1/search?activity_id=electricity-supply_grid-source_supplier_mix&region=US&data_version=^37' \
  --header "Authorization: Bearer $CLIMATIQ_API_KEY"

We now have the additional metadata for this region and activity_id. Perhaps we can see there are still multiple sources that can provide this data, and the user needs to select one. This would be the case if the possible_filters returned looked like this:


{
    "year": [
        2022,
        2021,
        ...
    ],
    "source": [
        {
        "source": "BEIS",
        "datasets": [
            "UK Government GHG Conversion Factors for Company Reporting"
            ]
        },
        {
        "source": "EPA",
        "datasets": [
            "eGRID",
            "GHG Emission Factors Hub"
            ]
        },
        ...
    ],
    "region": [
        {
            "id": "US",
            "name": "United States"
        }
    ],
    ...
}

Filtering by Source

At this stage, we include the source in the query to further narrow down our list of results.


curl --request GET \
  --url 'https://api.climatiq.io/data/v1/search?activity_id=electricity-supply_grid-source_supplier_mix&region=US&source=EPA&data_version=^37' \
  --header "Authorization: Bearer $CLIMATIQ_API_KEY"

This final query yields a set of emission factors specific to the activity_id (electricity-supply_grid-source_supplier_mix), the selected region (‘US’), and the user-selected source (‘EPA’).

If necessary, we could further request more information from the user (limiting their choices to what possible_filters says is possible). Alternatively, we could utilize the information we already have to perform a basic estimate and let Climatiq pick the most suitable emission factor from the ones left.

Filtering by Scope

Climatiq’s emission factors have been categorized based on which Greenhouse Gas Protocol (GHGP) scopes they fall under. This means if you’re looking for emission factors for scope 3.3 reporting, you can narrow your search down to just those emission factors, e.g. like this:


curl --request GET \
  --url 'https://api.climatiq.io/data/v1/search?scope=3.3&data_version=^37' \
  --header "Authorization: Bearer $CLIMATIQ_API_KEY"

All the valid values you can input in the scope filter is as follows: "1", "2", "3", "3.1", "3.2", "3.3", "3.4", "3.5", "3.6", "3.7", "3.8", "3.9", "3.10", "3.11", "3.12", "3.13", "3.14", "3.15", "outside_of_scopes"

A few things worth noting when you filter on scopes.

An emission factor might have multiple scopes, like ["3.4", "3.9"], because it could be used to report either upstream or downstream transportation, depending on how it’s used. Filtering on either 3, 3.4 or 3.9 would surface this emission factor.
While it’s possible to provide scope 3 as a filter parameter, emission factors always have a concrete category, like 1, 2, 3.1, 3.2 etc. They never just have scope 3. Filtering on scope 3 means you want emission factors with all scope 3 subcategories like 3.1, 3.2 etc.
Some emission factors might have outside_of_scopes listed as their scope. This means that the emission factor reports emissions that should not be reported under scope 1, 2 or 3. This could be e.g. because it tracks non-Kyoto gases, carbon storage or similar things that do not fall under the GHGP reporting framework.
Some emission factors might return combined_scopes. This is because they contain emissions that should be reported under several different scopes, but the source has not split them up. There are very few of these emission factors, and Climatiq recommends not using them for corporate reporting. An example of this could be an emission factor that combines the extraction and combustion of fuel, which should be reported separately as scope 1 and 3.3. Such a factor will currently list combined_scopes as its scope. It will however appear, if you filter on either 3.3 or 1. If you don’t want to use emission factors with combined scopes, you should filter them out after retrieving them from /search.