How to List Metadata and Refine Searches

Earthemission's database boasts an extensive collection of over 40,000 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 earthemission, and further demonstrates how to fine-tune your searches.

The best tool at your disposal for navigating all of earthemission'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 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"
    ]
}

Listing All Values

If you send a search query without any additional filters, the possible_filters object will contain all the metadata earthemission 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://beta4.api.earthemission.io/search?data_version=^3' \
  --header 'Authorization: Bearer API_KEY'

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

Note: 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 earthemission might have metadata, such as a region, that is not returned: 1. 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. 2. If all emission factors with a specific property have data quality issues: earthemission 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://beta4.api.earthemission.io/search?activity_id=electricity-supply_grid-source_supplier_mix&
  data_version=^3'
  --header 'Authorization: Bearer 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://beta4.api.earthemission.io/search?activity_id=
  electricity-supply_grid-source_supplier_mix&region=US&data_version=^3'
  --header 'Authorization: Bearer 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://beta4.api.earthemission.io/search?activity_id=electricity-supply_grid-
  source_supplier_mix&region=US&source=EPA&data_version=^3'
  --header 'Authorization: Bearer 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 earthemission pick the most suitable emission factor from the ones left.