Energy Endpoint version: V1V1 ADD-ONADD-ON
To see the changes since the preview versions, see our changelog
The energy endpoints automatically calculates the greenhouse gas emissions associated with the consumed energy based on relevant emission factors. These factors are determined based on the specific type of energy and the region where it is consumed, ensuring accurate carbon footprint calculations for your organization.
This feature can be used to help businesses estimate and report their scope 1, 2 and associated scope 3 emissions under the GHG Protocol. It also meets the requirements of the SBTi and covers market-based and location-based approaches for electricity use. The Energy Endpoint has passed a validation audit confirming compliance with the requirements of ISO 14067 and GHG Protocol - Product Life Cycle Accounting & Reporting Standard. Please see the Climatiq Trust page (opens in a new tab) for the document of conformity.
For extra information about our methodology for GHG Protocol scopes 2 and 3.3 calculation, please view the scope 2 and scope 3.3 FERA guides.
Electricity use
POST Calculate the estimated greenhouse gas emissions for electricity use, including both grid electricity and direct-line electricity. This endpoint allows you to obtain accurate carbon footprint calculations for your organization's purchased electricity.
By default the Electricity calculator uses publicly published emission factors from various official sources covering 63 countries. For greater coverage and consistency you also have the option to purchase a premium license to emission factors from the International Energy Agency (IEA) increasing coverage to 149 countries. Contact us (opens in a new tab)
https://api.climatiq.io/energy/v1/electricityRequest
This endpoint accepts the following parameters:
- regionrequired string
The region or country where the electricity was consumed, usually a country but could be US / Australian / Canadian state / province or US eGrid. A US zip code can be provided in the format
US-XXXXXor a UN/LOCODE in the formatXX-YYY. See also choosing a region below. - yearintegerDefault value: Latest year available
The year for which the greenhouse gas emissions are being calculated.
Default ValueLatest year available - Default ValueSum of the components
- recsEnergy object
Quantity of RECs (Renewable Energy Certificates) to apply.
- source_setstringDefault value:
"iea"if the API key used has access to the premium IEA dataset, otherwise"core"Specifies which set of emission factors the caller would like to use. Valid values are
coreorieaDefault Value"iea"if the API key used has access to the premium IEA dataset, otherwise"core" - componentsarray of Component objects
An array containing the different components of the electricity consumption and their associated details.
- allow_iea_provisionalbooleanDefault value:
false: no provisional IEA factors will be usedWhen using the IEA source, which requires an IEA license, you can choose whether you wish to use provisional factors from IEA where final factors are unavailable.
Default Valuefalse: no provisional IEA factors will be used
An implied residual component will be added to make up any difference between the total amount of energy in the request and the sum of the amount of energy in each component.
curl --request POST \ --url https://api.climatiq.io/energy/v1/electricity \ --header "Authorization: Bearer $CLIMATIQ_API_KEY" \ --data '{ "year": 2023, "region": "GB", "source_set": "core", "amount": { "energy": 5000, "energy_unit": "kWh" }, "recs": { "energy": 1000, "energy_unit": "kWh" }, "components": [ { "amount": { "energy": 1000, "energy_unit": "kWh" }, "connection_type": "grid", "supplier": "british_gas" }, { "amount": { "energy": 1000, "energy_unit": "kWh" }, "connection_type": "direct", "loss_factor": 0.05, "energy_source": "natural_gas" }, { "amount": { "energy": 1000, "energy_unit": "kWh" }, "connection_type": "direct", "energy_source": "renewable" } ]}'Response
The response includes estimates for the greenhouse gas emissions associated with electricity use.
- locationEnergy reporting quad
The estimates for greenhouse gas emissions based on the location of consumption.
- marketEnergy reporting quad
The estimates for greenhouse gas emissions based on market method (purchases).
- noticesarray of Notices
Any notices about deficiencies or peculiarities of the calculation.
{ "location": { "consumption": { "co2e": 1007, "co2e_unit": "kg", "co2e_calculation_method": "ipcc_ar6_gwp100", "source_trail": [ { "data_category": "emission_factor", "name": "Electricity supplied from grid", "source": "BEIS", "source_dataset": "Greenhouse gas reporting: conversion factors 2023", "year": "2023", "region": "GB", "region_name": "United Kingdom" }, { "data_category": "emission_factor", "name": "Natural gas - 100% mineral blend (net CV)", "source": "BEIS", "source_dataset": "Greenhouse gas reporting: conversion factors 2023", "year": "2023", "region": "GB", "region_name": "United Kingdom" }, { "data_category": "emission_factor", "name": "Renewables", "source": "Climatiq", "source_dataset": "Climatiq", "year": "2022", "region": "GLOBAL", "region_name": "Global" } ], "co2_biogenic": null, "constituent_gases": { "co2": 999.4, "ch4": 0.1169, "n2o": 0.01451 } }, "well_to_tank": { "co2e": 200.9, "co2e_unit": "kg", "co2e_calculation_method": "ipcc_ar5_gwp100", "source_trail": [ { "data_category": "emission_factor", "name": "Electricity supplied from grid", "source": "BEIS", "source_dataset": "Greenhouse gas reporting: conversion factors 2023", "year": "2023", "region": "GB", "region_name": "United Kingdom" }, { "data_category": "emission_factor", "name": "Natural gas - 100% mineral blend (net CV)", "source": "BEIS", "source_dataset": "Greenhouse gas reporting: conversion factors 2023", "year": "2023", "region": "GB", "region_name": "United Kingdom" }, { "data_category": "emission_factor", "name": "Renewables", "source": "Climatiq", "source_dataset": "Climatiq", "year": "2022", "region": "GLOBAL", "region_name": "Global" } ], "co2_biogenic": null, "constituent_gases": { "co2": null, "ch4": null, "n2o": null } }, "transmission_and_distribution": { "co2e": 74.07, "co2e_unit": "kg", "co2e_calculation_method": "ipcc_ar6_gwp100", "source_trail": [ { "data_category": "emission_factor", "name": "Electricity supplied from grid", "source": "BEIS", "source_dataset": "Greenhouse gas reporting: conversion factors 2023", "year": "2023", "region": "GB", "region_name": "United Kingdom" }, { "data_category": "emission_factor", "name": "Electricity supplied from grid: T&D losses", "source": "BEIS", "source_dataset": "Greenhouse gas reporting: conversion factors 2023", "year": "2023", "region": "GB", "region_name": "United Kingdom" }, { "data_category": "emission_factor", "name": "Natural gas - 100% mineral blend (net CV)", "source": "BEIS", "source_dataset": "Greenhouse gas reporting: conversion factors 2023", "year": "2023", "region": "GB", "region_name": "United Kingdom" }, { "data_category": "emission_factor", "name": "Renewables", "source": "Climatiq", "source_dataset": "Climatiq", "year": "2022", "region": "GLOBAL", "region_name": "Global" } ], "co2_biogenic": null, "constituent_gases": { "co2": 73.45, "ch4": 0.00941, "n2o": 0.001232 } }, "well_to_tank_of_transmission_and_distribution": { "co2e": 15.24, "co2e_unit": "kg", "co2e_calculation_method": "ipcc_ar5_gwp100", "source_trail": [ { "data_category": "emission_factor", "name": "Electricity supplied from grid", "source": "BEIS", "source_dataset": "Greenhouse gas reporting: conversion factors 2023", "year": "2023", "region": "GB", "region_name": "United Kingdom" }, { "data_category": "emission_factor", "name": "Electricity supplied from grid: T&D losses", "source": "BEIS", "source_dataset": "Greenhouse gas reporting: conversion factors 2023", "year": "2023", "region": "GB", "region_name": "United Kingdom" }, { "data_category": "emission_factor", "name": "Natural gas - 100% mineral blend (net CV)", "source": "BEIS", "source_dataset": "Greenhouse gas reporting: conversion factors 2023", "year": "2023", "region": "GB", "region_name": "United Kingdom" }, { "data_category": "emission_factor", "name": "Renewables", "source": "Climatiq", "source_dataset": "Climatiq", "year": "2022", "region": "GLOBAL", "region_name": "Global" } ], "co2_biogenic": null, "constituent_gases": { "co2": null, "ch4": null, "n2o": null } } }, "market": { "consumption": { "co2e": 889.6, "co2e_unit": "kg", "co2e_calculation_method": "ipcc_ar4_gwp100", "source_trail": [ { "data_category": "emission_factor", "name": "Electricity supplied from grid - residual mix", "source": "AIB", "source_dataset": "European Residual Mix", "year": "2023", "region": "GB", "region_name": "United Kingdom" }, { "data_category": "emission_factor", "name": "Electricity supplied from grid - supplier British Gas", "source": "Electricity Info", "source_dataset": "Fuel Mix of UK Domestic Electricity Suppliers", "year": "2022", "region": "GB", "region_name": "United Kingdom" }, { "data_category": "emission_factor", "name": "Natural gas - 100% mineral blend (net CV)", "source": "BEIS", "source_dataset": "Greenhouse gas reporting: conversion factors 2023", "year": "2023", "region": "GB", "region_name": "United Kingdom" }, { "data_category": "emission_factor", "name": "Renewables", "source": "Climatiq", "source_dataset": "Climatiq", "year": "2022", "region": "GLOBAL", "region_name": "Global" } ], "co2_biogenic": null, "constituent_gases": { "co2": 888.9, "ch4": null, "n2o": null } }, "well_to_tank": { "co2e": 148.9, "co2e_unit": "kg", "co2e_calculation_method": "ipcc_mixed_gwp100", "source_trail": [ { "data_category": "emission_factor", "name": "Electricity supplied from grid - residual mix", "source": "AIB", "source_dataset": "European Residual Mix", "year": "2023", "region": "GB", "region_name": "United Kingdom" }, { "data_category": "emission_factor", "name": "Electricity supplied from grid - supplier British Gas", "source": "Electricity Info", "source_dataset": "Fuel Mix of UK Domestic Electricity Suppliers", "year": "2022", "region": "GB", "region_name": "United Kingdom" }, { "data_category": "emission_factor", "name": "Natural gas - 100% mineral blend (net CV)", "source": "BEIS", "source_dataset": "Greenhouse gas reporting: conversion factors 2023", "year": "2023", "region": "GB", "region_name": "United Kingdom" }, { "data_category": "emission_factor", "name": "Renewables", "source": "Climatiq", "source_dataset": "Climatiq", "year": "2022", "region": "GLOBAL", "region_name": "Global" } ], "co2_biogenic": null, "constituent_gases": { "co2": null, "ch4": null, "n2o": null } }, "transmission_and_distribution": { "co2e": 74.07, "co2e_unit": "kg", "co2e_calculation_method": "ipcc_ar6_gwp100", "source_trail": [ { "data_category": "emission_factor", "name": "Electricity supplied from grid", "source": "BEIS", "source_dataset": "Greenhouse gas reporting: conversion factors 2023", "year": "2023", "region": "GB", "region_name": "United Kingdom" }, { "data_category": "emission_factor", "name": "Electricity supplied from grid: T&D losses", "source": "BEIS", "source_dataset": "Greenhouse gas reporting: conversion factors 2023", "year": "2023", "region": "GB", "region_name": "United Kingdom" }, { "data_category": "emission_factor", "name": "Natural gas - 100% mineral blend (net CV)", "source": "BEIS", "source_dataset": "Greenhouse gas reporting: conversion factors 2023", "year": "2023", "region": "GB", "region_name": "United Kingdom" }, { "data_category": "emission_factor", "name": "Renewables", "source": "Climatiq", "source_dataset": "Climatiq", "year": "2022", "region": "GLOBAL", "region_name": "Global" } ], "co2_biogenic": null, "constituent_gases": { "co2": 73.45, "ch4": 0.00941, "n2o": 0.001232 } }, "well_to_tank_of_transmission_and_distribution": { "co2e": 15.24, "co2e_unit": "kg", "co2e_calculation_method": "ipcc_ar5_gwp100", "source_trail": [ { "data_category": "emission_factor", "name": "Electricity supplied from grid", "source": "BEIS", "source_dataset": "Greenhouse gas reporting: conversion factors 2023", "year": "2023", "region": "GB", "region_name": "United Kingdom" }, { "data_category": "emission_factor", "name": "Electricity supplied from grid: T&D losses", "source": "BEIS", "source_dataset": "Greenhouse gas reporting: conversion factors 2023", "year": "2023", "region": "GB", "region_name": "United Kingdom" }, { "data_category": "emission_factor", "name": "Natural gas - 100% mineral blend (net CV)", "source": "BEIS", "source_dataset": "Greenhouse gas reporting: conversion factors 2023", "year": "2023", "region": "GB", "region_name": "United Kingdom" }, { "data_category": "emission_factor", "name": "Renewables", "source": "Climatiq", "source_dataset": "Climatiq", "year": "2022", "region": "GLOBAL", "region_name": "Global" } ], "co2_biogenic": null, "constituent_gases": { "co2": null, "ch4": null, "n2o": null } } }, "notices": [ { "severity": "info", "code": "recs_subtracted_market_generation", "message": "Market generation components were subtracted for RECs" }, { "severity": "warning", "code": "global_default_wtt_used", "message": "Calculating market well to tank emissions using a global average proportion of generation emissions, due to absence of an applicable emissions factor. For more accurate market well to tank emissions, explicitly provide a fuel mix." } ]}Choosing a region
Regions are currently only available where grid emission data is available. We plan to expand this coverage over time.
In countries where we have coverage, you can use a country-level region code to specify the country, or an extended region code to specify a subdivision, or a location within that subdivision.
In the US the preferred method is to use a zip code in the format US-XXXXX in order to most accurately choose both eGrid and state-based factors.
The suggested way to find available regions is to make a request without setting a region and see which ones are indicated as being available in the error response.
Request
curl --request POST \ --url https://api.climatiq.io/energy/v1/electricity \ --header "Authorization: Bearer $CLIMATIQ_API_KEY" \ --data '{ "region": "", "source_set": "core"}'Response
{ "error": "bad_request", "error_code": "no_location_found", "message": "The supplied region is not supported", "valid_values": { "region": [ "AE", "AR", "AT", "AU", "AU-ACT", "AU-NSW", "AU-NT", "AU-QLD", "AU-SA", "AU-TAS", "AU-VIC", "AU-WA", "BA", "BD", "BE", "BG", "BR", "CA", "CA-AB", "CA-BC", "CA-MB", "CA-NB", "CA-NL", "CA-NS", "CA-NT", "CA-NU", "CA-ON", "CA-QC", "CA-SK", "CA-YT", "CH", "CN", "CO", "CY", "CZ", "DE", "DK", "EE", "ES", "EU", "FI", "FR", "GB", "GR", "HR", "HU", "ID", "IE", "IN", "IS", "IT", "JP", "KR", "LT", "LU", "LV", "ME", "MT", "MX", "NG", "NL", "NO", "NP", "NZ", "PH", "PK", "PL", "PT", "RO", "RS", "RU", "SA", "SE", "SI", "SK", "TH", "TR", "US", "US-AK", "US-AKGD", "US-AKMS", "US-AL", "US-AR", "US-AZ", "US-AZNM", "US-CA", "US-CAMX", "US-CO", "US-CT", "US-DC", "US-DE", "US-ERCT", "US-FL", "US-FRCC", "US-GA", "US-HI", "US-HIMS", "US-HIOA", "US-IA", "US-ID", "US-IL", "US-IN", "US-KS", "US-KY", "US-LA", "US-MA", "US-MD", "US-ME", "US-MI", "US-MN", "US-MO", "US-MROE", "US-MROW", "US-MS", "US-MT", "US-NC", "US-ND", "US-NE", "US-NEWE", "US-NH", "US-NJ", "US-NM", "US-NV", "US-NWPP", "US-NY", "US-NYCW", "US-NYLI", "US-NYUP", "US-OH", "US-OK", "US-OR", "US-PA", "US-PR", "US-PRMS", "US-RFCE", "US-RFCM", "US-RFCW", "US-RI", "US-RMPA", "US-SC", "US-SD", "US-SPNO", "US-SPSO", "US-SRMV", "US-SRMW", "US-SRSO", "US-SRTV", "US-SRVC", "US-TN", "US-TX", "US-UT", "US-VA", "US-VT", "US-WA", "US-WI", "US-WV", "US-WY", "VN", "ZA" ] }}Choosing a supplier
Suppliers are currently only available in US states and in the United Kingdom. The suggested way to find available suppliers's is to make a request without setting a supplier (but setting amount and region) and see which suppliers are indicated as being available in the error response.
Request
curl --request POST \ --url https://api.climatiq.io/energy/v1/electricity \ --header "Authorization: Bearer $CLIMATIQ_API_KEY" \ --data '{ "region": "US-CA", "components": [ { "amount": { "energy": 0, "energy_unit": "kWh" }, "supplier": "" } ]}'Response
The available suppliers will depend on the region.
{ "error": "bad_request", "error_code": "invalid_input", "message": "No emission factors exist with the given supplier `` in the specified region. This error will contain the valid suppliers in the requested region.", "valid_values": { "supplier": [ "algonquin_power_and_utilities_corp_liberty_utilities", "edison_international_southern_california_edison", "pgande_corporation_pacific_gas_and_electric_company", "puget_sound_energy" ] }}Batch Electricity Use
POST For bulk data-processing, this endpoint has a batch endpoint variant allowing for up to 100 calculations with one API call.
The batch endpoint is available at:
https://api.climatiq.io/energy/v1/electricity/batchProvide this endpoint with an array of objects, where each object is a valid body for the non-batch endpoint. See the batch endpoint documentation for more information about how batch endpoints work and how to handle errors.
Heat and Steam use
POST Calculate the estimated greenhouse gas emissions for heat and steam use. This endpoint allows you to obtain accurate carbon footprint calculations for your organization's purchased heat and steam.
https://api.climatiq.io/energy/v1/heatRequest
This endpoint accepts the following parameters:
- regionrequired string
The country where the heat and steam was consumed.
- componentsrequired array of Component objects
An array containing the different components of the heat and steam consumption and their associated details.
Each component within thecomponentsarray corresponds to a purchase of heat and steam under some contract, it should include the following parameters: (outside of DE / GB / US, either theenergy_sourceor theco2e_kg_per_kwhmust be provided)The total heat and steam purchased
components[x].co2e_kg_per_kwhfloatContract emission factor for the component in kg per kWh
components[x].energy_sourcestringThe source that the heat is generated from. Valid values are
renewableor specific fuel types such asnatural_gas,coal,biomasscomponents[x].loss_factorfloat or stringDefault value:mediumThe distribution loss factor for this component. Can either be a number or one of the strings
"low","medium"or"high"Default Valuemedium - yearintegerDefault value: Latest year available
The year for which the greenhouse gas emissions are being calculated.
Default ValueLatest year available
curl --request POST \ --url https://api.climatiq.io/energy/v1/heat \ --header "Authorization: Bearer $CLIMATIQ_API_KEY" \ --data '{ "year": 2021, "region": "DE", "components": [ { "amount": { "energy": 1000, "energy_unit": "kWh" }, "loss_factor": 0.06 }, { "amount": { "energy": 1000, "energy_unit": "kWh" }, "loss_factor": 0.1, "energy_source": "natural_gas" }, { "amount": { "energy": 1000, "energy_unit": "kWh" }, "energy_source": "renewable" } ]}'Response
The response includes estimates for the greenhouse gas emissions associated with heat and steam use.
- estimatesEnergy reporting quad
The estimates for greenhouse gas emissions.
- noticesarray of Notices
Any notices about deficiencies or peculiarities of the calculation.
{ "estimates": { "consumption": { "co2e": 479.9, "co2e_unit": "kg", "co2e_calculation_method": "ipcc_ar6_gwp100", "source_trail": [ { "data_category": "emission_factor", "name": "District heating", "source": "UBA", "source_dataset": "Emissionsbilanz erneuerbarer Energietraeger", "year": "2021", "region": "DE", "region_name": "Germany" }, { "data_category": "emission_factor", "name": "Natural gas - 100% mineral blend (net CV)", "source": "BEIS", "source_dataset": "Greenhouse gas reporting: conversion factors 2021", "year": "2021", "region": "GB", "region_name": "United Kingdom" }, { "data_category": "emission_factor", "name": "Renewables", "source": "Climatiq", "source_dataset": "Climatiq", "year": "2022", "region": "GLOBAL", "region_name": "Global" } ], "co2_biogenic": null, "constituent_gases": { "co2": 475.9, "ch4": 0.08444, "n2o": 0.00541 } }, "well_to_tank": { "co2e": 78.89, "co2e_unit": "kg", "co2e_calculation_method": "ipcc_ar4_gwp100", "source_trail": [ { "data_category": "emission_factor", "name": "District heating", "source": "UBA", "source_dataset": "Emissionsbilanz erneuerbarer Energietraeger", "year": "2021", "region": "DE", "region_name": "Germany" }, { "data_category": "emission_factor", "name": "Natural gas - 100% mineral blend (net CV)", "source": "BEIS", "source_dataset": "Greenhouse gas reporting: conversion factors 2021", "year": "2021", "region": "GB", "region_name": "United Kingdom" }, { "data_category": "emission_factor", "name": "Renewables", "source": "Climatiq", "source_dataset": "Climatiq", "year": "2022", "region": "GLOBAL", "region_name": "Global" } ], "co2_biogenic": null, "constituent_gases": { "co2": null, "ch4": null, "n2o": null } }, "transmission_and_distribution": { "co2e": 41.37, "co2e_unit": "kg", "co2e_calculation_method": "ipcc_ar6_gwp100", "source_trail": [ { "data_category": "emission_factor", "name": "District heating", "source": "UBA", "source_dataset": "Emissionsbilanz erneuerbarer Energietraeger", "year": "2021", "region": "DE", "region_name": "Germany" }, { "data_category": "emission_factor", "name": "Natural gas - 100% mineral blend (net CV)", "source": "BEIS", "source_dataset": "Greenhouse gas reporting: conversion factors 2021", "year": "2021", "region": "GB", "region_name": "United Kingdom" }, { "data_category": "emission_factor", "name": "Renewables", "source": "Climatiq", "source_dataset": "Climatiq", "year": "2022", "region": "GLOBAL", "region_name": "Global" } ], "co2_biogenic": null, "constituent_gases": { "co2": 41.09, "ch4": 0.005978, "n2o": 0.0003647 } }, "well_to_tank_of_transmission_and_distribution": { "co2e": 6.861, "co2e_unit": "kg", "co2e_calculation_method": "ipcc_ar4_gwp100", "source_trail": [ { "data_category": "emission_factor", "name": "District heating", "source": "UBA", "source_dataset": "Emissionsbilanz erneuerbarer Energietraeger", "year": "2021", "region": "DE", "region_name": "Germany" }, { "data_category": "emission_factor", "name": "Natural gas - 100% mineral blend (net CV)", "source": "BEIS", "source_dataset": "Greenhouse gas reporting: conversion factors 2021", "year": "2021", "region": "GB", "region_name": "United Kingdom" }, { "data_category": "emission_factor", "name": "Renewables", "source": "Climatiq", "source_dataset": "Climatiq", "year": "2022", "region": "GLOBAL", "region_name": "Global" } ], "co2_biogenic": null, "constituent_gases": { "co2": null, "ch4": null, "n2o": null } } }}Batch Heat and Steam Use
POST For bulk data-processing, this endpoint has a batch endpoint variant allowing for up to 100 calculations with one API call.
The batch endpoint is available at:
https://api.climatiq.io/energy/v1/heat/batchProvide this endpoint with an array of objects, where each object is a valid body for the non-batch endpoint. See the batch endpoint documentation for more information about how batch endpoints work and how to handle errors.
Fuel Use
POST Calculate the estimated greenhouse gas emissions for fuel combustion.
https://api.climatiq.io/energy/v1/fuelRequest
The request to the fuel combustion endpoint accepts the following parameters included in the request body. Except for fuel_type and amount, which must match exactly, any parameters that cannot be matched to an emission factor will be ignored, e.g. this means that the emission factors might be for a different region than you selected. In the event of a mismatch, a notice will be included in the response.
- fuel_typerequired string
The type of fuel burned. See choosing a
fuel_typefor how to choose this. - regionstring
The region or country where the fuel was burned.
- yearintegerDefault value: Latest year available
The year in which the fuel was burned.
Default ValueLatest year available
curl --request POST \ --url https://api.climatiq.io/energy/v1/fuel \ --header "Authorization: Bearer $CLIMATIQ_API_KEY" \ --data '{ "fuel_type": "biodiesel_bio_100", "amount": { "volume": 5000, "volume_unit": "l" }, "region": "GB", "year": 2023}'Response
The response includes estimates for the greenhouse gas emissions associated with fuel combustion.
- combustionEnergy estimate
Estimate of emissions from fuel combustion
- well_to_tankEnergy estimate
Estimate of upstream emissions. (This could be empty in cases where we can't estimate the WTT but can estimate the combustion, a notice will be included in this case)
- noticesarray of Notices
Any notices about deficiencies or peculiarities of the calculation.
{ "combustion": { "co2e": 837.6, "co2e_unit": "kg", "co2e_calculation_method": "ipcc_ar5_gwp100", "source_trail": [ { "data_category": "emission_factor", "name": "Off road biodiesel", "source": "BEIS", "source_dataset": "Greenhouse gas reporting: conversion factors 2023", "year": "2023", "region": "GB", "region_name": "United Kingdom" } ], "co2_biogenic": 11950, "constituent_gases": { "co2": null, "ch4": null, "n2o": null } }, "well_to_tank": { "co2e": 2238, "co2e_unit": "kg", "co2e_calculation_method": "ipcc_ar5_gwp100", "source_trail": [ { "data_category": "emission_factor", "name": "Off road biodiesel", "source": "BEIS", "source_dataset": "Greenhouse gas reporting: conversion factors 2023", "year": "2023", "region": "GB", "region_name": "United Kingdom" } ], "co2_biogenic": null, "constituent_gases": { "co2": null, "ch4": null, "n2o": null } }, "notices": []}Choosing a fuel_type
The suggested way to find the available fuel_types is to make a request without setting the fuel_type (but setting amount and region) and see which fuel_types are indicated as being available in the error response. region can also be omitted to see all fuel_types available globally.
Request
curl --request POST \ --url https://api.climatiq.io/energy/v1/fuel \ --header "Authorization: Bearer $CLIMATIQ_API_KEY" \ --data '{ "amount": { "weight": 0, "weight_unit": "g" }, "region": "US"}'Response
The available fuel_types will depend on the unit and region.
{ "error": "bad_request", "error_code": "invalid_input", "message": "No emission factors exist with the given fuel type. This error will contain the valid fuel types for the provided unit type and for this region.", "valid_values": { "fuel_type": [ "agricultural_byproducts_bio_100", "coal_and_coke_mixed", "coal_anthracite", "coal_bituminous", "coal_coke", "coal_lignite", "coal_sub_bituminous", "peat_bio_100", "petroleum_coke", "plastics", "solid_byproducts", "tires", "waste_solid_municipal", "wood_and_wood_residuals_bio_100" ] }}Batch Fuel Use
POST For bulk data-processing, this endpoint has a batch endpoint variant allowing for up to 100 calculations with one API call.
The batch endpoint is available at:
https://api.climatiq.io/energy/v1/fuel/batchProvide this endpoint with an array of objects, where each object is a valid body for the non-batch endpoint. See the batch endpoint documentation for more information about how batch endpoints work and how to handle errors.
Response models
Response formats shared between the above endpoints.
Energy reporting quad
For electricity (market and location) and heat and steam, the API reports 4 estimates, one for scope 2 (consumption) emissions and each of the 3 scope 3.3 (FERA) emissions estimates:
| Attribute | Type | Description |
|---|---|---|
| consumption | Energy estimate | Estimates of the greenhouse gas emissions that result from generating the consumed energy. |
| transmission_and_distribution | Energy estimate | Estimates of the greenhouse gas emissions that result from generating the energy which is subsequently lost during the processes of transmission and distribution. |
| well_to_tank | Energy estimate | Estimates of the greenhouse gas emissions that result from obtaining the fuel used for generating the consumed energy. |
| well_to_tank_of_transmission_and_distribution | Energy estimate | Estimates of the greenhouse gas emissions that result from obtaining the fuel used for generating the energy which is subsequently lost during the processes of transmission and distribution. |
Energy estimate
- co2efloat
The total greenhouse gas emissions associated with the consumed energy, expressed in kilograms (kg).
- co2e_unitstring
The unit in which the CO2e field is expressed. The value of this is always
kg - co2e_calculation_methodstring
Which calculation methodology that was used for the calculation. The value of this is either
"ipcc_ar4_gwp100","ipcc_ar5_gwp100","ipcc_ar6_gwp100"or"ipcc_mixed_gwp100". Learn more about calculation methods here. - source_trailarray of Source Data Points
An array of data points that help explain and provide trust in the calculation. Click to view more details about Source Trail.
- co2_biogenicfloat or null
The biogenic CO2 emissions associated with the consumed energy, expressed in kilograms (kg). This is not included in the
co2etotal. - constituent_gasesEnergy constituent gases or null
Breakdown of the main 3 greenhouse gases which constitute the co2e estimate, they may not sum to the whole co2e value in the case of other, non-itemized gases. A
nullmeans the emission factor used only provided co2e without a constituent gase breakdown.
Our older calculation endpoints always return the Estimation model which gives information about the emission
factor that was used in the calculation and how it was applied, but we haven't implemented that
for our newest features. This is because the complexity of the calculations performed by our new
emissions calculators means that we are unable to explain the calculations adequately using the
estimation model. Below are the new features which replace the Estimation model and which we are
trialing on the Energy feature. If you have some requirements for calculation transparency
please get in contact (opens in a new tab).
Constituent Gases
| Attribute | Type | Description |
|---|---|---|
| co2 | number | Estimation of kg of CO2 emissions for the activity |
| ch4 | number | Estimation of kg of CH4 emissions for the activity |
| n2o | number | Estimation of kg of N2O emissions for the activity |
Notice
The notices array can contain objects like these:
| Notice attributes | Type | Description |
|---|---|---|
| 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 machine-readable categorization of the notice to allow automatic handling. |
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:
For Electricity
| Notice code value | description |
|---|---|
supplier_mix_used_for_residual | Unable to find a residual mix factor for the requested region, the supplier mix will be used instead, this will likely result in underestimating this portion of the energy usage. |
global_default_wtt_used | Applying a global default well to tank percentage due to absence of an applicable emissions factor. For more accurate market well to tank emissions, explicitly provide a fuel mix. |
ignored_parameter | A parameter in the request was ignored in favor of some more precise piece of data |
recs_subtracted_market_generation | Market components were subtracted for recs |
recs_subtracted_market_transmission_and_distribution | Market T&D components were subtracted for recs |
provisional_emission_factor_used | A provisional EF was used; the result may be inconsistent with, and significantly different from, results that use a final EF. If you don't want to use provisional EFs from IEA, add the flag "use_provisional_iea": false to your request |
For Fuel Combustion
| Notice code value | description |
|---|---|
no_region_match | A different region was selected as the requested region was not available for the selected fuel type and unit. |
wtt_not_estimated | Failed to estimate well to tank: a WTT factor wasn't found with the requested fuel type. |