Energy v1 (preview 1)

🚫

Newer version available

You are reading documentation for an older version of this feature. We recommend you view the documentation for the latest version of this feature, which is available here.

This version of the feature will be removed: December 2024

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

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.

IEA data

By default the Electricity calculator uses publicly published emission factors from various official sources covering 46 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.

https://preview.api.climatiq.io/energy/v1-preview1/electricity

Request

This endpoint accepts the following parameters:

Request parametersShould be sent as a JSON object in the body

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 also be provided in the format US-XXXXX
yearinteger
Default value: Latest year available
The year for which the greenhouse gas emissions are being calculated.
Default Value
Latest year available
amountEnergy object
Default value: Sum of the components
The total electricity used.
Default Value
Sum of the components
recsEnergy object
Quantity of RECs (Renewable Energy Certificates) to apply.
source_setstring
Default 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 core or iea
Default 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.

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://preview.api.climatiq.io/energy/v1-preview1/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.

Response parameters

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.

Example response:

{
    "location": {
        "consumption": {
            "co2e": 1006,
            "co2e_unit": "kg",
            "co2_biogenic": null,
            "calculation_method": "ar6",
            "audit_trail": "`C_\"combustion-efficiency-NaturalGas\" = 0.530`<br />\n`C_\"combustion-efficiency-Renewable\" = 1`<br />\n`F_\"combustion-NaturalGas\" = F_\"9c7763f9-0d77-4584-b268-184a5836bd49\" = 0.2039\"kgco2e/kWh\"`<br />\n`F_\"combustion-Renewable\" = F_\"4f80b533-b3ef-43d3-b51b-fddcd3e4b754\" = 0\"kgco2e/kWh\"`<br />\n`F_\"grid-generation\" = F_\"d53d2fff-6f3e-4a7d-aa78-e05b3a59ee57\" = 0.2072\"kgco2e/kWh\"`<br />\n`I_\"grid-energy\" = (P_\"energy\"^\"component-0\"+I_\"residual-energy\")`<br />\n`I_\"residual-energy\" = (P_\"total-consumed\"-(P_\"energy\"^\"component-0\"+(P_\"energy\"^\"component-1\"+P_\"energy\"^\"component-2\")))`<br />\n`P_\"energy\"^\"component-0\" = 1000\"kWh\"`<br />\n`P_\"energy\"^\"component-1\" = 1000\"kWh\"`<br />\n`P_\"energy\"^\"component-2\" = 1000\"kWh\"`<br />\n`P_\"total-consumed\" = 5000\"kWh\"`<br />\n`E_\"gen\"^\"component-1\" = P_\"energy\"^\"component-1\"/C_\"combustion-efficiency-NaturalGas\"*F_\"combustion-NaturalGas\"`<br />\n`E_\"gen\"^\"component-2\" = P_\"energy\"^\"component-2\"/C_\"combustion-efficiency-Renewable\"*F_\"combustion-Renewable\"`<br />\n`E_\"gen\"^\"grid\" = I_\"grid-energy\"*F_\"grid-generation\"`<br />\n`E_\"fossil\" = (E_\"gen\"^\"grid\"+E_\"gen\"^\"component-1\"+E_\"gen\"^\"component-2\")`<br />\n",
            "source_data": {
                "years": [
                    2022,
                    2023
                ],
                "sources": {
                    "BEIS": {
                        "Greenhouse gas reporting: conversion factors 2022": {},
                        "Greenhouse gas reporting: conversion factors 2023": {}
                    },
                    "Climatiq": {
                        "Climatiq": {}
                    }
                },
                "regions": {
                    "GB": "United Kingdom",
                    "GLOBAL": "Global"
                },
                "emission_factors": [
                    "Electricity supplied from grid",
                    "Natural gas - 100% mineral blend (net CV)",
                    "Renewables"
                ]
            },
            "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 2022",
                    "year": "2022",
                    "region": "GB",
                    "region_name": "United Kingdom"
                },
                {
                    "data_category": "emission_factor",
                    "name": "Renewables",
                    "source": "Climatiq",
                    "source_dataset": "Climatiq",
                    "year": "2022",
                    "region": "GLOBAL",
                    "region_name": "Global"
                }
            ]
        },
        "well_to_tank": {
            "co2e": 202.8,
            "co2e_unit": "kg",
            "co2_biogenic": null,
            "calculation_method": "ar4",
            "audit_trail": "`C_\"combustion-efficiency-NaturalGas\" = 0.530`<br />\n`C_\"combustion-efficiency-Renewable\" = 1`<br />\n`F_\"grid-WTT\" = F_\"f0cd3fdd-533e-41d1-828d-fd4d103dc2ad\" = 0.0459\"kgco2e/kWh\"`<br />\n`F_\"grid-generation\" = F_\"d53d2fff-6f3e-4a7d-aa78-e05b3a59ee57\" = 0.2071\"kgco2e/kWh\"`<br />\n`F_\"ref-grid-generation\" = F_\"d53d2fff-6f3e-4a7d-aa78-e05b3a59ee57\" = 0.2071\"kgco2e/kWh\"`<br />\n`F_\"wtt-NaturalGas\" = F_\"f240a055-c0ac-44e1-bd1b-603eae4be018\" = 0.03446\"kgco2e/kWh\"`<br />\n`F_\"wtt-Renewable\" = F_\"775f78bb-3d1e-499b-a95f-3fbbf4ba12e9\" = 0\"kgco2e/kWh\"`<br />\n`I_\"grid-energy\" = (P_\"energy\"^\"component-0\"+I_\"residual-energy\")`<br />\n`I_\"residual-energy\" = (P_\"total-consumed\"-(P_\"energy\"^\"component-0\"+(P_\"energy\"^\"component-1\"+P_\"energy\"^\"component-2\")))`<br />\n`P_\"energy\"^\"component-0\" = 1000\"kWh\"`<br />\n`P_\"energy\"^\"component-1\" = 1000\"kWh\"`<br />\n`P_\"energy\"^\"component-2\" = 1000\"kWh\"`<br />\n`P_\"total-consumed\" = 5000\"kWh\"`<br />\n`E_\"wtt-gen\"^\"component-1\" = P_\"energy\"^\"component-1\"/C_\"combustion-efficiency-NaturalGas\"*F_\"wtt-NaturalGas\"`<br />\n`E_\"wtt-gen\"^\"component-2\" = P_\"energy\"^\"component-2\"/C_\"combustion-efficiency-Renewable\"*F_\"wtt-Renewable\"`<br />\n`E_\"wtt-gen\"^\"grid\" = I_\"grid-energy\"*F_\"grid-WTT\"/F_\"ref-grid-generation\"*F_\"grid-generation\"`<br />\n`E_\"fossil\" = (E_\"wtt-gen\"^\"grid\"+E_\"wtt-gen\"^\"component-1\"+E_\"wtt-gen\"^\"component-2\")`<br />\n",
            "source_data": {
                "years": [
                    2022,
                    2023
                ],
                "sources": {
                    "BEIS": {
                        "Greenhouse gas reporting: conversion factors 2022": {},
                        "Greenhouse gas reporting: conversion factors 2023": {}
                    },
                    "Climatiq": {
                        "Climatiq": {}
                    }
                },
                "regions": {
                    "GB": "United Kingdom",
                    "GLOBAL": "Global"
                },
                "emission_factors": [
                    "Electricity supplied from grid",
                    "Natural gas - 100% mineral blend (net CV)",
                    "Renewables"
                ]
            },
            "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 2022",
                    "year": "2022",
                    "region": "GB",
                    "region_name": "United Kingdom"
                },
                {
                    "data_category": "emission_factor",
                    "name": "Renewables",
                    "source": "Climatiq",
                    "source_dataset": "Climatiq",
                    "year": "2022",
                    "region": "GLOBAL",
                    "region_name": "Global"
                }
            ]
        },
        "transmission_and_distribution": {
            "co2e": 79.09,
            "co2e_unit": "kg",
            "co2_biogenic": null,
            "calculation_method": "ar6",
            "audit_trail": "`C_\"TnD-loss-factor\" = 0.010`<br />\n`C_\"combustion-efficiency-NaturalGas\" = 0.530`<br />\n`C_\"combustion-efficiency-Renewable\" = 1`<br />\n`F_\"combustion-NaturalGas\" = F_\"9c7763f9-0d77-4584-b268-184a5836bd49\" = 0.2039\"kgco2e/kWh\"`<br />\n`F_\"combustion-Renewable\" = F_\"4f80b533-b3ef-43d3-b51b-fddcd3e4b754\" = 0\"kgco2e/kWh\"`<br />\n`F_\"grid-WTT\" = F_\"f0cd3fdd-533e-41d1-828d-fd4d103dc2ad\" = 0.0459\"kgco2e/kWh\"`<br />\n`F_\"grid-WTT-TnD\" = F_\"7f7fbc79-c64a-4371-9692-2e606d38a86a\" = 0.00397\"kgco2e/kWh\"`<br />\n`F_\"grid-generation\" = F_\"d53d2fff-6f3e-4a7d-aa78-e05b3a59ee57\" = 0.2072\"kgco2e/kWh\"`<br />\n`I_\"TnD-loss-factor\"^\"grid\" = F_\"grid-WTT-TnD\"/F_\"grid-WTT\"`<br />\n`I_\"generated-energy\"^\"component-1\" = P_\"energy\"^\"component-1\"/(1-P_\"TnD-loss-factor\"^\"component-1\")`<br />\n`I_\"generated-energy\"^\"component-2\" = P_\"energy\"^\"component-2\"/(1-C_\"TnD-loss-factor\")`<br />\n`I_\"generated-energy\"^\"grid\" = I_\"grid-energy\"/(1-I_\"TnD-loss-factor\"^\"grid\")`<br />\n`I_\"grid-energy\" = (P_\"energy\"^\"component-0\"+I_\"residual-energy\")`<br />\n`I_\"residual-energy\" = (P_\"total-consumed\"-(P_\"energy\"^\"component-0\"+(P_\"energy\"^\"component-1\"+P_\"energy\"^\"component-2\")))`<br />\n`P_\"TnD-loss-factor\"^\"component-1\" = 0.050`<br />\n`P_\"energy\"^\"component-0\" = 1000\"kWh\"`<br />\n`P_\"energy\"^\"component-1\" = 1000\"kWh\"`<br />\n`P_\"energy\"^\"component-2\" = 1000\"kWh\"`<br />\n`P_\"total-consumed\" = 5000\"kWh\"`<br />\n`E_\"tnd\"^\"component-1\" = I_\"generated-energy\"^\"component-1\"*P_\"TnD-loss-factor\"^\"component-1\"/C_\"combustion-efficiency-NaturalGas\"*F_\"combustion-NaturalGas\"`<br />\n`E_\"tnd\"^\"component-2\" = I_\"generated-energy\"^\"component-2\"*C_\"TnD-loss-factor\"/C_\"combustion-efficiency-Renewable\"*F_\"combustion-Renewable\"`<br />\n`E_\"tnd\"^\"grid\" = I_\"generated-energy\"^\"grid\"*I_\"TnD-loss-factor\"^\"grid\"*F_\"grid-generation\"`<br />\n`E_\"fossil\" = (E_\"tnd\"^\"grid\"+E_\"tnd\"^\"component-1\"+E_\"tnd\"^\"component-2\")`<br />\n",
            "source_data": {
                "years": [
                    2022,
                    2023
                ],
                "sources": {
                    "BEIS": {
                        "Greenhouse gas reporting: conversion factors 2022": {},
                        "Greenhouse gas reporting: conversion factors 2023": {}
                    },
                    "Climatiq": {
                        "Climatiq": {}
                    }
                },
                "regions": {
                    "GB": "United Kingdom",
                    "GLOBAL": "Global"
                },
                "emission_factors": [
                    "Electricity supplied from grid",
                    "Electricity supplied from grid: T&D losses",
                    "Natural gas - 100% mineral blend (net CV)",
                    "Renewables"
                ]
            },
            "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 2022",
                    "year": "2022",
                    "region": "GB",
                    "region_name": "United Kingdom"
                },
                {
                    "data_category": "emission_factor",
                    "name": "Renewables",
                    "source": "Climatiq",
                    "source_dataset": "Climatiq",
                    "year": "2022",
                    "region": "GLOBAL",
                    "region_name": "Global"
                }
            ]
        },
        "well_to_tank_of_transmission_and_distribution": {
            "co2e": 16.46,
            "co2e_unit": "kg",
            "co2_biogenic": null,
            "calculation_method": "ar4",
            "audit_trail": "`C_\"TnD-loss-factor\" = 0.010`<br />\n`C_\"combustion-efficiency-NaturalGas\" = 0.530`<br />\n`C_\"combustion-efficiency-Renewable\" = 1`<br />\n`F_\"grid-WTT\" = F_\"f0cd3fdd-533e-41d1-828d-fd4d103dc2ad\" = 0.0459\"kgco2e/kWh\"`<br />\n`F_\"grid-WTT-TnD\" = F_\"7f7fbc79-c64a-4371-9692-2e606d38a86a\" = 0.00397\"kgco2e/kWh\"`<br />\n`F_\"grid-generation\" = F_\"d53d2fff-6f3e-4a7d-aa78-e05b3a59ee57\" = 0.2071\"kgco2e/kWh\"`<br />\n`F_\"ref-grid-generation\" = F_\"d53d2fff-6f3e-4a7d-aa78-e05b3a59ee57\" = 0.2071\"kgco2e/kWh\"`<br />\n`F_\"wtt-NaturalGas\" = F_\"f240a055-c0ac-44e1-bd1b-603eae4be018\" = 0.03446\"kgco2e/kWh\"`<br />\n`F_\"wtt-Renewable\" = F_\"775f78bb-3d1e-499b-a95f-3fbbf4ba12e9\" = 0\"kgco2e/kWh\"`<br />\n`I_\"TnD-loss-factor\"^\"grid\" = F_\"grid-WTT-TnD\"/F_\"grid-WTT\"`<br />\n`I_\"generated-energy\"^\"component-1\" = P_\"energy\"^\"component-1\"/(1-P_\"TnD-loss-factor\"^\"component-1\")`<br />\n`I_\"generated-energy\"^\"component-2\" = P_\"energy\"^\"component-2\"/(1-C_\"TnD-loss-factor\")`<br />\n`I_\"generated-energy\"^\"grid\" = I_\"grid-energy\"/(1-I_\"TnD-loss-factor\"^\"grid\")`<br />\n`I_\"grid-energy\" = (P_\"energy\"^\"component-0\"+I_\"residual-energy\")`<br />\n`I_\"residual-energy\" = (P_\"total-consumed\"-(P_\"energy\"^\"component-0\"+(P_\"energy\"^\"component-1\"+P_\"energy\"^\"component-2\")))`<br />\n`P_\"TnD-loss-factor\"^\"component-1\" = 0.050`<br />\n`P_\"energy\"^\"component-0\" = 1000\"kWh\"`<br />\n`P_\"energy\"^\"component-1\" = 1000\"kWh\"`<br />\n`P_\"energy\"^\"component-2\" = 1000\"kWh\"`<br />\n`P_\"total-consumed\" = 5000\"kWh\"`<br />\n`E_\"wtt-tnd\"^\"component-1\" = I_\"generated-energy\"^\"component-1\"*P_\"TnD-loss-factor\"^\"component-1\"/C_\"combustion-efficiency-NaturalGas\"*F_\"wtt-NaturalGas\"`<br />\n`E_\"wtt-tnd\"^\"component-2\" = I_\"generated-energy\"^\"component-2\"*C_\"TnD-loss-factor\"/C_\"combustion-efficiency-Renewable\"*F_\"wtt-Renewable\"`<br />\n`E_\"wtt-tnd\"^\"grid\" = I_\"generated-energy\"^\"grid\"*I_\"TnD-loss-factor\"^\"grid\"*F_\"grid-WTT\"/F_\"ref-grid-generation\"*F_\"grid-generation\"`<br />\n`E_\"fossil\" = (E_\"wtt-tnd\"^\"grid\"+E_\"wtt-tnd\"^\"component-1\"+E_\"wtt-tnd\"^\"component-2\")`<br />\n",
            "source_data": {
                "years": [
                    2022,
                    2023
                ],
                "sources": {
                    "BEIS": {
                        "Greenhouse gas reporting: conversion factors 2022": {},
                        "Greenhouse gas reporting: conversion factors 2023": {}
                    },
                    "Climatiq": {
                        "Climatiq": {}
                    }
                },
                "regions": {
                    "GB": "United Kingdom",
                    "GLOBAL": "Global"
                },
                "emission_factors": [
                    "Electricity supplied from grid",
                    "Electricity supplied from grid: T&D losses",
                    "Natural gas - 100% mineral blend (net CV)",
                    "Renewables"
                ]
            },
            "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 2022",
                    "year": "2022",
                    "region": "GB",
                    "region_name": "United Kingdom"
                },
                {
                    "data_category": "emission_factor",
                    "name": "Renewables",
                    "source": "Climatiq",
                    "source_dataset": "Climatiq",
                    "year": "2022",
                    "region": "GLOBAL",
                    "region_name": "Global"
                }
            ]
        }
    },
    "market": {
        "consumption": {
            "co2e": 889,
            "co2e_unit": "kg",
            "co2_biogenic": null,
            "calculation_method": "ar4",
            "audit_trail": "`C_\"combustion-efficiency-NaturalGas\" = 0.530`<br />\n`C_\"combustion-efficiency-Renewable\" = 1`<br />\n`F_\"british_gas\" = F_\"91085c77-b65f-403c-812f-a68040b14e1f\" = 0.116\"kgco2e/kWh\"`<br />\n`F_\"combustion-NaturalGas\" = F_\"9c7763f9-0d77-4584-b268-184a5836bd49\" = 0.2039\"kgco2e/kWh\"`<br />\n`F_\"combustion-Renewable\" = F_\"4f80b533-b3ef-43d3-b51b-fddcd3e4b754\" = 0\"kgco2e/kWh\"`<br />\n`F_\"grid-residual\" = F_\"3bf35117-1ad2-42ba-a403-c5fa92db0925\" = 0.3884\"kgco2e/kWh\"`<br />\n`I_\"residual-energy\" = (P_\"total-consumed\"-(P_\"energy\"^\"component-0\"+(P_\"energy\"^\"component-1\"+P_\"energy\"^\"component-2\")))`<br />\n`P_\"energy\"^\"component-0\" = 1000\"kWh\"`<br />\n`P_\"energy\"^\"component-1\" = 1000\"kWh\"`<br />\n`P_\"energy\"^\"component-2\" = 1000\"kWh\"`<br />\n`P_\"recs\" = 1000\"kWh\"`<br />\n`P_\"total-consumed\" = 5000\"kWh\"`<br />\n`E_\"gen\"^\"component-0\" = P_\"energy\"^\"component-0\"*F_\"british_gas\"`<br />\n`E_\"gen\"^\"component-1\" = P_\"energy\"^\"component-1\"/C_\"combustion-efficiency-NaturalGas\"*F_\"combustion-NaturalGas\"`<br />\n`E_\"gen\"^\"component-2\" = P_\"energy\"^\"component-2\"/C_\"combustion-efficiency-Renewable\"*F_\"combustion-Renewable\"`<br />\n`E_\"gen\"^\"residual\" = (I_\"residual-energy\"-P_\"recs\")*F_\"grid-residual\"`<br />\n`E_\"fossil\" = (E_\"gen\"^\"component-0\"+E_\"gen\"^\"residual\"+E_\"gen\"^\"component-1\"+E_\"gen\"^\"component-2\")`<br />\n",
            "source_data": {
                "years": [
                    2022,
                    2023
                ],
                "sources": {
                    "AIB": {
                        "European Residual Mix": {}
                    },
                    "BEIS": {
                        "Greenhouse gas reporting: conversion factors 2022": {}
                    },
                    "Climatiq": {
                        "Climatiq": {}
                    },
                    "Electricity Info": {
                        "Fuel Mix of UK Domestic Electricity Suppliers": {}
                    }
                },
                "regions": {
                    "GB": "United Kingdom",
                    "GLOBAL": "Global"
                },
                "emission_factors": [
                    "Electricity supplied from grid - residual mix",
                    "Electricity supplied from grid - supplier British Gas",
                    "Natural gas - 100% mineral blend (net CV)",
                    "Renewables"
                ]
            },
            "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 2022",
                    "year": "2022",
                    "region": "GB",
                    "region_name": "United Kingdom"
                },
                {
                    "data_category": "emission_factor",
                    "name": "Renewables",
                    "source": "Climatiq",
                    "source_dataset": "Climatiq",
                    "year": "2022",
                    "region": "GLOBAL",
                    "region_name": "Global"
                }
            ]
        },
        "well_to_tank": {
            "co2e": 176.8,
            "co2e_unit": "kg",
            "co2_biogenic": null,
            "calculation_method": "ar4",
            "audit_trail": "`C_\"combustion-efficiency-NaturalGas\" = 0.530`<br />\n`C_\"combustion-efficiency-Renewable\" = 1`<br />\n`F_\"british_gas\" = F_\"91085c77-b65f-403c-812f-a68040b14e1f\" = 0.116\"kgco2e/kWh\"`<br />\n`F_\"grid-WTT\" = F_\"f0cd3fdd-533e-41d1-828d-fd4d103dc2ad\" = 0.0459\"kgco2e/kWh\"`<br />\n`F_\"grid-residual\" = F_\"3bf35117-1ad2-42ba-a403-c5fa92db0925\" = 0.3884\"kgco2e/kWh\"`<br />\n`F_\"ref-grid-generation\" = F_\"d53d2fff-6f3e-4a7d-aa78-e05b3a59ee57\" = 0.2071\"kgco2e/kWh\"`<br />\n`F_\"wtt-NaturalGas\" = F_\"f240a055-c0ac-44e1-bd1b-603eae4be018\" = 0.03446\"kgco2e/kWh\"`<br />\n`F_\"wtt-Renewable\" = F_\"775f78bb-3d1e-499b-a95f-3fbbf4ba12e9\" = 0\"kgco2e/kWh\"`<br />\n`I_\"residual-energy\" = (P_\"total-consumed\"-(P_\"energy\"^\"component-0\"+(P_\"energy\"^\"component-1\"+P_\"energy\"^\"component-2\")))`<br />\n`P_\"energy\"^\"component-0\" = 1000\"kWh\"`<br />\n`P_\"energy\"^\"component-1\" = 1000\"kWh\"`<br />\n`P_\"energy\"^\"component-2\" = 1000\"kWh\"`<br />\n`P_\"recs\" = 1000\"kWh\"`<br />\n`P_\"total-consumed\" = 5000\"kWh\"`<br />\n`E_\"wtt-gen\"^\"component-0\" = P_\"energy\"^\"component-0\"*ubrace(F_\"grid-WTT\"/F_\"ref-grid-generation\")_\"Applying regional well to tank percentage to the market factor for named supplier 'british_gas'. For more accurate well to tank emissions, explicitly provide a fuel mix.\"*F_\"british_gas\"`<br />\n`E_\"wtt-gen\"^\"component-1\" = P_\"energy\"^\"component-1\"/C_\"combustion-efficiency-NaturalGas\"*F_\"wtt-NaturalGas\"`<br />\n`E_\"wtt-gen\"^\"component-2\" = P_\"energy\"^\"component-2\"/C_\"combustion-efficiency-Renewable\"*F_\"wtt-Renewable\"`<br />\n`E_\"wtt-gen\"^\"residual\" = (I_\"residual-energy\"-P_\"recs\")*F_\"grid-WTT\"/F_\"ref-grid-generation\"*F_\"grid-residual\"`<br />\n`E_\"fossil\" = (E_\"wtt-gen\"^\"component-0\"+E_\"wtt-gen\"^\"residual\"+E_\"wtt-gen\"^\"component-1\"+E_\"wtt-gen\"^\"component-2\")`<br />\n",
            "source_data": {
                "years": [
                    2022,
                    2023
                ],
                "sources": {
                    "AIB": {
                        "European Residual Mix": {}
                    },
                    "BEIS": {
                        "Greenhouse gas reporting: conversion factors 2022": {},
                        "Greenhouse gas reporting: conversion factors 2023": {}
                    },
                    "Climatiq": {
                        "Climatiq": {}
                    },
                    "Electricity Info": {
                        "Fuel Mix of UK Domestic Electricity Suppliers": {}
                    }
                },
                "regions": {
                    "GB": "United Kingdom",
                    "GLOBAL": "Global"
                },
                "emission_factors": [
                    "Electricity supplied from grid",
                    "Electricity supplied from grid - residual mix",
                    "Electricity supplied from grid - supplier British Gas",
                    "Natural gas - 100% mineral blend (net CV)",
                    "Renewables"
                ]
            },
            "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 - 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 2022",
                    "year": "2022",
                    "region": "GB",
                    "region_name": "United Kingdom"
                },
                {
                    "data_category": "emission_factor",
                    "name": "Renewables",
                    "source": "Climatiq",
                    "source_dataset": "Climatiq",
                    "year": "2022",
                    "region": "GLOBAL",
                    "region_name": "Global"
                }
            ]
        },
        "transmission_and_distribution": {
            "co2e": 79.09,
            "co2e_unit": "kg",
            "co2_biogenic": null,
            "calculation_method": "ar6",
            "audit_trail": "`C_\"TnD-loss-factor\" = 0.010`<br />\n`C_\"combustion-efficiency-NaturalGas\" = 0.530`<br />\n`C_\"combustion-efficiency-Renewable\" = 1`<br />\n`F_\"combustion-NaturalGas\" = F_\"9c7763f9-0d77-4584-b268-184a5836bd49\" = 0.2039\"kgco2e/kWh\"`<br />\n`F_\"combustion-Renewable\" = F_\"4f80b533-b3ef-43d3-b51b-fddcd3e4b754\" = 0\"kgco2e/kWh\"`<br />\n`F_\"grid-WTT\" = F_\"f0cd3fdd-533e-41d1-828d-fd4d103dc2ad\" = 0.0459\"kgco2e/kWh\"`<br />\n`F_\"grid-WTT-TnD\" = F_\"7f7fbc79-c64a-4371-9692-2e606d38a86a\" = 0.00397\"kgco2e/kWh\"`<br />\n`F_\"grid-generation\" = F_\"d53d2fff-6f3e-4a7d-aa78-e05b3a59ee57\" = 0.2072\"kgco2e/kWh\"`<br />\n`I_\"TnD-loss-factor\"^\"grid\" = F_\"grid-WTT-TnD\"/F_\"grid-WTT\"`<br />\n`I_\"generated-energy\"^\"component-1\" = P_\"energy\"^\"component-1\"/(1-P_\"TnD-loss-factor\"^\"component-1\")`<br />\n`I_\"generated-energy\"^\"component-2\" = P_\"energy\"^\"component-2\"/(1-C_\"TnD-loss-factor\")`<br />\n`I_\"generated-energy\"^\"grid\" = I_\"grid-energy\"/(1-I_\"TnD-loss-factor\"^\"grid\")`<br />\n`I_\"grid-energy\" = (P_\"energy\"^\"component-0\"+I_\"residual-energy\")`<br />\n`I_\"residual-energy\" = (P_\"total-consumed\"-(P_\"energy\"^\"component-0\"+(P_\"energy\"^\"component-1\"+P_\"energy\"^\"component-2\")))`<br />\n`P_\"TnD-loss-factor\"^\"component-1\" = 0.050`<br />\n`P_\"energy\"^\"component-0\" = 1000\"kWh\"`<br />\n`P_\"energy\"^\"component-1\" = 1000\"kWh\"`<br />\n`P_\"energy\"^\"component-2\" = 1000\"kWh\"`<br />\n`P_\"total-consumed\" = 5000\"kWh\"`<br />\n`E_\"tnd\"^\"component-1\" = I_\"generated-energy\"^\"component-1\"*P_\"TnD-loss-factor\"^\"component-1\"/C_\"combustion-efficiency-NaturalGas\"*F_\"combustion-NaturalGas\"`<br />\n`E_\"tnd\"^\"component-2\" = I_\"generated-energy\"^\"component-2\"*C_\"TnD-loss-factor\"/C_\"combustion-efficiency-Renewable\"*F_\"combustion-Renewable\"`<br />\n`E_\"tnd\"^\"grid\" = I_\"generated-energy\"^\"grid\"*I_\"TnD-loss-factor\"^\"grid\"*F_\"grid-generation\"`<br />\n`E_\"fossil\" = (E_\"tnd\"^\"grid\"+E_\"tnd\"^\"component-1\"+E_\"tnd\"^\"component-2\")`<br />\n",
            "source_data": {
                "years": [
                    2022,
                    2023
                ],
                "sources": {
                    "BEIS": {
                        "Greenhouse gas reporting: conversion factors 2022": {},
                        "Greenhouse gas reporting: conversion factors 2023": {}
                    },
                    "Climatiq": {
                        "Climatiq": {}
                    }
                },
                "regions": {
                    "GB": "United Kingdom",
                    "GLOBAL": "Global"
                },
                "emission_factors": [
                    "Electricity supplied from grid",
                    "Electricity supplied from grid: T&D losses",
                    "Natural gas - 100% mineral blend (net CV)",
                    "Renewables"
                ]
            },
            "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 2022",
                    "year": "2022",
                    "region": "GB",
                    "region_name": "United Kingdom"
                },
                {
                    "data_category": "emission_factor",
                    "name": "Renewables",
                    "source": "Climatiq",
                    "source_dataset": "Climatiq",
                    "year": "2022",
                    "region": "GLOBAL",
                    "region_name": "Global"
                }
            ]
        },
        "well_to_tank_of_transmission_and_distribution": {
            "co2e": 16.46,
            "co2e_unit": "kg",
            "co2_biogenic": null,
            "calculation_method": "ar4",
            "audit_trail": "`C_\"TnD-loss-factor\" = 0.010`<br />\n`C_\"combustion-efficiency-NaturalGas\" = 0.530`<br />\n`C_\"combustion-efficiency-Renewable\" = 1`<br />\n`F_\"grid-WTT\" = F_\"f0cd3fdd-533e-41d1-828d-fd4d103dc2ad\" = 0.0459\"kgco2e/kWh\"`<br />\n`F_\"grid-WTT-TnD\" = F_\"7f7fbc79-c64a-4371-9692-2e606d38a86a\" = 0.00397\"kgco2e/kWh\"`<br />\n`F_\"grid-generation\" = F_\"d53d2fff-6f3e-4a7d-aa78-e05b3a59ee57\" = 0.2071\"kgco2e/kWh\"`<br />\n`F_\"ref-grid-generation\" = F_\"d53d2fff-6f3e-4a7d-aa78-e05b3a59ee57\" = 0.2071\"kgco2e/kWh\"`<br />\n`F_\"wtt-NaturalGas\" = F_\"f240a055-c0ac-44e1-bd1b-603eae4be018\" = 0.03446\"kgco2e/kWh\"`<br />\n`F_\"wtt-Renewable\" = F_\"775f78bb-3d1e-499b-a95f-3fbbf4ba12e9\" = 0\"kgco2e/kWh\"`<br />\n`I_\"TnD-loss-factor\"^\"grid\" = F_\"grid-WTT-TnD\"/F_\"grid-WTT\"`<br />\n`I_\"generated-energy\"^\"component-1\" = P_\"energy\"^\"component-1\"/(1-P_\"TnD-loss-factor\"^\"component-1\")`<br />\n`I_\"generated-energy\"^\"component-2\" = P_\"energy\"^\"component-2\"/(1-C_\"TnD-loss-factor\")`<br />\n`I_\"generated-energy\"^\"grid\" = I_\"grid-energy\"/(1-I_\"TnD-loss-factor\"^\"grid\")`<br />\n`I_\"grid-energy\" = (P_\"energy\"^\"component-0\"+I_\"residual-energy\")`<br />\n`I_\"residual-energy\" = (P_\"total-consumed\"-(P_\"energy\"^\"component-0\"+(P_\"energy\"^\"component-1\"+P_\"energy\"^\"component-2\")))`<br />\n`P_\"TnD-loss-factor\"^\"component-1\" = 0.050`<br />\n`P_\"energy\"^\"component-0\" = 1000\"kWh\"`<br />\n`P_\"energy\"^\"component-1\" = 1000\"kWh\"`<br />\n`P_\"energy\"^\"component-2\" = 1000\"kWh\"`<br />\n`P_\"total-consumed\" = 5000\"kWh\"`<br />\n`E_\"wtt-tnd\"^\"component-1\" = I_\"generated-energy\"^\"component-1\"*P_\"TnD-loss-factor\"^\"component-1\"/C_\"combustion-efficiency-NaturalGas\"*F_\"wtt-NaturalGas\"`<br />\n`E_\"wtt-tnd\"^\"component-2\" = I_\"generated-energy\"^\"component-2\"*C_\"TnD-loss-factor\"/C_\"combustion-efficiency-Renewable\"*F_\"wtt-Renewable\"`<br />\n`E_\"wtt-tnd\"^\"grid\" = I_\"generated-energy\"^\"grid\"*I_\"TnD-loss-factor\"^\"grid\"*F_\"grid-WTT\"/F_\"ref-grid-generation\"*F_\"grid-generation\"`<br />\n`E_\"fossil\" = (E_\"wtt-tnd\"^\"grid\"+E_\"wtt-tnd\"^\"component-1\"+E_\"wtt-tnd\"^\"component-2\")`<br />\n",
            "source_data": {
                "years": [
                    2022,
                    2023
                ],
                "sources": {
                    "BEIS": {
                        "Greenhouse gas reporting: conversion factors 2022": {},
                        "Greenhouse gas reporting: conversion factors 2023": {}
                    },
                    "Climatiq": {
                        "Climatiq": {}
                    }
                },
                "regions": {
                    "GB": "United Kingdom",
                    "GLOBAL": "Global"
                },
                "emission_factors": [
                    "Electricity supplied from grid",
                    "Electricity supplied from grid: T&D losses",
                    "Natural gas - 100% mineral blend (net CV)",
                    "Renewables"
                ]
            },
            "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 2022",
                    "year": "2022",
                    "region": "GB",
                    "region_name": "United Kingdom"
                },
                {
                    "data_category": "emission_factor",
                    "name": "Renewables",
                    "source": "Climatiq",
                    "source_dataset": "Climatiq",
                    "year": "2022",
                    "region": "GLOBAL",
                    "region_name": "Global"
                }
            ]
        }
    },
    "notices": [
        {
            "severity": "warning",
            "code": "general_wtt_used_for_specific_factor",
            "message": "Applying regional well to tank percentage to the market factor for named supplier 'british_gas'. For more accurate well to tank emissions, explicitly provide a fuel mix."
        },
        {
            "severity": "info",
            "code": "recs_subtracted_market_generation",
            "message": "Market generation components were subtracted for RECs"
        }
    ]
}

Choosing a `region`

regions's are currently only available where grid emission data is available, and we plan to expand this coverage over time. 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://preview.api.climatiq.io/energy/v1-preview1/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": [
            "AT",
            "AU",
            "AU-ACT",
            "AU-NSW",
            "AU-NT",
            "AU-QLD",
            "AU-SA",
            "AU-TAS",
            "AU-VIC",
            "AU-WA",
            "BE",
            "BG",
            "BR",
            "CA",
            "CA-AB",
            "CA-BC",
            "CA-MB",
            "CA-NB",
            "CA-NL",
            "CA-NS",
            "CA-NT",
            "CA-NU",
            "CA-ON",
            "CA-PE",
            "CA-QC",
            "CA-SK",
            "CA-YT",
            "CH",
            "CN",
            "CY",
            "CZ",
            "DE",
            "DK",
            "EE",
            "ES",
            "EU",
            "FI",
            "FR",
            "GB",
            "GR",
            "HR",
            "HU",
            "ID",
            "IE",
            "IN",
            "IS",
            "IT",
            "JP",
            "KR",
            "LT",
            "LU",
            "LV",
            "MT",
            "MX",
            "NL",
            "NO",
            "NZ",
            "PL",
            "PT",
            "RO",
            "RU",
            "SA",
            "SE",
            "SI",
            "SK",
            "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",
            "ZA"
        ]
    }
}

Choosing a `supplier`

supplier's 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://preview.api.climatiq.io/energy/v1-preview1/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",
            "pg_and_e_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://preview.api.climatiq.io/energy/v1-preview1/electricity/batch

Provide 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://preview.api.climatiq.io/energy/v1-preview1/heat

Request

This endpoint accepts the following parameters:

Request parametersShould be sent as a JSON object in the body

yearinteger
Default value: Latest year available
The year for which the greenhouse gas emissions are being calculated.
Default Value
Latest year available
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 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)
components[x].amountrequired Energy object
The total heat and steam purchased
components[x].co2e_kg_per_kwhfloat
Contract emission factor for the component in kg per kWh
components[x].energy_sourcestring
The source that the heat is generated from. Valid values are renewable or specific fuel types such as natural_gas, coal, biomass, nuclear
components[x].loss_factorfloat or string
Default value: medium
The distribution loss factor for this component. Can either be a number or one of the strings "low", "medium" or "high"
Default Value
medium

curl --request POST \
  --url https://preview.api.climatiq.io/energy/v1-preview1/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.

Response parameters

estimatesEnergy reporting quad
The estimates for greenhouse gas emissions.
noticesarray of Notices
Any notices about deficiencies or peculiarities of the calculation.

Example response:

{
    "estimates": {
        "consumption": {
            "co2e": 638.5,
            "co2e_unit": "kg",
            "co2_biogenic": null,
            "calculation_method": "ar6",
            "audit_trail": "`C_\"combustion-efficiency-NaturalGas\" = 0.530`<br />\n`C_\"combustion-efficiency-Renewable\" = 1`<br />\n`F_\"combustion-NaturalGas\" = F_\"1e1ffef5-6478-4356-a13b-fa0f66d962d1\" = 0.2044\"kgco2e/kWh\"`<br />\n`F_\"combustion-Renewable\" = F_\"4f80b533-b3ef-43d3-b51b-fddcd3e4b754\" = 0\"kgco2e/kWh\"`<br />\n`F_\"location-generation\" = F_\"1e66f532-ec59-4f23-9606-0c63d4add4a1\" = 0.2529\"kgco2e/kWh\"`<br />\n`P_\"energy\"^\"component-0\" = 1000\"kWh\"`<br />\n`P_\"energy\"^\"component-1\" = 1000\"kWh\"`<br />\n`P_\"energy\"^\"component-2\" = 1000\"kWh\"`<br />\n`E_\"gen\"^\"component-0\" = P_\"energy\"^\"component-0\"*F_\"location-generation\"`<br />\n`E_\"gen\"^\"component-1\" = P_\"energy\"^\"component-1\"/C_\"combustion-efficiency-NaturalGas\"*F_\"combustion-NaturalGas\"`<br />\n`E_\"gen\"^\"component-2\" = P_\"energy\"^\"component-2\"/C_\"combustion-efficiency-Renewable\"*F_\"combustion-Renewable\"`<br />\n`E_\"fossil\" = (E_\"gen\"^\"component-0\"+E_\"gen\"^\"component-1\"+E_\"gen\"^\"component-2\")`<br />\n",
            "source_data": {
                "years": [
                    2021,
                    2022
                ],
                "sources": {
                    "BEIS": {
                        "Greenhouse gas reporting: conversion factors 2021": {}
                    },
                    "Climatiq": {
                        "Climatiq": {}
                    },
                    "UBA": {
                        "Emissionsbilanz erneuerbarer Energietraeger": {}
                    }
                },
                "regions": {
                    "DE": "Germany",
                    "GB": "United Kingdom",
                    "GLOBAL": "Global"
                },
                "emission_factors": [
                    "District heating",
                    "Natural gas - 100% mineral blend (net CV)",
                    "Renewables"
                ]
            },
            "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"
                }
            ]
        },
        "well_to_tank": {
            "co2e": 105.8,
            "co2e_unit": "kg",
            "co2_biogenic": null,
            "calculation_method": "ar4",
            "audit_trail": "`C_\"combustion-efficiency-NaturalGas\" = 0.530`<br />\n`C_\"combustion-efficiency-Renewable\" = 1`<br />\n`F_\"location-WTT\" = F_\"21035a1d-f1df-452b-b673-c69895065b1c\" = 0.04029\"kgco2e/kWh\"`<br />\n`F_\"location-generation\" = F_\"1e66f532-ec59-4f23-9606-0c63d4add4a1\" = 0.2526\"kgco2e/kWh\"`<br />\n`F_\"ref-location-generation\" = F_\"1e66f532-ec59-4f23-9606-0c63d4add4a1\" = 0.2526\"kgco2e/kWh\"`<br />\n`F_\"wtt-NaturalGas\" = F_\"aa9240f8-ca36-4405-bed9-083678faa694\" = 0.03474\"kgco2e/kWh\"`<br />\n`F_\"wtt-Renewable\" = F_\"775f78bb-3d1e-499b-a95f-3fbbf4ba12e9\" = 0\"kgco2e/kWh\"`<br />\n`P_\"energy\"^\"component-0\" = 1000\"kWh\"`<br />\n`P_\"energy\"^\"component-1\" = 1000\"kWh\"`<br />\n`P_\"energy\"^\"component-2\" = 1000\"kWh\"`<br />\n`E_\"wtt-gen\"^\"component-0\" = P_\"energy\"^\"component-0\"*F_\"location-WTT\"/F_\"ref-location-generation\"*F_\"location-generation\"`<br />\n`E_\"wtt-gen\"^\"component-1\" = P_\"energy\"^\"component-1\"/C_\"combustion-efficiency-NaturalGas\"*F_\"wtt-NaturalGas\"`<br />\n`E_\"wtt-gen\"^\"component-2\" = P_\"energy\"^\"component-2\"/C_\"combustion-efficiency-Renewable\"*F_\"wtt-Renewable\"`<br />\n`E_\"fossil\" = (E_\"wtt-gen\"^\"component-0\"+E_\"wtt-gen\"^\"component-1\"+E_\"wtt-gen\"^\"component-2\")`<br />\n",
            "source_data": {
                "years": [
                    2021,
                    2022
                ],
                "sources": {
                    "BEIS": {
                        "Greenhouse gas reporting: conversion factors 2021": {}
                    },
                    "Climatiq": {
                        "Climatiq": {}
                    },
                    "UBA": {
                        "Emissionsbilanz erneuerbarer Energietraeger": {}
                    }
                },
                "regions": {
                    "DE": "Germany",
                    "GB": "United Kingdom",
                    "GLOBAL": "Global"
                },
                "emission_factors": [
                    "District heating",
                    "Natural gas - 100% mineral blend (net CV)",
                    "Renewables"
                ]
            },
            "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"
                }
            ]
        },
        "transmission_and_distribution": {
            "co2e": 58.98,
            "co2e_unit": "kg",
            "co2_biogenic": null,
            "calculation_method": "ar6",
            "audit_trail": "`C_\"combustion-efficiency-NaturalGas\" = 0.530`<br />\n`C_\"combustion-efficiency-Renewable\" = 1`<br />\n`F_\"combustion-NaturalGas\" = F_\"1e1ffef5-6478-4356-a13b-fa0f66d962d1\" = 0.2044\"kgco2e/kWh\"`<br />\n`F_\"combustion-Renewable\" = F_\"4f80b533-b3ef-43d3-b51b-fddcd3e4b754\" = 0\"kgco2e/kWh\"`<br />\n`F_\"location-generation\" = F_\"1e66f532-ec59-4f23-9606-0c63d4add4a1\" = 0.2529\"kgco2e/kWh\"`<br />\n`I_\"generated-energy\"^\"component-0\" = P_\"energy\"^\"component-0\"/(1-P_\"TnD-loss-factor\"^\"component-0\")`<br />\n`I_\"generated-energy\"^\"component-1\" = P_\"energy\"^\"component-1\"/(1-P_\"TnD-loss-factor\"^\"component-1\")`<br />\n`I_\"generated-energy\"^\"component-2\" = P_\"energy\"^\"component-2\"/(1-P_\"TnD-loss-factor\"^\"component-2\")`<br />\n`P_\"TnD-loss-factor\"^\"component-0\" = 0.060`<br />\n`P_\"TnD-loss-factor\"^\"component-1\" = 0.100`<br />\n`P_\"TnD-loss-factor\"^\"component-2\" = 0.120`<br />\n`P_\"energy\"^\"component-0\" = 1000\"kWh\"`<br />\n`P_\"energy\"^\"component-1\" = 1000\"kWh\"`<br />\n`P_\"energy\"^\"component-2\" = 1000\"kWh\"`<br />\n`E_\"tnd\"^\"component-0\" = I_\"generated-energy\"^\"component-0\"*P_\"TnD-loss-factor\"^\"component-0\"*F_\"location-generation\"`<br />\n`E_\"tnd\"^\"component-1\" = I_\"generated-energy\"^\"component-1\"*P_\"TnD-loss-factor\"^\"component-1\"/C_\"combustion-efficiency-NaturalGas\"*F_\"combustion-NaturalGas\"`<br />\n`E_\"tnd\"^\"component-2\" = I_\"generated-energy\"^\"component-2\"*P_\"TnD-loss-factor\"^\"component-2\"/C_\"combustion-efficiency-Renewable\"*F_\"combustion-Renewable\"`<br />\n`E_\"fossil\" = (E_\"tnd\"^\"component-0\"+E_\"tnd\"^\"component-1\"+E_\"tnd\"^\"component-2\")`<br />\n",
            "source_data": {
                "years": [
                    2021,
                    2022
                ],
                "sources": {
                    "BEIS": {
                        "Greenhouse gas reporting: conversion factors 2021": {}
                    },
                    "Climatiq": {
                        "Climatiq": {}
                    },
                    "UBA": {
                        "Emissionsbilanz erneuerbarer Energietraeger": {}
                    }
                },
                "regions": {
                    "DE": "Germany",
                    "GB": "United Kingdom",
                    "GLOBAL": "Global"
                },
                "emission_factors": [
                    "District heating",
                    "Natural gas - 100% mineral blend (net CV)",
                    "Renewables"
                ]
            },
            "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"
                }
            ]
        },
        "well_to_tank_of_transmission_and_distribution": {
            "co2e": 9.855,
            "co2e_unit": "kg",
            "co2_biogenic": null,
            "calculation_method": "ar4",
            "audit_trail": "`C_\"combustion-efficiency-NaturalGas\" = 0.530`<br />\n`C_\"combustion-efficiency-Renewable\" = 1`<br />\n`F_\"location-WTT\" = F_\"21035a1d-f1df-452b-b673-c69895065b1c\" = 0.04029\"kgco2e/kWh\"`<br />\n`F_\"location-generation\" = F_\"1e66f532-ec59-4f23-9606-0c63d4add4a1\" = 0.2526\"kgco2e/kWh\"`<br />\n`F_\"ref-location-generation\" = F_\"1e66f532-ec59-4f23-9606-0c63d4add4a1\" = 0.2526\"kgco2e/kWh\"`<br />\n`F_\"wtt-NaturalGas\" = F_\"aa9240f8-ca36-4405-bed9-083678faa694\" = 0.03474\"kgco2e/kWh\"`<br />\n`F_\"wtt-Renewable\" = F_\"775f78bb-3d1e-499b-a95f-3fbbf4ba12e9\" = 0\"kgco2e/kWh\"`<br />\n`I_\"generated-energy\"^\"component-0\" = P_\"energy\"^\"component-0\"/(1-P_\"TnD-loss-factor\"^\"component-0\")`<br />\n`I_\"generated-energy\"^\"component-1\" = P_\"energy\"^\"component-1\"/(1-P_\"TnD-loss-factor\"^\"component-1\")`<br />\n`I_\"generated-energy\"^\"component-2\" = P_\"energy\"^\"component-2\"/(1-P_\"TnD-loss-factor\"^\"component-2\")`<br />\n`P_\"TnD-loss-factor\"^\"component-0\" = 0.060`<br />\n`P_\"TnD-loss-factor\"^\"component-1\" = 0.100`<br />\n`P_\"TnD-loss-factor\"^\"component-2\" = 0.120`<br />\n`P_\"energy\"^\"component-0\" = 1000\"kWh\"`<br />\n`P_\"energy\"^\"component-1\" = 1000\"kWh\"`<br />\n`P_\"energy\"^\"component-2\" = 1000\"kWh\"`<br />\n`E_\"wtt-tnd\"^\"component-0\" = I_\"generated-energy\"^\"component-0\"*P_\"TnD-loss-factor\"^\"component-0\"*F_\"location-WTT\"/F_\"ref-location-generation\"*F_\"location-generation\"`<br />\n`E_\"wtt-tnd\"^\"component-1\" = I_\"generated-energy\"^\"component-1\"*P_\"TnD-loss-factor\"^\"component-1\"/C_\"combustion-efficiency-NaturalGas\"*F_\"wtt-NaturalGas\"`<br />\n`E_\"wtt-tnd\"^\"component-2\" = I_\"generated-energy\"^\"component-2\"*P_\"TnD-loss-factor\"^\"component-2\"/C_\"combustion-efficiency-Renewable\"*F_\"wtt-Renewable\"`<br />\n`E_\"fossil\" = (E_\"wtt-tnd\"^\"component-0\"+E_\"wtt-tnd\"^\"component-1\"+E_\"wtt-tnd\"^\"component-2\")`<br />\n",
            "source_data": {
                "years": [
                    2021,
                    2022
                ],
                "sources": {
                    "BEIS": {
                        "Greenhouse gas reporting: conversion factors 2021": {}
                    },
                    "Climatiq": {
                        "Climatiq": {}
                    },
                    "UBA": {
                        "Emissionsbilanz erneuerbarer Energietraeger": {}
                    }
                },
                "regions": {
                    "DE": "Germany",
                    "GB": "United Kingdom",
                    "GLOBAL": "Global"
                },
                "emission_factors": [
                    "District heating",
                    "Natural gas - 100% mineral blend (net CV)",
                    "Renewables"
                ]
            },
            "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"
                }
            ]
        }
    }
}

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://preview.api.climatiq.io/energy/v1-preview1/heat/batch

Fuel Use

POST Calculate the estimated greenhouse gas emissions for fuel combustion.

https://preview.api.climatiq.io/energy/v1-preview1/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, 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.

Request parametersShould be sent as a JSON object in the body

fuel_typerequired string
The type of fuel burned. See choosing a fuel_type for how to choose this.
amountrequired Energy/Volume/Weight object
The amount of fuel burned.
regionstring
The region or country where the fuel was burned.
yearinteger
Default value: Latest year available
The year in which the fuel was burned.
Default Value
Latest year available

curl --request POST \
  --url https://preview.api.climatiq.io/energy/v1-preview1/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.

Response parameters

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.

Example response:

{
    "combustion": {
        "co2e": 837.6,
        "co2e_unit": "kg",
        "co2_biogenic": 11950,
        "calculation_method": "ar5",
        "audit_trail": "`F_\"combustion\" = F_\"414c53d5-8844-4250-8b4d-09a8a1133535\" = 0.1675\"kgco2e/l\"`<br />\n`E_\"fossil\" = F_\"combustion\"*5000\"l\"`<br />\n`F_\"biogenic-combustion\" = F_\"c1c8c8f9-38f4-4057-a245-49e9d8c93798\" = 2.39\"kgco2e/l\"`<br />\n`E_\"biogenic\" = F_\"biogenic-combustion\"*5000\"l\"`<br />\n",
        "source_data": {
            "years": [
                2023
            ],
            "sources": {
                "BEIS": {
                    "Greenhouse gas reporting: conversion factors 2023": {}
                }
            },
            "regions": {
                "GB": "United Kingdom"
            },
            "emission_factors": [
                "Off road biodiesel"
            ]
        },
        "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"
            }
        ]
    },
    "well_to_tank": {
        "co2e": 2238,
        "co2e_unit": "kg",
        "co2_biogenic": null,
        "calculation_method": "ar5",
        "audit_trail": "`F_\"WTT\" = F_\"b4d508d5-d6c5-48e0-a86d-3cca2b268657\" = 0.4476\"kgco2e/l\"`<br />\n`E_\"fossil\" = F_\"WTT\"*5000\"l\"`<br />\n",
        "source_data": {
            "years": [
                2023
            ],
            "sources": {
                "BEIS": {
                    "Greenhouse gas reporting: conversion factors 2023": {}
                }
            },
            "regions": {
                "GB": "United Kingdom"
            },
            "emission_factors": [
                "Off road biodiesel"
            ]
        },
        "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"
            }
        ]
    },
    "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://preview.api.climatiq.io/energy/v1-preview1/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://preview.api.climatiq.io/energy/v1-preview1/fuel/batch

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	float	The total greenhouse gas emissions associated with the consumed energy, expressed in kilograms (kg).
co2_biogenic	float or null	The biogenic CO₂ emissions associated with the consumed energy, expressed in kilograms (kg). This is not included in the `co2e` total.
co2e_unit	string	The unit of measurement for greenhouse gas emissions, which is "kg" (kilograms).
calculation_method	string	Method used for calculating the CO2-equivalent global warming potential of gases, as described in the IPCC assessment reports: The value of this is either `ar4`, `ar5` or `ar6`.
audit_trail	string or absent	Only present with "audit trail" feature. See Advanced audit trail. Not to be confused with our existing audit trail on other endpoints.
source_data	Source data or absent	Only present with "audit trail" feature. Aggregated metadata about the data used for the calculation. This field is deprecated. Prefer the `source_trail` field instead
source_trail	array 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.

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

Advanced audit trailADD-ONADD-ON

A string containing all the information about the calculation we made, this can be stored for future verification purposes.

Audit trail feature

This is not included by default with the energy feature, and requires additionally the "audit trail" premium feature.

This is a trial format for recording information about our calculations for audit purposes that we are trialing for the energy feature. The intention for this data is for use by people who are verifying the estimations, so it contains all the important information about the calculation which was actually performed and which would make reproduction easy.

We intend to improve this feature over time and that will involve changing the format of the data within string in undefined ways, and so the audit_trail string should not be used in a programmatic way in a live application which is sensitive to breakage. Instead, we recommend that you only store the string, alongside the result and your parameters, and it is used offline in conjunction with our documentation.

Usage

We don't currently provide any tooling for this audit trail, currently we recommend that you take your unescaped audit_trail string and paste it into the MathJAX demo tool (opens in a new tab). The tool will format the Asciimath markup into mathematical notation in your browser, which should be enough to understand the calculation which was made.

It will show a number of variable assignments with subscript descriptions.

Key to variable symbols:

Symbol	Description
`E`	Estimation result, showing how it was calculated, unsubscripted for the final estimation and with subscripts for any component estimations which are summed to the final one.
`I`	Intermediate calculation, separated to make the `E` formula easier to read
`F`	Emissions factor, with a subscript either explaining it's role in the calculation or it's Climatiq ID
`C`	Other constant, with a subscript explaining it's role in the calculation
`P`	Parameter, something that the client provided in the request, with a subscript explaining which parameter it is

The other thing you may see is a notice, which are likely the same as the notices described below in a more machine-readable way. In audit trail, they identify a specific part of the calculation or a specific parameter and give more details as to why it is being used. It is usually for where we have incomplete data or edge cases of our methodology.

Here is an example of how a rendered audit trail could look, this is more complicated than most outputs and is intended to show all the features you could encounter. This example has also been edited to fit more easily on the page:

Rendered audit trail example

Source dataADD-ONADD-ON

Source data provides aggregated information about the sources we used to calculate your estimate. These can be used to signal to end users where the data is coming from and how specific it is to their use case. Each field provides a collection of items, where each of the items describes at least one of the sources.

Audit trail feature

This is not included by default with the energy feature, and requires additionally the "audit trail" premium feature.

Attribute	Type	Description
sources	{string -> string -> object}	Mapping of all sources used, to their datasets which were used, to an empty object which may in the future be used to provide access to metadata about the specific dataset
years	array of integers	The years that the source(s) judged their data to be most valid for
regions	{string -> string}	Mapping from region codes which the source data was said to apply to, to the region name
emission_factors	array of strings	List of names of emission factors used in the calculation

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

For Fuel Combustion

Notice code value	description
`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

Energy (preview 2)CBAM (preview)

Energy v1 (preview 1)

Electricity use

Request

Response

Choosing a region

Request

Response

Choosing a supplier

Request

Response

Batch Electricity Use

Heat and Steam use

Request

Response

Batch Heat and Steam Use

Fuel Use

Request

Response

Choosing a fuel_type

Request

Response

Batch Fuel Use

Response models

Energy reporting quad

Energy estimate

Usage

Notice

For Electricity

For Fuel Combustion

Choosing a `region`

Choosing a `supplier`

Choosing a `fuel_type`