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_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:

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

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

Cloud Computing Classifications

Request

Response

Request

Response

Request

Response

Choosing a fuel_type

Request

Response

Response models

Energy reporting quad

Energy estimate

Notice

Choosing a `fuel_type`