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

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 $CLIMATIQ_API_KEY" \

Response

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

{
    "current_page": 1,
    "last_page": 3,
    "total_results": 3,
    "results": [
        {
            "activity_id": "commercial_vehicle-vehicle_type_truck_light-fuel_source_na-engine_size_na-vehicle_age_na-vehicle_weight_na",
            "id": "05d034db-dfe7-462e-9a19-a69ecd65a114",
            "name": "Light-Duty Truck",
            "category": "Vehicles",
            "sector": "Transport",
            "source": "EPA",
            "source_link": "https://www.epa.gov/climateleadership/ghg-emission-factors-hub",
            "source_dataset": "GHG Emission Factors Hub",
            "uncertainty": null,
            "year": 2021,
            "year_released": 2021,
            "region": "US",
            "region_name": "United States of America (the)",
            "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).",
            "unit_type": "Distance",
            "unit": "kg/mile",
            "source_lca_activity": "use_phase",
            "data_quality_flags": [],
            "access_type": "public",
            "supported_calculation_methods": [
                "ar4",
                "ar5",
                "ar6"
            ],
            "factor": 0.4671,
            "factor_calculation_method": "ar6",
            "factor_calculation_origin": "climatiq",
            "constituent_gases": {
                "co2e_total": null,
                "co2e_other": null,
                "co2": 0.464,
                "ch4": 0.000012,
                "n2o": 0.00001
            },
            "data_version": {
                "status": "up_to_date"
            },
            "data_version_information": {
                "status": "up_to_date"
            }
        }
    ],
    "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 of America (the)"
            }
        ],
        "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

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.