Search Endpoint version: V1V1

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, and 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 headersRequired HTTP headers for this request

Authorizationrequired string
Bearer token containing your Climatiq API key. Example: Authorization: Bearer CLIMATIQ_API_KEY
Don't have an API key? Get your API key here.

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
scopestring
Filters by scope, such as 1, 2, 3.1, 3.2, etc. Scope 3 categories can be explicitly stated (such as 3.1) or all Scope 3 categories can be selected by specifying 3.
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 unit category (e.g., "Weight", "Energy", "Volume", "Money"). See unit types endpoint for all available types.
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
Default value: View defaults
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
View defaults
access_typestring
Filters by the access type of the emission factors. Allowed values are public, private and premium
pageinteger
Default value: 1
Which page of results to retrieve.
Default Value
1
results_per_pageinteger
Default value: 20
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=^21&year=2021&results_per_page=1' \
  --header "Authorization: Bearer $CLIMATIQ_API_KEY" \

Response

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

Response parameters

resultsarray of SearchResult
An ordered array of SearchResult that explains each emission factor that matches the search result, from best to worst match
current_pagenumber
The current page you have retrieved.
last_pagenumber
The last page that there are results for.
total_resultsnumber
How many results there are in total across all pages.
possible_filtersobject
A list of potential filters you can use to further narrow down your query. See below.
noticesarray of Notice
Lists any notices that are relevant for understanding the result.


{
    "current_page": 1,
    "last_page": 53,
    "total_results": 53,
    "results": [
        {
            "id": "e4256fa1-9527-42de-a46d-477f2c1bbb3f",
            "activity_id": "commercial_vehicle-vehicle_type_truck_light-fuel_source_na-engine_size_na-vehicle_age_na-vehicle_weight_na",
            "name": "Light-Duty Truck",
            "sector": "Transport",
            "category": "Vehicles",
            "source": "EPA",
            "source_dataset": "2021 GHG Emission Factors Hub",
            "source_link": "https://www.epa.gov/climateleadership/ghg-emission-factors-hub",
            "source_lca_activity": "use_phase",
            "year": 2021,
            "year_released": 2021,
            "region": "US",
            "region_name": "United States of America (the)",
            "unit_type": "Distance",
            "unit": "kg/mile",
            "supported_calculation_methods": [
                "ar4",
                "ar5",
                "ar6"
            ],
            "factor": 0.467054,
            "factor_calculation_method": "ar6",
            "factor_calculation_origin": "climatiq",
            "constituent_gases": {
                "co2e_total": null,
                "co2e_other": null,
                "co2": 0.464,
                "ch4": 0.000012,
                "ch4_fossil": null,
                "ch4_biogenic": null,
                "n2o": 0.00001
            },
            "additional_indicators": {},
            "data_version": {
                "status": "up_to_date"
            },
            "data_version_information": {
                "status": "up_to_date"
            },
            "scopes": [
                "3.4",
                "3.6",
                "3.7",
                "3.9"
            ],
            "uncertainty": null,
            "description": "Emission intensity of light duty truck (includes full-size pickup trucks/full-size vans/extended-length SUVs with wheelbase greater than 121 inches). Retrieved from the EPA's GHG Emission Factors Hub (xlsx).",
            "data_quality_flags": [],
            "access_type": "public"
        }
    ],
    "possible_filters": {
        "year": [
            2021
        ],
        "source": [
            {
                "source": "EPA",
                "datasets": [
                    "2021 GHG Emission Factors Hub"
                ]
            },
            {
                "source": "GHG Protocol",
                "datasets": [
                    "GHG Emissions Calculation Tool"
                ]
            },
            {
                "source": "OpenIO-Canada",
                "datasets": [
                    "OpenIO v2.11"
                ]
            }
        ],
        "region": [
            {
                "id": "CA-ON",
                "name": "Ontario, CA"
            },
            {
                "id": "US",
                "name": "United States of America (the)"
            }
        ],
        "category": [
            "Fuel",
            "Vehicles"
        ],
        "scope": [
            "1",
            "3.2",
            "3.4",
            "3.6",
            "3.7",
            "3.9"
        ],
        "sector": [
            "Energy",
            "Transport"
        ],
        "unit_type": [
            "Distance",
            "Money",
            "Volume"
        ],
        "source_lca_activity": [
            "cradle_to_gate",
            "cradle_to_gate_inc_capital_endogenization",
            "fuel_combustion",
            "use_phase"
        ],
        "access_type": [
            "public"
        ],
        "data_quality_flags": [
            "partial_factor",
            "notable_methodological_variance"
        ]
    },
    "notices": []
}

Search Result

This table describes the object that is returned inside the results array.

Search Result object

idstring
The unique ID describing this particular emission factor.
activity_idstring
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.
namestring
Emission factor name.
sectorstring
Emission factor sector.
categorystring
Emission factor category.
sourcestring
Emission factor publisher.
source_datasetstring
The dataset the source published this emission factor in.
source_linkstring
Link to emission factor publisher.
source_lca_activitystring
Which LCA activity the emission factor corresponds to. Read more about life cycle assessments here.
yearnumber
The year in which the emission factor is considered most relevant, according to the source.
year_releasednumber
The year in which the emission factor was released by the source.
regionstring
A region code describing the geographic region to which the emission factor applies.
region_namestring
Geographic region to which the emission factor applies (in English).
unitstring
The unit in which the factor field is expressed. This is the unit that the emission factor was published with, e.g. kg/room-night means "kg of CO2e emitted per night spent in a hotel room". For more details see here.
unit_typestring
The Unit types that this emission factor accepts.
supported_calculation_methodsarray of strings
The methods of CO2e calculation supported for this emission factor.
factornumber 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. If you do not have this add-on, this value is null. 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_gasesconstituent gases
Indicates which gases the CO2e emission factor is composed of.
additional_indicatorsadditional indicators
Supplementary indicator data such as scope breakdowns for spend-based EFs. May be empty ({}) if no additional indicator data is available.
data_versiondata version information
Gives relevant data version information about this emission factor, such as if it has a newer version available, or has been deprecated.
data_version_informationobject
This field is deprecated and should not be used. Refer to the data_version field instead.
scopesarray of strings
A list of applicable emission factor scopes. If multiple scopes are provided, this means the emission factor can be accounted for under different scopes depending on context. A small number of emission factors may cover combined emissions across several scopes, in which case the scopes field will be ["combined_scopes"]. Information about combined scopes will be provided in a later release of the API.
uncertaintynumber or null
Emission factor uncertainty factor (%).
descriptionstring
Emission factor description.
data_quality_flagsarray of strings
A list of data quality flags that this factor has. For more information about how data quality flags work and what to look out for, see here for more information about data quality
access_typestring
Whether or not the data is publicly available or private to your project. Can be either public, premium or private. Public emission factors are available to all, premium factors require a separate license, and private emission factors are only accessible to you.

`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 a region code that describes the different regions emission factors can apply to 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.

The values of scope can be used to further narrow search results by scope. Only scopes which narrow the query are listed here. If the original query was filtered by a set of scopes, then scopes unrelated to the original query will not be listed.

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 the CO2e emission factor is composed of. The calculation methodology used for these values is shown as factor_calculation_method in each search result.

For the full list of fields, see Constituent Gases.

Additional Indicators

See Additional Indicators for the list of indicators, including the scope breakdown, the fossil / biogenic / land-use-change split, and the FLAG fields.

Data Version Information

The data_version object explains whether this emission factor has been modified in a later data version. The object contains a status field that contains one of three string values:

up_to_date: This is the latest version of this emission factor. If this is the case, the data_version object will not contain any additional information.
replaced: There is a more recent emission factor available. Note that if an emission factor has been replaced multiple times this will give information about the next emission factor in the chain, not the most current one. The following fields are also available:
- replaced_in will provide the data release where this emission factor has been replaced.
- replaced_by will provide the ID of the newer version of the emission factor that replaced it time throughout data versions, this will give information about the next emission factor in the chain, not the most current one.
removed: This emission factor has been removed in a newer data release, without being replaced by something else. The following field is also available:
- removed_in will list the data release where this emission factor was removed.

Notice

The notices array can contain these objects:

Notice attributes
severity string Either `warning` or `info`. `warning` is for messages that might lead to inaccurate calculations. You should check these to make sure the results are fit for your intended purpose. `info` is for information that will help you understand the calculation result better.
message string An explanation of the notice.
code string A programmatic value you can use to disambiguate the different notice types.

The different possible values for code are as follows. You should not treat this list as exhaustive as more values may be added with time:

Notice code value	description
`premium_data_available`	Your query returned no results, but there is premium data available that would have resulted in matches.