ghg_emissions/tutorials/scope3/transportation_and_distribution_emission.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Transportation and Distribution Emissions"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Table of contents**\n",
    "- Overview\n",
    "- Setup\n",
    "  - Get Token\n",
    "- Utility Functions\n",
    "  - Function to call API\n",
    "  - Input format for API\n",
    "- Example of Transportation and Distribution Emission Query\n",
    "  - Output Explanation\n",
    "- Related Links"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Overview"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Scope 3 Emissions are GHG emissions from upstream or downstream in the value chain of a company, for example, business travel or the transportation of goods.\n",
    "\n",
    "Use this notebook to learn how to calculate transportation and distribution emissions from business-related employee travel, employee commuting, and freight transport."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Setup"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Ensure that Python is installed in your system. Python 3+ is required.\n",
    "\n",
    "\n",
    "<b>Note:</b> To run this notebook seamlessly, you must first configure your credentials for GHG Emission APIs in a file named `secrets.ini` in the following format:\n",
    "\n",
    "```\n",
    "[EI]\n",
    "api.api_key = <Your GHG APIs API key>\n",
    "api.client_id = <Your GHG APIs client Id>\n",
    "\n",
    "```\n",
    "\n",
    "Keep the secrets.ini file at an appropriate relative location of this notebook, for example, as specified in the following config.\n",
    "\n",
    "```config.read('../../auth/secrets.ini')```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Install the packages below using pip/pip3 based on your python version.\n",
    "# pip install pandas,configparser,json,IPython\n",
    "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": [
    "### Get Token"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "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": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "config = configparser.RawConfigParser()\n",
    "config.read(['../../auth/secrets.ini','../../auth/config.ini'])\n",
    "\n",
    "EI_API_KEY  = config.get('EI', 'api.api_key')\n",
    "EI_CLIENT_ID = config.get('EI', 'api.client_id')\n",
    "EI_AUTH_ENPOINT = config.get('EI', 'api.auth_endpoint')\n",
    "EI_BASE_URL = config.get('EI', 'api.base_url')\n",
    "\n",
    "def get_bearer_token(token):\n",
    "    headers = {\n",
    "        'Content-Type': 'application/json',\n",
    "        'cache-control': 'no-cache',\n",
    "    }\n",
    "    data = {\"apiKey\":token, \"clientId\":EI_CLIENT_ID}\n",
    "    bearer_token_req = requests.post(EI_AUTH_ENPOINT, headers=headers, data= json.dumps(data))\n",
    "    if bearer_token_req.status_code != 200:\n",
    "        print( \"Error in getting Bearer token. Error code :\",bearer_token_req.status_code)\n",
    "    return bearer_token_req.json()['access_token']\n",
    "\n",
    "mybearer_token = get_bearer_token(EI_API_KEY)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The following code snippet sets the Transportation and Distribution Emission Parameters.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Utility Functions"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Function to call API"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "def Call_Carbon_API(CO2API, Co2Data, token):\n",
    "    headers = {\n",
    "        'accept': 'application/json',\n",
    "        'Authorization': 'Bearer '+token,\n",
    "        'Content-Type': 'application/json',\n",
    "    }\n",
    "\n",
    "    CO2response_req = requests.post( CO2API, headers=headers, data=json.dumps(Co2Data))\n",
    "    if CO2response_req.status_code != 200:\n",
    "        print( \"Problem! Error in generating response. Error code : \",CO2response_req.status_code)\n",
    "    return CO2response_req.json()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Input format for API"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
    "def customer_id(customerid):\n",
    "    Input =  {\n",
    "              \"id\": customerid\n",
    "          }\n",
    "    return Input \n",
    "\n",
    "def customer_onBehalfOfClient(companyId,companyName):\n",
    "    Input =  {\n",
    "              \"companyId\": companyId,\n",
    "              \"companyName\": companyName\n",
    "          }\n",
    "    return Input  \n",
    "\n",
    "\n",
    "def customer_organisation(departmentId,departmentName):\n",
    "    Input =  {\n",
    "              \"departmentId\": departmentId,\n",
    "              \"departmentName\": departmentName\n",
    "          }\n",
    "    return Input  \n",
    "\n",
    "\n",
    "def customer_requestType(requestType):\n",
    "    Input =  {\n",
    "              \"requestType\": requestType,\n",
    "             }\n",
    "    return Input     \n",
    "\n",
    "\n",
    "def customer_location(country,stateProvince,zipPostCode,city):\n",
    "    Input =  {\n",
    "              \"country\": country,\n",
    "              \"stateProvince\": stateProvince,\n",
    "              \"zipPostCode\": zipPostCode,\n",
    "              \"city\": city\n",
    "          }\n",
    "    return Input        \n",
    "\n",
    "\n",
    "def customer_site(siteId,siteName,buildingId,buildingName):\n",
    "    Input = {\n",
    "              \"siteId\": siteId,\n",
    "              \"siteName\": siteName,\n",
    "              \"buildingId\": buildingId,\n",
    "              \"buildingName\": buildingName\n",
    "          }               \n",
    "    return Input\n",
    "\n",
    "def transportation_and_distribution_input(typeOfActivityData,vehicleType,distanceTravelled,\n",
    "                                          totalWeightOfFreight,numberOfPassengers,unitOfMeasurement,\n",
    "                                          fuelUsed,fuelAmount,unitOfFuelAmount):\n",
    "    input = {\"typeOfActivityData\": typeOfActivityData,\n",
    "             \"vehicleType\": vehicleType,\n",
    "             \"distanceTravelled\": distanceTravelled,\n",
    "             \"totalWeightOfFreight\": totalWeightOfFreight,\n",
    "             \"numberOfPassengers\": numberOfPassengers,\n",
    "             \"unitOfMeasurement\": unitOfMeasurement,\n",
    "             \"fuelUsed\": fuelUsed,\n",
    "             \"fuelAmount\": fuelAmount,\n",
    "             \"unitOfFuelAmount\": unitOfFuelAmount\n",
    "  }\n",
    "    return input"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Example of Transportation and Distribution Emission Query"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can check the accepted values for the individual fields of the request payload. For more information, see [GHG Emissions API Developer Guide](https://developer.ibm.com/apis/catalog/envintelsuite--ibm-environmental-intelligence/GHG+Emissions+API#transportation_and_distribution).\n",
    "\n",
    "Run the following snippet to set the request payload for the Transportation and Distribution Emission Endpoint Query:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Requests payload is : {\n",
      "  \"customID\": {\n",
      "    \"id\": \"Retailer_A_fugitive_31234\"\n",
      "  },\n",
      "  \"onBehalfOfClient\": {\n",
      "    \"companyId\": \"877889877\",\n",
      "    \"companyName\": \"Retailer_A\"\n",
      "  },\n",
      "  \"organisation\": {\n",
      "    \"departmentId\": \"384834\",\n",
      "    \"departmentName\": \"Acme_retail\"\n",
      "  },\n",
      "  \"requestType\": {\n",
      "    \"requestType\": \"ACTUAL\"\n",
      "  },\n",
      "  \"location\": {\n",
      "    \"country\": \"England\",\n",
      "    \"stateProvince\": \"\",\n",
      "    \"zipPostCode\": \"\",\n",
      "    \"city\": \"London\"\n",
      "  },\n",
      "  \"site\": {\n",
      "    \"siteId\": \"T2383823\",\n",
      "    \"siteName\": \"Retailed_A_South_Bank\",\n",
      "    \"buildingId\": \"B38383\",\n",
      "    \"buildingName\": \"Building_6\"\n",
      "  },\n",
      "  \"timePeriod\": {\n",
      "    \"year\": \"2021\",\n",
      "    \"month\": \"1\"\n",
      "  },\n",
      "  \"activityData\": {\n",
      "    \"typeOfActivityData\": \"Weight Distance\",\n",
      "    \"vehicleType\": \"Road Vehicle - HGV - Articulated - Engine Size 3.5 - 33 tonnes\",\n",
      "    \"distanceTravelled\": \"2000\",\n",
      "    \"totalWeightOfFreight\": \"100\",\n",
      "    \"numberOfPassengers\": \"15\",\n",
      "    \"unitOfMeasurement\": \"Tonne Mile\",\n",
      "    \"fuelUsed\": 0,\n",
      "    \"fuelAmount\": 0,\n",
      "    \"unitOfFuelAmount\": 0\n",
      "  }\n",
      "}\n"
     ]
    }
   ],
   "source": [
    "request_payload ={'customID'        : customer_id(customerid='Retailer_A_fugitive_31234'), \n",
    "                   'onBehalfOfClient': customer_onBehalfOfClient(companyId='877889877',\n",
    "                                                                 companyName='Retailer_A') , \n",
    "                   'organisation'    : customer_organisation(departmentId='384834',\n",
    "                                                             departmentName='Acme_retail'), \n",
    "                   'requestType'     : customer_requestType(requestType='ACTUAL'), \n",
    "                   'location'        : customer_location(country='England',\n",
    "                                                         stateProvince='',\n",
    "                                                         zipPostCode='',\n",
    "                                                         city='London'),\n",
    "                   'site'            : customer_site(siteId='T2383823',\n",
    "                                                     siteName='Retailed_A_South_Bank',\n",
    "                                                     buildingId='B38383',\n",
    "                                                     buildingName='Building_6'), \n",
    "                   'timePeriod'      : {'year' : '2021', \n",
    "                                        'month': '1'},\n",
    "                   'activityData' : transportation_and_distribution_input(typeOfActivityData   = 'Weight Distance',\n",
    "                                                                             vehicleType          = 'Road Vehicle - HGV - Articulated - Engine Size 3.5 - 33 tonnes',\n",
    "                                                                             distanceTravelled    = '2000',\n",
    "                                                                             totalWeightOfFreight = '100',\n",
    "                                                                             numberOfPassengers   = '15',\n",
    "                                                                             unitOfMeasurement    = 'Tonne Mile',\n",
    "                                                                             fuelUsed             = 0,\n",
    "                                                                             fuelAmount           = 0,\n",
    "                                                                             unitOfFuelAmount     = 0)\n",
    "                   }        \n",
    "       \n",
    "print(\"Requests payload is :\",json.dumps(request_payload, indent=2))\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Use the following code to run the Transportation and Distribution Emission API:\n",
    "\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<style type=\"text/css\">\n",
       "#T_69c85 table {\n",
       "  display: block;\n",
       "  overflow-x: auto;\n",
       "  white-space: nowrap;\n",
       "}\n",
       "</style>\n",
       "<table id=\"T_69c85\">\n",
       "  <thead>\n",
       "    <tr>\n",
       "      <th class=\"blank level0\" >&nbsp;</th>\n",
       "      <th id=\"T_69c85_level0_col0\" class=\"col_heading level0 col0\" >fossilFuelCO2</th>\n",
       "      <th id=\"T_69c85_level0_col1\" class=\"col_heading level0 col1\" >biogenicCO2</th>\n",
       "      <th id=\"T_69c85_level0_col2\" class=\"col_heading level0 col2\" >CH4</th>\n",
       "      <th id=\"T_69c85_level0_col3\" class=\"col_heading level0 col3\" >N2O</th>\n",
       "      <th id=\"T_69c85_level0_col4\" class=\"col_heading level0 col4\" >CO2e</th>\n",
       "      <th id=\"T_69c85_level0_col5\" class=\"col_heading level0 col5\" >description</th>\n",
       "      <th id=\"T_69c85_level0_col6\" class=\"col_heading level0 col6\" >unitOfMeasurement</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th id=\"T_69c85_level0_row0\" class=\"row_heading level0 row0\" >0</th>\n",
       "      <td id=\"T_69c85_row0_col0\" class=\"data row0 col0\" >65.477292</td>\n",
       "      <td id=\"T_69c85_row0_col1\" class=\"data row0 col1\" >0.000000</td>\n",
       "      <td id=\"T_69c85_row0_col2\" class=\"data row0 col2\" >0.000772</td>\n",
       "      <td id=\"T_69c85_row0_col3\" class=\"data row0 col3\" >0.000595</td>\n",
       "      <td id=\"T_69c85_row0_col4\" class=\"data row0 col4\" >65.656638</td>\n",
       "      <td id=\"T_69c85_row0_col5\" class=\"data row0 col5\" >Emission factors are from Cross-Sector Tools, GHG Protocol. GWP values are obtained from IPCC Fifth Assessment Report, 2014 (AR5)</td>\n",
       "      <td id=\"T_69c85_row0_col6\" class=\"data row0 col6\" >metric tonne</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n"
      ],
      "text/plain": [
       "<pandas.io.formats.style.Styler at 0x11a4383a0>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "EI_API_ENDPOINT = f\"{EI_BASE_URL}/v2/carbon/transportation_and_distribution\"\n",
    "CO2Response = Call_Carbon_API(EI_API_ENDPOINT , request_payload, mybearer_token)\n",
    "df_res = pd.json_normalize(CO2Response)\n",
    "df_styled = df_res.style.set_table_styles([{\n",
    "    'selector': 'table',\n",
    "    'props' : [\n",
    "        ('display', 'block'),\n",
    "        ('overflow-x', 'auto'),\n",
    "        ('white-space', 'nowrap')\n",
    "    ]\n",
    "}])\n",
    "display_summary(df_styled)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Output Explanation"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<b>fossilFuelCO2 </b> -    Release of carbon dioxide in metric tonnes due to burning of fossil fuels.\n",
    "\n",
    "<b>biogenicCO2</b> -       Release of carbon dioxide in metric tonnes due to combustion or decomposition of biomass and its derivatives.\n",
    "\n",
    "<b>CH4 </b>-               Release of methane in metric tonnes.\n",
    "\n",
    "<b>N2O </b>-               Release of nitrous oxide in metric tonnes. \n",
    "\n",
    "<b>CO2e</b> -              Total greenhouse gases emitted in metric tonnes.\n",
    "\n",
    "<b>unitOfMeasurement</b>-  Unit used to measure"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Related Links"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "[GHG Emissions API Developer Guide](https://developer.ibm.com/apis/catalog/envintelsuite--ibm-environmental-intelligence/GHG+Emissions+API)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "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.9.6"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}