API Reference
Search

Search

GET Allows you to determine what emission factors are available to be used in your estimates.

You can search for free-text queries with the query parameter, or filter by parameters such as category, source, region, year calculation_method, source_lca_activity or id.

If you are using the query parameter, the results will be returned in order of how well they match your free-text query.

This endpoint is paginated, and will return current_page and last_page so you can determine which page you are on. You switch pages by using the page query parameter.

https://api.climatiq.io/data/v1/search

Request

Request parametersShould be sent as an URL-encoded query string

  • data_versionrequired string

    The required Data Version string for this request.

  • querystring

    A free-text query that will match ids, names, descriptions, etc. of emission factors. This uses fuzzy matching, so your query does not need to be precise. Spaces need to be encoded as + or %20

  • activity_idstring

    Filter by the id of a specific activity. Multiple emission factors might share the same activity. You may specify an asterisk (*) at the end of the activity id to act as a wildcard character, matching any ids that begin with the string before the asterisk.

  • idstring

    Filter by the id of a specific emission factor. As IDs are unique, this will only ever return a maximum of 1 emission factor. If using id, the emission factor will only be returned if it was not added later than the provided data version.

  • categorystring

    Filters by emission factor category

  • sectorstring

    Filters by emission factor sector

  • sourcestring

    Filters emission factors by data source

  • source_datasetstring

    Filters emission factors by a given dataset from a source

  • yearinteger

    Filters emission factors by the year in which the emission factor is considered most relevant, according to the source.

  • regionstring

    Filters emission factors by geographic region to which it applies. You may specify an asterisk (*) at the end of the region to act as a wildcard character, matching any regions, such as sub-regions, that begin with the string before the asterisk.

  • unit_typestring

    Filters emission factors by what unit (such as money, energy or volume) the factor accepts.

  • source_lca_activitystring

    The Life Cycle Assessment (LCA) activity with which this factor is associated.

  • calculation_methodstring

    The calculation method that is used to calculate the emission factor. Can be either ar4, ar5 or ar6. Not providing a value means that this defaults to the latest calculation methodology the source supports. Learn more about calculation methods here.

  • allowed_data_quality_flagsarray of strings

    A list of data quality flags that you are willing to allow for this query. You can provide a comma-separated list of data quality flags you want to allow, or the value none if you only want emission factors without detected data quality issues. See the guide on data quality flags for more information.

    Default Value
  • access_typestring

    Filters by the access type of the emission factors. Allowed values are public, private and premium

  • pageinteger

    Which page of results to retrieve.

    Default Value
    1
  • results_per_pageinteger

    How many results to return per page. Max is 500.

    Default Value
    20
curl --request GET \
--url 'https://api.climatiq.io/data/v1/search?query=light+duty+trucks&data_version=^6&year=2021&results_per_page=1' \
--header 'Authorization: Bearer API_KEY' \

Response

The response includes a paginated list of emission factors filtered by the request parameters above.

Attribute
results array
A list of emission factors for this page. See below.
current_page number
The current page you have retrieved
last_page number
The last page that there are results for.
total_results number
How many results there are in total across all pages.
possible_filters object
A list of potential filters you can use to further narrow down your query. See below.

results

Every emission factor returned in the list of results is formed by the following properties:

Attribute
id string
The unique ID describing this particular emission factor.
activity_id string
The ID describing the activity that this emission factor applies to. Multiple emission factors can share the same activity_id, e.g. if they are from a different source or apply to a different region.
access_type string
Whether or not the data is publicly available or private to your project. Can be either private or public. Public emission factors are available to all, while private emission factors are only accessible to you.
name string
Emission factor name.
category string
Emission factor category.
sector string
Emission factor sector.
source string
Emission factor publisher.
source_link string
Link to emission factor publisher.
uncertainty number or null
Emission factor uncertainty factor (%).
year number
The year in which the emission factor is considered most relevant, according to the source.
year_released number
The year in which the emission factor was released by the source.
region string
Geographic region to which the emission factor applies (UN/LOCODE (opens in a new tab)).
region_name string
Geographic region to which the emission factor applies (in English).
description string
Emission factor description.
unit_type array
A list of Unit types that this emission factor accepts.
unit string
The unit in which the factor field is expressed.
source_lca_activity string
Which LCA activity the emission factor corresponds to. Read more about life cycle assessments here.
supported_calculation_methods array of strings
The methods of CO2e calculation supported for this emission factor
factor number or null
CO2e emission factor value, expressed in kgCO2e emitted per unit of activity provided in the unit field. This is available as add-on. Reach out to our team to know more. Otherwise the value is null for the community plan. You can use the estimate endpoint to calculate the emissions generated by specifying this factor.
factor_calculation_method "ar4", "ar5", "ar6" or null
Indicates which conversion values were used (IPCC 4th, 5th or 6th Assessment Report) to generate the returned CO2e emission factor. If factor is null, this is also null.
factor_calculation_origin "climatiq", "source" or null
Indicates whether the CO2e emission factor provided in this response was provided by the source or calculated by Climatiq. If factor is null, this is also null.
constituent_gases constituent gases
Indicates which gases the CO2e emission factor is composed of.
{
"current_page": 1,
"last_page": 3,
"total_results": 3,
"results": [
{
"activity_id": "fuel-type_diesel-fuel_use_diesel_light_duty_trucks",
"id": "d4a3d672-e13c-435a-967f-fa067d8a01cd",
"name": "Diesel fuel - diesel light-duty trucks",
"category": "Fuel",
"sector": "Energy",
"source": "GHG Protocol",
"source_link": "https://ghgprotocol.org/sites/default/files/GHG%20Emissions%20Calculation%20Tool_0.xlsx",
"source_dataset": "GHG Emissions Calculation Tool",
"uncertainty": null,
"year": 2021,
"year_released": 2021,
"region": "US",
"region_name": "United States",
"description": "Emission intensity of mobile combustion of fuel. Includes fuel consumption by vehicles that are owned or leased by the company. The primary source is EPA Emission Factors for Greenhouse Gas Inventories - March 9 2018 - WRI - GHG Protocol - Emission Factors from Cross-Sector Tools - April 2014. NOTE: This dataset has been deprecated by the source and will be removed soon.",
"unit_type": "Volume",
"unit": "kg/gal (US)",
"source_lca_activity": "fuel_combustion",
"data_quality_flags": [
"notable_methodological_variance"
],
"access_type": "public",
"supported_calculation_methods": [
"ar4",
"ar5",
"ar6"
],
"factor": 10.22,
"factor_calculation_method": "ar5",
"factor_calculation_origin": "source",
"constituent_gases": {
"co2e_total": 10.22,
"co2e_other": null,
"co2": 10.21,
"ch4": 0.0000162,
"n2o": 0.0000243
}
}
],
"possible_filters": {
"year": [
2021
],
"source": [
{
"source": "EPA",
"datasets": [
"GHG Emission Factors Hub"
]
},
{
"source": "GHG Protocol",
"datasets": [
"GHG Emissions Calculation Tool"
]
}
],
"region": [
{
"id": "US",
"name": "United States"
}
],
"category": [
"Fuel",
"Vehicles"
],
"sector": [
"Energy",
"Transport"
],
"unit_type": [
"Distance",
"Volume"
],
"source_lca_activity": [
"fuel_combustion",
"use_phase"
],
"access_type": [
"public"
],
"data_quality_flags": [
"notable_methodological_variance"
]
}
}

possible_filters

The field possible_filters includes aggregated metadata about the results of your search request, to help you to choose further filters which would narrow down your results.

Most of the fields (year, category, sector, unit_type, source_lca_activity, access_type) contain a list enumerating each of the values present for the given field in the response. The values can be used verbatim in those fields of the search request to narrow down the results. If there is only one value, all results have the same value for this field.

The values of region contain a JSON object, the id field is the ISO 3166-1 alpha-2 code (opens in a new tab) for the country and can be used as the value for further filtering, the name is provided for the convenience of interactive apps to show the full name of the country.

The source contain a JSON object, the source field inside it is the source name, corresponding to the source for an emission factor. The datasets field is what datasets that belong to this particular source, is a valid source_dataset filter for this query.

data_quality_flags is named differently from its search request parameter equivalent allowed_data_quality_flags as it can't be used in the same way as the other filters.

  • Each emission factor can have multiple, or (usually) no data quality flags, so each of your results may have the same 2 flags, then if you select only one of them you would have no more results.
  • When a search doesn't specify an allowed_data_quality_flags list, we allow some flags by default. See here for more information about data quality. Also see the documentation for the search request above for how to use allowed_data_quality_flags while searching.

If you're curious about how to use possible_filters to narrow down your searches, the search refinement how-to has you covered.

Constituent Gases

The constituent gases model explains which constituent gases the source of the data considers to be part of their calculations. These values might be null for one of several reasons:

  • The source does not provide data at the constituent gas level.
  • The source is a premium dataset, and part of the commercial terms dictate we cannot reveal this number.
  • You do not have a commercial agreement with Climatiq to view this data.

The constituent gases also depend on the calculation methodology chosen, displayed as factor_calculation_method in the search results. If you filter on different calculation methodologies, you might see different constituent gas values. Learn more about calculation methods and constituent gases here

Attribute
co2e_total number or null
The total amount of GHG emitted per unit of activity expressed as kgCO2e, as reported by the source. It is null for Climatiq-performed calculations.
co2e_other number or null
The total amount of GHG emitted that are not CO2, CH4 or N20 - expressed in kgCO2e emitted per unit of activity, as reported by the source.
co2 number or null
The amount of carbon dioxide (CO2) emitted per unit of activity expressed as kgCO2, as reported by the source.
ch4 number or null
The amount of methane (CH4) emitted per unit of activity expressed as kgCH4, as reported by the source.
n2o number or null
The amount of nitrous oxide (N2O) emitted per unit of activity expressed as kgN2O, as reported by the source.