Skip to Content
API ReferenceSearch

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.

    • 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.

    • results_per_pageinteger
      Default value: 20

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

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": 7,
    "total_results": 7,
    "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": [
            "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. 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_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_flagsstring

      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 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.

A null means the constituent gas may or may not be present, but the source does not split it out from the co2e total.

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. This is the methane not included in the ch4_fossil or ch4_biogenic fields.
ch4_fossil number or null
The amount of methane (CH4) from fossil sources (e.g. fugitive emissions from fossil fuels) emitted per unit of activity expressed as kgCH4, as reported by the source.
ch4_biogenic number or null
The amount of methane (CH4) from biogenic sources 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.

Additional Indicators

Additional indicators provide supplementary data beyond the core CO2e estimate, such as scope breakdowns for spend-based EFs and the fossil / biogenic / land-use-change split that makes up the headline CO2e. All fields are optional, as not all emission factors have additional indicator data. If an EF does not have data for a specific indicator, its field will be omitted from the response. If no additional indicators are available for an EF, additional_indicators will be empty ({}).

The flag_co2e and land_management_co2e indicators are only returned when your account has the FLAG feature enabled; contact us if you need access.

Attribute
scope1 number
Scope 1 emissions for spend-based EFs, expressed in kgCO2e per unit of activity.
scope2 number
Scope 2 emissions for spend-based EFs, expressed in kgCO2e per unit of activity.
scope3 number
Scope 3 emissions for spend-based EFs, expressed in kgCO2e per unit of activity.
fossil_co2e number
Net fossil CO2e per unit of activity (kgCO2e) — the portion of the total CO2e attributable to fossil-origin emissions. A component of the headline co2e.
biogenic_neutral_co2e number
Net biogenic CO2e per unit of activity (kgCO2e) under the neutral accounting method (the biogenic CH4/N2O contributions; biogenic CO2 itself is treated as 0). May be negative when net removals dominate. A component of the headline co2e.
luc_co2e number
Net land-use-change CO2e per unit of activity (kgCO2e), capturing emissions and removals from land use and land-use change. May be negative. A component of the headline co2e.
total_neutral_co2e number
Total CO2e per unit of activity (kgCO2e) under the neutral accounting method (fossil_co2e + biogenic_neutral_co2e + luc_co2e).
flag_co2e number
Forest, Land and Agriculture (FLAG) CO2e per unit of activity (kgCO2e). Requires the FLAG feature.
land_management_co2e number
Land management CO2e per unit of activity (kgCO2e). Requires the FLAG feature.

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 valuedescription
premium_data_availableYour query returned no results, but there is premium data available that would have resulted in matches.
Last updated on
ErrorsUnit Types