Factor

Table of contents

  • Overview

  • Setup

    • Authentication Token

  • Query

    • Output Description

  • Related Links

Overview

This notebook focuses on retrieving specific emission factors from the Factor API. It enables users to:

  • Query for emission factors for specific activities and locations

  • Override the default factor selection by specifying exact factor sets and versions

  • Examine detailed metadata about emission factors, including their source and methodology

  • Understand the composition of emission factors across different greenhouse gases

The Factor API gives users precise control over which emissions factors are applied to their calculations. This granular access is essential for regulatory compliance where specific methodologies must be used, for creating transparent audit trails that document exactly which factors were applied, for maintaining consistent reporting methodologies across time periods, and for performing comparative analyses using different factor sets. By exposing the raw emissions factors with their complete metadata, the API supports sophisticated sustainability reporting and compliance workflows.

Setup

Ensure that you have Python installed in your system. Python 3+ is required.

Note: To run this notebook, you must first add your credentials to config.read('/../../../auth/secrets.ini') in the following format:

[EAPI]
api.api_key = <Your GHG APIs API key>
api.client_id = <Your GHG APIs client Id>
api.org_id = <Your GHG APIs Org Id>

[ ]:

# Install the packages below using pip/pip3 based on your python version.
%pip install pandas configparser IPython requests

[2]:

import pandas as pd
import configparser
import requests
import json
from IPython.display import display as display_summary

Authentication Token

Run the following code snippet to generate the Auth Bearer Token by using your api_key configured in secrets.ini.

[3]:

config = configparser.RawConfigParser()
config.read(['../../../auth/secrets.ini','../../../auth/config.ini'])

EAPI_API_KEY        = config.get('EAPI', 'api.api_key')
EAPI_TENANT_ID      = config.get('EAPI', 'api.tenant_id')
EAPI_ORG_ID         = config.get('EAPI', 'api.org_id')

EAPI_AUTH_ENDPOINT  = config.get('EAPI', 'api.auth_endpoint')
EAPI_BASE_URL       = config.get('EAPI', 'api.base_url')
EAPI_ENDPOINT       = f"{EAPI_BASE_URL}/factor"

EAPI_AUTH_CLIENT_ID = 'saascore-' + EAPI_TENANT_ID
EAPI_CLIENT_ID      = 'ghgemissions-' + EAPI_TENANT_ID

auth_request_headers: dict = {}
auth_request_headers["X-IBM-CLIENT-ID"] = EAPI_AUTH_CLIENT_ID
auth_request_headers["X-API-KEY"] = EAPI_API_KEY

verify = True

auth_url = f"{EAPI_AUTH_ENDPOINT}?orgId={EAPI_ORG_ID}"

response = requests.get(url = auth_url,
                        headers = auth_request_headers,
                        verify  = verify
                       )
if response.status_code == 200:
    jwt_token = response.text
    print("Authentication Success")
else:
    print("Authentication Failed")
    print(response.text)

Authentication Success

Query

The example request payload queries IBM Envizi - Emissions API with location data (India), activity information (electricity consumption measured in kWh), and a specific date (January 1, 2022). By including the optional parameters factorSet: “Managed - NGERS” and factorVersion: “2023”, the request explicitly overrides the API’s default factor selection algorithm.

[4]:

payload = {
  "location": {
    "country": "ind"
  },
  "activity": {
    "type": "electricity",
    "unit": "kWh"
  },
  "time": {
    "date": "2022-01-01"
  },
  "factorSet": "Managed - NGERS",
  "factorVersion": "2023"
}

[5]:

# Create the query headers
request_headers: dict = {}
request_headers["Content-Type"] = "application/json"
request_headers["x-ibm-client-id"] = EAPI_CLIENT_ID
request_headers["Authorization"] = "Bearer " + jwt_token

# Submit the request
response = requests.post(EAPI_ENDPOINT,
                         headers = request_headers,
                         data = json.dumps(payload))

For more information about allowable parameters for the payload, please see `Emissions API Developer Guide <>`__.

[6]:

if response.text != "":
    # Get the response as json
    response_json = response.json()

    # Get json and convert to dataframe
    json_str = json.dumps(response_json)
    dict = json.loads(json_str)
    dataframe = pd.json_normalize(dict)

    # display
    print("\n\n")
    pd.set_option('display.max_colwidth', None)
    display( dataframe)
else:
    print("Empty Response")
transactionId totalCO2e indirectCO2e unit description id factorSet source activityType activityUnit name effectiveFrom effectiveTo publishedFrom publishedTo region
0 c32c3bc8-2eb3-437c-99ea-bd00d4c9c687 0.54 0.07 kgCO2e NGER Schedule 1, Item 83 156198 Managed - NGERS National Greenhouse and Energy Reporting (Measurement) Determination 2008 (compiled 1 July 2023). Sourced from the Federal Register of Legislation at October 2023 and ongoing. For the latest information on Australian Government law please go to https://www.legislation.gov.au. Indirect Factor - NGA workbook (where applicable), published Aug 2023. Electricity kWh 83 - Electricity - 23-24 - Northern Territory 01/07/2023 30/06/2024 01/07/2023 30/06/2024 Earth

Output Description

transactionId - An Emissions API transaction id.

totalCO2e - The total emissions as CO2 equivalent (CO2e)

CO2 - The amount of CO2 (Carbon Dioxide) in the CO2e value.

CH4 - The amount of CH4 (Methane) in the CO2e value.

N2O - The amount of N2O (Nitrous Oxide) in the CO2e value.

HFC - The amount of HFCs (Hydrofluorocarbons) in the CO2e value.

PFC - The amount of PFCs (Perfluorocarbons) in the CO2e value.

SF6 - The amount of SF6 (Sulphur Hexafluoride) in the CO2e value.

NF3 - The amount of NF3 (Nitrogen Trifluoride) in the CO2e value.

bioCo2 - The amount of bio CO2 in the CO2 value.

indirectCo2e - The amount of CO2e that is indirect in the CO2e value.

unit - The unit of measure of the values.

description - A description of the source factor set of the factor used in the calculation.