{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "# Calculation" ] }, { "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": [ "The Calculation endpoint provides a versatile, general-purpose solution for emissions calculations across any activity type supported by the system. Unlike scope-specific endpoints that are tailored for particular use cases, this endpoint offers flexibility to handle a wide range of scenarios where specialized endpoints might not exist. It allows users to:\n", "\n", "- Calculate emissions from various activities like energy use, transportation, and material consumption\n", "- Specify location data to get region-specific calculations\n", "- Include date information to ensure time-relevant emission factors are used\n", "- Receive detailed breakdown of emissions by gas type (CO2, CH4, N2O, etc.)\n", "\n", "The Calculation API serves as a versatile, general-purpose solution for emissions calculations that aren't covered by specialized endpoints. It provides flexibility to handle a wide range of activity types using a consistent interface, automatically selecting appropriate emission factors based on the provided parameters. This API is particularly valuable when dealing with uncommon activities, when specialized endpoints don't exist for specific use cases, or when organizations need to quickly implement emissions calculations without developing multiple integrations." ] }, { "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", "Note: To run this notebook, you must first add your credentials to `config.read('../../../auth/secrets.ini')` in the following format:\n", "\n", "\n", "```\n", "[EAPI]\n", "api.api_key = \n", "api.client_id = \n", "api.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": 1, "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, client_id and org_id 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}/calculation\"\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 (below) queries IBM Envizi - Emissions API with location data (India), activity information (adhesives with a value of 12 USD), and a specific date (January 4, 2024)." ] }, { "cell_type": "code", "execution_count": 4, "metadata": {}, "outputs": [], "source": [ "payload = {\n", " \"location\": {\n", " \"country\": \"ind\"\n", " },\n", " \"activity\": {\n", " \"value\": [\n", " 12\n", " ],\n", " \"type\": \"Adhesives\",\n", " \"unit\": [\n", " \"USD\"\n", " ]\n", " },\n", " \"time\": {\n", " \"date\": \"2024-01-04\"\n", " }\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": [ "
\n", "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "
transactionIdtotalCO2eCO2CH4indirectCO2eunitdescription
09eb24f2a-7ef1-49cc-a057-0f31b6f36e169.0968.3760.60.396kgCO2eThe Adhesives emissions factor used to calculate this result was obtained from the Managed - eGRID & US Climate Leaders factor set for the area Earth year 2023.
\n", "
" ], "text/plain": [ " transactionId totalCO2e CO2 CH4 indirectCO2e \\\n", "0 9eb24f2a-7ef1-49cc-a057-0f31b6f36e16 9.096 8.376 0.6 0.396 \n", "\n", " unit \\\n", "0 kgCO2e \n", "\n", " description \n", "0 The Adhesives emissions factor used to calculate this result was obtained from the Managed - eGRID & US Climate Leaders factor set for the area Earth year 2023. " ] }, "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": [ "transactionId - An Emissions API transaction id.\n", "\n", "totalCO2e - The total emissions as CO2 equivalent (CO2e)\n", "\n", "CO2 - The amount of CO2 (Carbon Dioxide) in the CO2e value.\n", "\n", "CH4 - The amount of CH4 (Methane) in the CO2e value.\n", "\n", "N2O - The amount of N2O (Nitrous Oxide) in the CO2e value.\n", "\n", "HFC - The amount of HFCs (Hydrofluorocarbons) in the CO2e value.\n", "\n", "PFC - The amount of PFCs (Perfluorocarbons) in the CO2e value.\n", "\n", "SF6 - The amount of SF6 (Sulphur Hexafluoride) in the CO2e value.\n", "\n", "NF3 - The amount of NF3 (Nitrogen Trifluoride) in the CO2e value.\n", "\n", "bioCo2 - The amount of bio CO2 in the CO2 value.\n", "\n", "indirectCo2e - The amount of CO2e that is indirect in the CO2e value.\n", "\n", "unit - The unit of measure of the values.\n", "\n", "description - 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 }