{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Factor"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Table of contents**\n",
    "- Overview\n",
    "- Setup\n",
    "  - Authentication Token\n",
    "- Query\n",
    "  - Output Description\n",
    "- Related Links"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Overview"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This notebook focuses on retrieving specific emission factors from the Factor API. It enables users to:\n",
    "\n",
    "- Query for emission factors for specific activities and locations\n",
    "- Override the default factor selection by specifying exact factor sets and versions\n",
    "- Examine detailed metadata about emission factors, including their source and methodology\n",
    "- Understand the composition of emission factors across different greenhouse gases\n",
    "\n",
    "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."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Setup"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "Ensure that you have Python installed in your system. Python 3+ is required.\n",
    "\n",
    "<b>Note:</b> To run this notebook, you must first add your credentials to `config.read('/../../../auth/secrets.ini')` in the following format:\n",
    "\n",
    "```\n",
    "[EAPI]\n",
    "api.api_key = <Your GHG APIs API key>\n",
    "api.client_id = <Your GHG APIs client Id>\n",
    "api.org_id = <Your GHG APIs Org Id>\n",
    "\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Install the packages below using pip/pip3 based on your python version.\n",
    "%pip install pandas configparser IPython requests"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "import pandas as pd\n",
    "import configparser\n",
    "import requests\n",
    "import json\n",
    "from IPython.display import display as display_summary"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Authentication Token\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "Run the following code snippet to generate the Auth Bearer Token by using your api_key configured in secrets.ini."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Authentication Success\n"
     ]
    }
   ],
   "source": [
    "config = configparser.RawConfigParser()\n",
    "config.read(['../../../auth/secrets.ini','../../../auth/config.ini'])\n",
    "\n",
    "EAPI_API_KEY        = config.get('EAPI', 'api.api_key')\n",
    "EAPI_TENANT_ID      = config.get('EAPI', 'api.tenant_id')\n",
    "EAPI_ORG_ID         = config.get('EAPI', 'api.org_id') \n",
    "\n",
    "EAPI_AUTH_ENDPOINT  = config.get('EAPI', 'api.auth_endpoint')\n",
    "EAPI_BASE_URL       = config.get('EAPI', 'api.base_url')\n",
    "EAPI_ENDPOINT       = f\"{EAPI_BASE_URL}/factor\"\n",
    "\n",
    "EAPI_AUTH_CLIENT_ID = 'saascore-' + EAPI_TENANT_ID\n",
    "EAPI_CLIENT_ID      = 'ghgemissions-' + EAPI_TENANT_ID\n",
    "\n",
    "auth_request_headers: dict = {}\n",
    "auth_request_headers[\"X-IBM-CLIENT-ID\"] = EAPI_AUTH_CLIENT_ID\n",
    "auth_request_headers[\"X-API-KEY\"] = EAPI_API_KEY\n",
    "\n",
    "verify = True\n",
    "\n",
    "auth_url = f\"{EAPI_AUTH_ENDPOINT}?orgId={EAPI_ORG_ID}\"\n",
    "              \n",
    "response = requests.get(url = auth_url,\n",
    "                        headers = auth_request_headers,\n",
    "                        verify  = verify\n",
    "                       )\n",
    "if response.status_code == 200:\n",
    "    jwt_token = response.text\n",
    "    print(\"Authentication Success\")\n",
    "else:     \n",
    "    print(\"Authentication Failed\")\n",
    "    print(response.text)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Query"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "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."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
    "payload = {\n",
    "  \"location\": {\n",
    "    \"country\": \"ind\"\n",
    "  },\n",
    "  \"activity\": {\n",
    "    \"type\": \"electricity\",\n",
    "    \"unit\": \"kWh\"\n",
    "  },\n",
    "  \"time\": {\n",
    "    \"date\": \"2022-01-01\"\n",
    "  },\n",
    "  \"factorSet\": \"Managed - NGERS\",\n",
    "  \"factorVersion\": \"2023\"\n",
    "}"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Create the query headers\n",
    "request_headers: dict = {}\n",
    "request_headers[\"Content-Type\"] = \"application/json\"\n",
    "request_headers[\"x-ibm-client-id\"] = EAPI_CLIENT_ID\n",
    "request_headers[\"Authorization\"] = \"Bearer \" + jwt_token\n",
    "\n",
    "# Submit the request\n",
    "response = requests.post(EAPI_ENDPOINT, \n",
    "                         headers = request_headers, \n",
    "                         data = json.dumps(payload))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For more information about allowable parameters for the payload, please see [Emissions API Developer Guide]()."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "\n",
      "\n"
     ]
    },
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>transactionId</th>\n",
       "      <th>totalCO2e</th>\n",
       "      <th>indirectCO2e</th>\n",
       "      <th>unit</th>\n",
       "      <th>description</th>\n",
       "      <th>id</th>\n",
       "      <th>factorSet</th>\n",
       "      <th>source</th>\n",
       "      <th>activityType</th>\n",
       "      <th>activityUnit</th>\n",
       "      <th>name</th>\n",
       "      <th>effectiveFrom</th>\n",
       "      <th>effectiveTo</th>\n",
       "      <th>publishedFrom</th>\n",
       "      <th>publishedTo</th>\n",
       "      <th>region</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>c32c3bc8-2eb3-437c-99ea-bd00d4c9c687</td>\n",
       "      <td>0.54</td>\n",
       "      <td>0.07</td>\n",
       "      <td>kgCO2e</td>\n",
       "      <td>NGER Schedule 1, Item 83</td>\n",
       "      <td>156198</td>\n",
       "      <td>Managed - NGERS</td>\n",
       "      <td>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.</td>\n",
       "      <td>Electricity</td>\n",
       "      <td>kWh</td>\n",
       "      <td>83 - Electricity - 23-24 - Northern Territory</td>\n",
       "      <td>01/07/2023</td>\n",
       "      <td>30/06/2024</td>\n",
       "      <td>01/07/2023</td>\n",
       "      <td>30/06/2024</td>\n",
       "      <td>Earth</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "                          transactionId  totalCO2e  indirectCO2e    unit  \\\n",
       "0  c32c3bc8-2eb3-437c-99ea-bd00d4c9c687       0.54          0.07  kgCO2e   \n",
       "\n",
       "                description      id        factorSet  \\\n",
       "0  NGER Schedule 1, Item 83  156198  Managed - NGERS   \n",
       "\n",
       "                                                                                                                                                                                                                                                                                                                                                        source  \\\n",
       "0  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.   \n",
       "\n",
       "  activityType activityUnit                                           name  \\\n",
       "0  Electricity          kWh  83 - Electricity - 23-24 - Northern Territory   \n",
       "\n",
       "  effectiveFrom effectiveTo publishedFrom publishedTo region  \n",
       "0    01/07/2023  30/06/2024    01/07/2023  30/06/2024  Earth  "
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "if response.text != \"\":\n",
    "    # Get the response as json\n",
    "    response_json = response.json()\n",
    "    \n",
    "    # Get json and convert to dataframe\n",
    "    json_str = json.dumps(response_json)\n",
    "    dict = json.loads(json_str)\n",
    "    dataframe = pd.json_normalize(dict) \n",
    "    \n",
    "    # display\n",
    "    print(\"\\n\\n\")\n",
    "    pd.set_option('display.max_colwidth', None)\n",
    "    display( dataframe) \n",
    "else:\n",
    "    print(\"Empty Response\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Output Description"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<b>transactionId</b> - An Emissions API transaction id.\n",
    "\n",
    "<b>totalCO2e</b>     - The total emissions as CO<sub>2</sub> equivalent (CO<sub>2</sub>e)\n",
    "\n",
    "<b>CO2</b>           - The amount of CO<sub>2</sub> (Carbon Dioxide) in the CO<sub>2</sub>e value.\n",
    "\n",
    "<b>CH4</b>           - The amount of CH<sub>4</sub> (Methane) in the CO<sub>2</sub>e value.\n",
    "\n",
    "<b>N2O</b>           - The amount of N<sub>2</sub>O (Nitrous Oxide) in the CO<sub>2</sub>e value.\n",
    "\n",
    "<b>HFC</b>           - The amount of HFCs (Hydrofluorocarbons) in the CO<sub>2</sub>e value.\n",
    "\n",
    "<b>PFC</b>           - The amount of PFCs (Perfluorocarbons) in the CO<sub>2</sub>e value.\n",
    "\n",
    "<b>SF6</b>           - The amount of SF<sub>6</sub> (Sulphur Hexafluoride) in the CO<sub>2</sub>e value.\n",
    "\n",
    "<b>NF3</b>           - The amount of NF<sub>3</sub> (Nitrogen Trifluoride) in the CO<sub>2</sub>e value.\n",
    "\n",
    "<b>bioCo2</b>        - The amount of bio CO<sub>2</sub> in the CO<sub>2</sub> value.\n",
    "\n",
    "<b>indirectCo2e</b>  - The amount of CO<sub>2</sub>e that is indirect in the CO<sub>2</sub>e value.\n",
    "\n",
    "<b>unit</b>          - The unit of measure of the values.\n",
    "\n",
    "<b>description</b>   - A description of the source factor set of the factor used in the calculation."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Related Links"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "[GHG Emissions API Developer Guide](https://developer.ibm.com/apis/catalog/envintelsuite--ibm-environmental-intelligence/GHG+Emissions+API)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": ".venv",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.12.1"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}