Energy ADD-ONADD-ON
The energy endpoints automatically calculate 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.
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 ALPHAALPHA
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.
POST /energy/electricity
Request
The request to the electricity use endpoint requires the following parameters to be included in the request body:
Parameter | Type | Description | Required | Default |
---|---|---|---|---|
region | string | The region or country where the electricity was consumed, usually a country but could be US state / US eGrid / Canadian province . | required | |
year | number | The year for which the greenhouse gas emissions are being calculated. | optional | Latest available |
amount | Unit type Energy | The total electricity used. | optional | Sum of the components |
recs | Unit type Energy | Quantity of RECs (Renewable Energy Certificates) to apply. | optional | 0 |
components | [Component] (See below) | An array containing the different components of the electricity consumption and their associated details. | optional | [] |
Each component within the components array
corresponds to a particular supply (under a particular contract or otherwise) of electricity to the user; it should include the following parameters:
Parameter | Type | Description | Required | Default |
---|---|---|---|---|
amount | Unit type Energy | The total electricity used via the supply contract. | required | |
connection_type | string | Either the electricity was delivered via the grid or via a direct line. | optional | grid |
supplier | string | Available where the region is GB or a US state, a supplier ID can be provided to use market factors for that supplier. | optional | |
co2e_kg_per_kwh | number | Contract emission factor for the component in kg per kWh | optional | |
energy_source | string | The source that electricity is generated from. Valid values are renewable or specific fuel types such as natural_gas , coal , biomass , nuclear . | optional | |
loss_factor | number | Some energy is lost during the transmission and distribution of the electricity. If you know this loss factor for the component, you can specify it here. | optional | Default for the region, regional losses range from 0.01 to 0.3. |
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.
Example request:
POST /energy/electricity
{ "year": 2023, "region": "GB", "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.
Attribute | Type | |
---|---|---|
location | Energy reporting quad | The estimates for greenhouse gas emissions based on the location of consumption. |
market | Energy reporting quad | The estimates for greenhouse gas emissions based on market method (purchases). |
notices | [Notice] | Any notices about deficiencies or peculiarities of the calculation. |
Example response:
{ "location": { "consumption": { "co2e": 945.951623246493, "co2e_unit": "kg" }, "well_to_tank": { "co2e": 201.0746492985972, "co2e_unit": "kg" }, "transmission_and_distribution": { "co2e": 71.34987197313546, "co2e_unit": "kg" }, "well_to_tank_of_transmission_and_distribution": { "co2e": 15.80623246492986, "co2e_unit": "kg" } }, "market": { "consumption": { "co2e": 906.8116232464929, "co2e_unit": "kg" }, "well_to_tank": { "co2e": 191.7136760852349, "co2e_unit": "kg" }, "transmission_and_distribution": { "co2e": 71.34987197313546, "co2e_unit": "kg" }, "well_to_tank_of_transmission_and_distribution": { "co2e": 15.80623246492986, "co2e_unit": "kg" } }, "notices": [ { "message": "Applying regional well to tank percentage to the market factor for named supplier 'british_gas', for a more accurate WTT, provide a fuel mix.", "code": "general_wtt_used_for_specific_factor", "severity": "warning" }, { "message": "Market generation components were subtracted for RECs", "code": "recs_subtracted_market_generation", "severity": "info" } ]}
Heat and Steam use ALPHAALPHA
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.
POST /energy/heat
Request
The request to the Heat and Steam use endpoint requires the following parameters to be included in the request body:
Parameter | Type | Description | Required | Default |
---|---|---|---|---|
year | number | The year for which the greenhouse gas emissions are being calculated. | optional | Latest available |
region | string | The country where the heat and steam was consumed. | required | |
components | [Component] (See below) | An array containing the different components of the heat and steam consumption and their associated details. | required |
Each component within the components
array corresponds to a purchase of heat and steam under some contract, it should include the following parameters: (outside of DE / GB / US, either the energy_source
or the co2e_kg_per_kwh
must be provided)
Parameter | Type | Description | Required | Default |
---|---|---|---|---|
amount | Unit type Energy | The total heat and steam purchased | required | |
co2e_kg_per_kwh | number | Contract emission factor for the component in kg per kWh | optional | |
energy_source | string | The source that the heat is generated from. Valid values are renewable or specific fuel types such as natural_gas , coal , biomass , nuclear | optional | |
loss_factor | number, "low", "medium" or "high" | The distribution loss factor for this component. | optional | "medium" |
Example request:
POST /energy/heat
{ "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.
Attribute | Type | |
---|---|---|
estimates | Energy reporting quad | The estimates for greenhouse gas emissions. |
notices | [Notice] | Any notices about deficiencies or peculiarities of the calculation. |
Example response:
{ "estimates": { "consumption": { "co2e": 537.7841082164329, "co2e_unit": "kg" }, "well_to_tank": { "co2e": 94.35565130260521, "co2e_unit": "kg" }, "transmission_and_distribution": { "co2e": 46.94921082164328, "co2e_unit": "kg" }, "well_to_tank_of_transmission_and_distribution": { "co2e": 8.17436513026052, "co2e_unit": "kg" } }, "notices": []}
Fuel Use ALPHAALPHA
POST Calculate the estimated greenhouse gas emissions for fuel combustion.
POST /energy/fuel
Request
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. In the event of a mismatch, a notice will be included in the response.
Parameter | Type | Description | Required | Default |
---|---|---|---|---|
fuel_type | string | The type of fuel burned. See choosing a fuel_type for how to choose this. | required | |
amount | Unit type Energy/Volume/Weight | The amount of fuel burned. | required | |
region | string | The region or country where the fuel was burned. | required | |
fuel_use | string | The use for the fuel, if known. | optional | |
year | number | The year in which the fuel was burned. | optional | Latest available |
Example request:
POST /energy/fuel
{ "fuel_type": "diesel_biofuel_blend", "amount": { "volume": 5000, "volume_unit": "l" }, "region": "GB", "year": 2023}
Response
The response includes estimates for the greenhouse gas emissions associated with fuel combustion.
Attribute | Type | |
---|---|---|
combustion | Energy estimate | Estimate of emissions from fuel combustion |
well_to_tank | Energy 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) |
notices | [Notice] | Any notices about deficiencies or peculiarities of the calculation. |
Example response:
{ "combustion": { "co2e": 12789.2, "co2e_unit": "kg" }, "well_to_tank": { "co2e": 3049.2999999999997, "co2e_unit": "kg" }, "notices": []}
Choosing a fuel_type
fuel_type
's don't currently follow the same naming convention across regions. 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_type
s are indicated as being available in the error response.
Request
Example request:
POST /energy/fuel
{ "amount": { "weight": 0, "weight_unit": "g" }, "region": "US"}
Response
The available fuel_type
s 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", "anthracite_coal", "bituminous_coal", "coal_coke", "lignite_coal", "mixed_commercial_sector", "mixed_electric_power_sector", "mixed_industrial_coking", "mixed_industrial_sector", "municipal_solid_waste", "peat", "petroleum_coke_solid", "plastics", "solid_byproducts", "sub_bituminous_coal", "tires", "wood_and_wood_residuals" ] }}
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
Attribute | Type | Description |
---|---|---|
co2e | number | The total greenhouse gas emissions associated with the consumed energy, expressed in kilograms (kg). |
co2e_unit | string | The unit of measurement for greenhouse gas emissions, which is "kg" (kilograms). |
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
existing model. We are working on a new method to explain our calculations which will offer more
transparency and usability. If you have some requirements for calculation transparency please
get in contact (opens in a new tab).
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 categorisation 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:
Notice code value | description |
---|---|
supplier_mix_used_for_residual | A grid mix factor was used in place of a residual factor, this will lead to an underestimated market estimate. |
general_wtt_used_for_specific_factor | The generic regional WTT% was used for a specific market factor, an energy_source should be provided for a better WTT estimate |
ignored_parameter | A parameter in the request was ignored in favour 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 |
no_region_match | The requested region was not matched |
no_fuel_use_match | The requested fuel_use was not matched |
wtt_not_estimated | Error when trying to estimate WTT, WTT estimate will be empty |