API Reference
Energy

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:

ParameterTypeDescriptionRequiredDefault
regionstringThe region or country where the electricity was consumed, usually a country but could be US state / US eGrid / Canadian province .required
yearnumberThe year for which the greenhouse gas emissions are being calculated.optionalLatest available
amountUnit type EnergyThe total electricity used.optionalSum of the components
recsUnit type EnergyQuantity of RECs (Renewable Energy Certificates) to apply.optional0
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:

ParameterTypeDescriptionRequiredDefault
amountUnit type EnergyThe total electricity used via the supply contract.required
connection_typestringEither the electricity was delivered via the grid or via a direct line.optionalgrid
supplierstringAvailable 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_kwhnumberContract emission factor for the component in kg per kWhoptional
energy_sourcestringThe source that electricity is generated from. Valid values are renewable or specific fuel types such as natural_gas, coal, biomass, nuclear.optional
loss_factornumberSome 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.optionalDefault 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.

AttributeType
locationEnergy reporting quadThe estimates for greenhouse gas emissions based on the location of consumption.
marketEnergy reporting quadThe 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:

ParameterTypeDescriptionRequiredDefault
yearnumberThe year for which the greenhouse gas emissions are being calculated.optionalLatest available
regionstringThe 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)

ParameterTypeDescriptionRequiredDefault
amountUnit type EnergyThe total heat and steam purchasedrequired
co2e_kg_per_kwhnumberContract emission factor for the component in kg per kWhoptional
energy_sourcestringThe source that the heat is generated from. Valid values are renewable or specific fuel types such as natural_gas, coal, biomass, nuclearoptional
loss_factornumber, "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.

AttributeType
estimatesEnergy reporting quadThe 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.

ParameterTypeDescriptionRequiredDefault
fuel_typestringThe type of fuel burned. See choosing a fuel_type for how to choose this.required
amountUnit type Energy/Volume/WeightThe amount of fuel burned.required
regionstringThe region or country where the fuel was burned.required
fuel_usestringThe use for the fuel, if known.optional
yearnumberThe year in which the fuel was burned.optionalLatest 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.

AttributeType
combustionEnergy estimateEstimate of emissions from fuel combustion
well_to_tankEnergy estimateEstimate 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_types 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_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",
"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:

AttributeTypeDescription
consumptionEnergy estimateEstimates of the greenhouse gas emissions that result from generating the consumed energy.
transmission_and_distributionEnergy estimateEstimates of the greenhouse gas emissions that result from generating the energy which is subsequently lost during the processes of transmission and distribution.
well_to_tankEnergy estimateEstimates of the greenhouse gas emissions that result from obtaining the fuel used for generating the consumed energy.
well_to_tank_of_transmission_and_distributionEnergy estimateEstimates 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

AttributeTypeDescription
co2enumberThe total greenhouse gas emissions associated with the consumed energy, expressed in kilograms (kg).
co2e_unitstringThe unit of measurement for greenhouse gas emissions, which is "kg" (kilograms).
Absence of Estimation model

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 attributesTypeDescription
severitystringEither 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.
messagestringAn explanation of the notice.
codestringA 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 valuedescription
supplier_mix_used_for_residualA grid mix factor was used in place of a residual factor, this will lead to an underestimated market estimate.
general_wtt_used_for_specific_factorThe generic regional WTT% was used for a specific market factor, an energy_source should be provided for a better WTT estimate
ignored_parameterA parameter in the request was ignored in favour of some more precise piece of data
recs_subtracted_market_generationMarket components were subtracted for recs
recs_subtracted_market_transmission_and_distributionMarket T&D components were subtracted for recs
no_region_matchThe requested region was not matched
no_fuel_use_matchThe requested fuel_use was not matched
wtt_not_estimatedError when trying to estimate WTT, WTT estimate will be empty