{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Metadata\n",
    "**Table of contents**\n",
    "\n",
    "- Overview\n",
    "- Setup\n",
    "  - Authentication Token\n",
    "- Example Metadata Queries\n",
    "  - Fugitive Emissions Metadata (Scope 1 Example)\n",
    "  - Calculation Metadata (General API Example)\n",
    "  - Search Metadata (Special Case)\n",
    "- Other Metadata Endpoints\n",
    "- Related Links"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Overview\n",
    "\n",
    "This notebook demonstrates how to query metadata endpoints across the IBM Envizi Emissions API. These endpoints help you discover available data types, units of measurement, and geographic locations for emissions calculations across all scopes.\n",
    "\n",
    "### What are Metadata Endpoints?\n",
    "\n",
    "Metadata endpoints provide essential information about:\n",
    "\n",
    "1. **Available Data Types**: All activity types, fuel types, refrigerants, energy types, and transportation modes supported by each API\n",
    "2. **Units of Measurement**: Valid units for each data type (kg, km, kWh, BTU, etc.)\n",
    "3. **Geographic Locations**: Countries and state/province subdivisions available for calculations\n",
    "\n",
    "### APIs Covered in This Notebook\n",
    "\n",
    "**Scope 1 - Direct Emissions:**\n",
    "- **Fugitive Emissions API**: Refrigerant leaks, HFCs, PFCs, natural gas leaks, and other greenhouse gas releases\n",
    "- **Mobile API**: Fleet vehicles, cars, vans, trucks, and other mobile sources\n",
    "- **Stationary API**: Boilers, furnaces, generators, and stationary fuel combustion\n",
    "\n",
    "**Scope 2 - Indirect Energy Emissions:**\n",
    "- **Location-Based API**: Purchased electricity, steam, chilled water, and hot water\n",
    "\n",
    "**Scope 3 - Other Indirect Emissions:**\n",
    "- **Transportation and Distribution API**: Business travel, freight transport, and logistics\n",
    "\n",
    "**General APIs:**\n",
    "- **Calculation API**: Complete emissions calculations combining activity data with emission factors\n",
    "- **Factor API**: Access to emission factors for custom calculations and audit trails\n",
    "- **Search API**: Keyword-based search and discovery of emission factors\n",
    "\n",
    "### Why Use Metadata Endpoints?\n",
    "\n",
    "- **Discovery**: Find what data types, units, and locations are available before building your application\n",
    "- **Validation**: Ensure your input data uses valid types and units supported by the API\n",
    "- **Planning**: Understand geographic coverage and data availability for your use case\n",
    "- **Integration**: Build dynamic applications that adapt to available options\n",
    "- **Documentation**: Reference guide for building emissions calculation workflows\n",
    "- **Compliance**: Verify that required emission factors are available for your reporting needs\n",
    "\n",
    "### How to Use This Notebook\n",
    "\n",
    "1. **Setup**: Configure your authentication credentials (one-time setup)\n",
    "2. **Explore**: Browse through the example metadata queries\n",
    "3. **Query**: Run the code cells to see available types, units, and locations\n",
    "4. **Reference**: Use the results to build your emissions calculation workflows\n",
    "\n",
    "Each metadata endpoint follows a consistent pattern:\n",
    "- Get available types/data types\n",
    "- Get units for specific types\n",
    "- Get available geographic locations"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Setup\n",
    "\n",
    "Ensure that Python 3+ is installed on your system.\n",
    "\n",
    "<b>Note:</b> To run this notebook, you must first add your credentials to `'../../../auth/secrets.ini'` in the following format:\n",
    "\n",
    "```\n",
    "[EAPI]\n",
    "api.api_key = <Your Emissions API Key>\n",
    "api.tenant_id = <Your Emissions API Tenant Id>\n",
    "api.org_id = <Your Emissions API Org Id>\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Install the prerequisite Python packages\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",
    "\n",
    "Run the following code snippet to generate a Bearer Token by using your api_key configured in secrets.ini."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "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_CLIENT_ID      = 'ghgemissions-' + EAPI_TENANT_ID\n",
    "EAPI_ORG_ID         = config.get('EAPI', 'api.org_id')\n",
    "\n",
    "EAPI_AUTH_CLIENT_ID = 'saascore-' + EAPI_TENANT_ID\n",
    "EAPI_AUTH_ENDPOINT  = config.get('EAPI', 'api.auth_endpoint')\n",
    "\n",
    "EAPI_BASE_URL       = config.get('EAPI', 'api.base_url')\n",
    "EAPI_ENDPOINT       = f\"{EAPI_BASE_URL}\"\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",
    "\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": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Create the query headers for all metadata requests\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"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Example Metadata Queries\n",
    "\n",
    "The following sections demonstrate metadata queries for three representative APIs. All other metadata endpoints follow the same pattern."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Fugitive Metadata (Scope 1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Get Types\n",
    "\n",
    "**Endpoint**: `GET /fugitive/types`\n",
    "\n",
    "This endpoint returns all available fugitive data types that can be used in fugitive emission calculations. Types include:\n",
    "- **HFCs (Hydrofluorocarbons)**: HFC-161, HFC-263fb, etc.\n",
    "- **HFEs (Hydrofluoroethers)**: HFE-569sf2, HFE-338mcf2, HFE-236ea2 (desflurane), etc.\n",
    "- **HFOs (Hydrofluoroolefins)**: HFO-1234ze(Z), etc.\n",
    "- **PFCs (Perfluorocarbons)**: PFC-71-18, etc.\n",
    "- **Refrigerant blends**: R422A, R434A, R-512A, R421B, R-426A, R-438A, R-513A, etc.\n",
    "- **Natural Gas**: Various natural gas types with different scopes\n",
    "- **Other chemicals**: Carbon Tetrachloride, chlorinated compounds, fluorinated compounds, etc."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Total data types available: 575\n",
      "\n",
      "All available fugitive data types for emissions:\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>Fugitive Data Type</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>HFE-569sf2</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>1,1,2-trichloro-ethene</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>R422A</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>2-chloropropane</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>R434A</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>...</th>\n",
       "      <td>...</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>570</th>\n",
       "      <td>HFE-7100</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>571</th>\n",
       "      <td>(e)-hex-2-en-1-ol</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>572</th>\n",
       "      <td>Fluoro(methoxy)methane</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>573</th>\n",
       "      <td>HFE-356mec3</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>574</th>\n",
       "      <td>HFC-245eb</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "<p>575 rows × 1 columns</p>\n",
       "</div>"
      ],
      "text/plain": [
       "         Fugitive Data Type\n",
       "0                HFE-569sf2\n",
       "1    1,1,2-trichloro-ethene\n",
       "2                     R422A\n",
       "3           2-chloropropane\n",
       "4                     R434A\n",
       "..                      ...\n",
       "570                HFE-7100\n",
       "571       (e)-hex-2-en-1-ol\n",
       "572  Fluoro(methoxy)methane\n",
       "573             HFE-356mec3\n",
       "574               HFC-245eb\n",
       "\n",
       "[575 rows x 1 columns]"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "# Query the types endpoint\n",
    "types_url = f\"{EAPI_ENDPOINT}/fugitive/types\"\n",
    "response = requests.get(types_url, headers=request_headers)\n",
    "\n",
    "if response.status_code == 200:\n",
    "    types_data = response.json()\n",
    "    types_df = pd.DataFrame(types_data['types'], columns=['Fugitive Data Type'])\n",
    "    print(f\"Total data types available: {len(types_df)}\\n\")\n",
    "    print(\"All available fugitive data types for emissions:\")\n",
    "    display_summary(types_df)\n",
    "else:\n",
    "    print(f\"Error: {response.status_code}\")\n",
    "    print(response.text)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Get Units for a Type\n",
    "\n",
    "**Endpoint**: `GET /fugitive/units?type={type}`\n",
    "\n",
    "This endpoint returns the available units of measurement for a specific fugitive data type. Common units include:\n",
    "- **Mass units**: g (grams), kg (kilograms), t (tonnes), lb (pounds), st (short tons)\n",
    "- **Large mass units**: thousand lb, million lb\n",
    "\n",
    "Fugitive emissions are typically calculated based on the mass of refrigerant leaked or released.\n",
    "\n",
    "**Example**: Query units for \"R134a:NGERs - Method 1\""
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Available units for 'R134a:NGERs - Method 1':\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>Unit</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>g</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>kg</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>t</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>lb</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>thousand lb</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>5</th>\n",
       "      <td>million lb</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>6</th>\n",
       "      <td>st</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "          Unit\n",
       "0            g\n",
       "1           kg\n",
       "2            t\n",
       "3           lb\n",
       "4  thousand lb\n",
       "5   million lb\n",
       "6           st"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "# Example: Get units for \"R134a:NGERs - Method 1\"\n",
    "data_type = \"R134a:NGERs - Method 1\"\n",
    "units_url = f\"{EAPI_ENDPOINT}/fugitive/units?type={data_type}\"\n",
    "\n",
    "response = requests.get(units_url, headers=request_headers)\n",
    "\n",
    "if response.status_code == 200:\n",
    "    units_data = response.json()\n",
    "    units_df = pd.DataFrame(units_data['units'], columns=['Unit'])\n",
    "    print(f\"Available units for '{data_type}':\\n\")\n",
    "    display_summary(units_df)\n",
    "else:\n",
    "    print(f\"Error: {response.status_code}\")\n",
    "    print(response.text)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Get Available Locations\n",
    "\n",
    "**Endpoint**: `GET /fugitive/area`\n",
    "\n",
    "This endpoint returns all available countries and their state/province subdivisions (where applicable) that can be used in emission calculations. The response includes:\n",
    "- **alpha3**: ISO 3166-1 alpha-3 country code\n",
    "- **countryName**: Full country name\n",
    "- **stateProvinces**: Array of state/province names (for countries with regional data)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Total countries available: 244\n",
      "Countries with state/province subdivisions: 10\n",
      "\n",
      "Sample locations (first 20 rows):\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>Country Code (alpha3)</th>\n",
       "      <th>Country Name</th>\n",
       "      <th>State/Province</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>ABW</td>\n",
       "      <td>Aruba</td>\n",
       "      <td>N/A</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>AFG</td>\n",
       "      <td>Afghanistan</td>\n",
       "      <td>N/A</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>AGO</td>\n",
       "      <td>Angola</td>\n",
       "      <td>N/A</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>AIA</td>\n",
       "      <td>Anguilla</td>\n",
       "      <td>N/A</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>ALA</td>\n",
       "      <td>Åland Islands</td>\n",
       "      <td>N/A</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>5</th>\n",
       "      <td>ALB</td>\n",
       "      <td>Albania</td>\n",
       "      <td>N/A</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>6</th>\n",
       "      <td>AND</td>\n",
       "      <td>Andorra</td>\n",
       "      <td>N/A</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>7</th>\n",
       "      <td>ARE</td>\n",
       "      <td>United Arab Emirates</td>\n",
       "      <td>Abu Dhabi</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>8</th>\n",
       "      <td>ARE</td>\n",
       "      <td>United Arab Emirates</td>\n",
       "      <td>Ajman</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>9</th>\n",
       "      <td>ARE</td>\n",
       "      <td>United Arab Emirates</td>\n",
       "      <td>Dubai</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>10</th>\n",
       "      <td>ARE</td>\n",
       "      <td>United Arab Emirates</td>\n",
       "      <td>Fujairah</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>11</th>\n",
       "      <td>ARE</td>\n",
       "      <td>United Arab Emirates</td>\n",
       "      <td>Ras Al Khaimah</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>12</th>\n",
       "      <td>ARE</td>\n",
       "      <td>United Arab Emirates</td>\n",
       "      <td>Sharjah</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>13</th>\n",
       "      <td>ARE</td>\n",
       "      <td>United Arab Emirates</td>\n",
       "      <td>Umm Al Quwain</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>14</th>\n",
       "      <td>ARG</td>\n",
       "      <td>Argentina</td>\n",
       "      <td>N/A</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>15</th>\n",
       "      <td>ARM</td>\n",
       "      <td>Armenia</td>\n",
       "      <td>N/A</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>16</th>\n",
       "      <td>ATF</td>\n",
       "      <td>French Southern Territories</td>\n",
       "      <td>N/A</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>17</th>\n",
       "      <td>ATG</td>\n",
       "      <td>Antigua and Barbuda</td>\n",
       "      <td>Antigua</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>18</th>\n",
       "      <td>ATG</td>\n",
       "      <td>Antigua and Barbuda</td>\n",
       "      <td>Barbuda</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>19</th>\n",
       "      <td>AUS</td>\n",
       "      <td>Australia</td>\n",
       "      <td>Australian Capital Territory</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "   Country Code (alpha3)                 Country Name  \\\n",
       "0                    ABW                        Aruba   \n",
       "1                    AFG                  Afghanistan   \n",
       "2                    AGO                       Angola   \n",
       "3                    AIA                     Anguilla   \n",
       "4                    ALA                Åland Islands   \n",
       "5                    ALB                      Albania   \n",
       "6                    AND                      Andorra   \n",
       "7                    ARE         United Arab Emirates   \n",
       "8                    ARE         United Arab Emirates   \n",
       "9                    ARE         United Arab Emirates   \n",
       "10                   ARE         United Arab Emirates   \n",
       "11                   ARE         United Arab Emirates   \n",
       "12                   ARE         United Arab Emirates   \n",
       "13                   ARE         United Arab Emirates   \n",
       "14                   ARG                    Argentina   \n",
       "15                   ARM                      Armenia   \n",
       "16                   ATF  French Southern Territories   \n",
       "17                   ATG          Antigua and Barbuda   \n",
       "18                   ATG          Antigua and Barbuda   \n",
       "19                   AUS                    Australia   \n",
       "\n",
       "                  State/Province  \n",
       "0                            N/A  \n",
       "1                            N/A  \n",
       "2                            N/A  \n",
       "3                            N/A  \n",
       "4                            N/A  \n",
       "5                            N/A  \n",
       "6                            N/A  \n",
       "7                      Abu Dhabi  \n",
       "8                          Ajman  \n",
       "9                          Dubai  \n",
       "10                      Fujairah  \n",
       "11                Ras Al Khaimah  \n",
       "12                       Sharjah  \n",
       "13                 Umm Al Quwain  \n",
       "14                           N/A  \n",
       "15                           N/A  \n",
       "16                           N/A  \n",
       "17                       Antigua  \n",
       "18                       Barbuda  \n",
       "19  Australian Capital Territory  "
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "# Query the area endpoint\n",
    "area_url = f\"{EAPI_ENDPOINT}/fugitive/area\"\n",
    "response = requests.get(area_url, headers=request_headers)\n",
    "\n",
    "if response.status_code == 200:\n",
    "    area_data = response.json()\n",
    "    \n",
    "    # Create a list to hold location data\n",
    "    location_list = []\n",
    "    countries_with_states = []\n",
    "    \n",
    "    for location in area_data['locations']:\n",
    "        alpha3 = location.get('alpha3', '')\n",
    "        country_name = location.get('countryName', '')\n",
    "        state_provinces = location.get('stateProvinces', [])\n",
    "        \n",
    "        if state_provinces:\n",
    "            countries_with_states.append(country_name)\n",
    "            # If there are state/provinces, create a row for each\n",
    "            for state in state_provinces:\n",
    "                location_list.append({\n",
    "                    'Country Code (alpha3)': alpha3,\n",
    "                    'Country Name': country_name,\n",
    "                    'State/Province': state\n",
    "                })\n",
    "        else:\n",
    "            # If no state/provinces, just add the country\n",
    "            location_list.append({\n",
    "                'Country Code (alpha3)': alpha3,\n",
    "                'Country Name': country_name,\n",
    "                'State/Province': 'N/A'\n",
    "            })\n",
    "    \n",
    "    locations_df = pd.DataFrame(location_list)\n",
    "    \n",
    "    print(f\"Total countries available: {len(area_data['locations'])}\")\n",
    "    print(f\"Countries with state/province subdivisions: {len(countries_with_states)}\\n\")\n",
    "    print(\"Sample locations (first 20 rows):\")\n",
    "    display_summary(locations_df.head(20))\n",
    "else:\n",
    "    print(f\"Error: {response.status_code}\")\n",
    "    print(response.text)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Calculation Metadata (General API Example)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Get Types\n",
    "\n",
    "**Endpoint**: `GET /carbon/calculation/types`\n",
    "\n",
    "This endpoint returns all available calculation types. These types represent different categories of emissions calculations such as:\n",
    "\n",
    "- Transportation types (vehicles, flights, etc.)\n",
    "- Energy sources (natural gas, electricity, etc.)\n",
    "- Materials and products\n",
    "- Waste management\n",
    "- Industry-specific categories"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Total calculation types available: 5687\n",
      "\n",
      "All available calculation types:\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>Calculation Type</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>Timber and raw forest products</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>Scope 3 - Spend-based USEEIO v1.2:Recreational...</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>Other transportation and support activities:Al...</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>Scope 3 - Spend-based USEEIO v1.2:Plastics Pac...</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>Natural Gas - Scope 3:AAA</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>...</th>\n",
       "      <td>...</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>5682</th>\n",
       "      <td>Material Use - Paper and Board - Board</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>5683</th>\n",
       "      <td>Stainless Steel Sheet Products</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>5684</th>\n",
       "      <td>Company Vehicles:Engine size 1.4-2.0 litres - ...</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>5685</th>\n",
       "      <td>Fluoro(methoxy)methane</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>5686</th>\n",
       "      <td>HFE-356mec3</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "<p>5687 rows × 1 columns</p>\n",
       "</div>"
      ],
      "text/plain": [
       "                                       Calculation Type\n",
       "0                        Timber and raw forest products\n",
       "1     Scope 3 - Spend-based USEEIO v1.2:Recreational...\n",
       "2     Other transportation and support activities:Al...\n",
       "3     Scope 3 - Spend-based USEEIO v1.2:Plastics Pac...\n",
       "4                             Natural Gas - Scope 3:AAA\n",
       "...                                                 ...\n",
       "5682             Material Use - Paper and Board - Board\n",
       "5683                     Stainless Steel Sheet Products\n",
       "5684  Company Vehicles:Engine size 1.4-2.0 litres - ...\n",
       "5685                             Fluoro(methoxy)methane\n",
       "5686                                        HFE-356mec3\n",
       "\n",
       "[5687 rows x 1 columns]"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "# Query the types endpoint\n",
    "types_url = f\"{EAPI_ENDPOINT}/calculation/types\"\n",
    "response = requests.get(types_url, headers=request_headers)\n",
    "\n",
    "if response.status_code == 200:\n",
    "    types_data = response.json()\n",
    "    types_df = pd.DataFrame(types_data['types'], columns=['Calculation Type'])\n",
    "    print(f\"Total calculation types available: {len(types_df)}\\n\")\n",
    "    print(\"All available calculation types:\")\n",
    "    display_summary(types_df)\n",
    "else:\n",
    "    print(f\"Error: {response.status_code}\")\n",
    "    print(response.text)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Get Units for a Type\n",
    "\n",
    "**Endpoint**: `GET /carbon/calculation/units?type={type}`\n",
    "\n",
    "This endpoint returns the available units of measurement for a specific calculation type. Units vary by activity type:\n",
    "\n",
    "- **Spend-based activities**: Typically use currency units (USD)\n",
    "- **Material activities**: May use mass, volume, or currency units\n",
    "- **Transportation**: Distance units (m, km, mi, etc.)\n",
    "- **Waste**: Mass units (kg, t, lb, etc.)\n",
    "- **Refrigerants**: Mass units (g, kg, t, lb, etc.)\n",
    "\n",
    "**Example**: Query units for \"Tobacco products\""
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Available units for 'Tobacco products':\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>Unit</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>usd</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "  Unit\n",
       "0  usd"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "# Example: Get units for \"Tobacco products\"\n",
    "calculation_type = \"Tobacco products\"\n",
    "units_url = f\"{EAPI_ENDPOINT}/calculation/units?type={calculation_type}\"\n",
    "\n",
    "response = requests.get(units_url, headers=request_headers)\n",
    "\n",
    "if response.status_code == 200:\n",
    "    units_data = response.json()\n",
    "    units_df = pd.DataFrame(units_data['units'], columns=['Unit'])\n",
    "    print(f\"Available units for '{calculation_type}':\\n\")\n",
    "    display_summary(units_df)\n",
    "else:\n",
    "    print(f\"Error: {response.status_code}\")\n",
    "    print(response.text)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Get Available Locations\n",
    "\n",
    "**Endpoint**: `GET /carbon/calculation/area`\n",
    "\n",
    "This endpoint returns all available countries and their state/province subdivisions (where applicable) for which calculations are available. The response includes:\n",
    "\n",
    "- **alpha3**: ISO 3166-1 alpha-3 country code\n",
    "- **countryName**: Full country name\n",
    "- **stateProvinces**: Array of state/province names (for countries with regional factors)\n",
    "\n",
    "Location data is crucial as emission factors can vary significantly by region due to:\n",
    "- Different energy grid compositions\n",
    "- Regional regulations and methodologies\n",
    "- Local fuel compositions\n",
    "- Climate and environmental conditions"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Total countries available: 244\n",
      "Countries with state/province subdivisions: 10\n",
      "\n",
      "Sample locations (first 20 rows):\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>Country Code (alpha3)</th>\n",
       "      <th>Country Name</th>\n",
       "      <th>State/Province</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>ABW</td>\n",
       "      <td>Aruba</td>\n",
       "      <td>N/A</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>AFG</td>\n",
       "      <td>Afghanistan</td>\n",
       "      <td>N/A</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>AGO</td>\n",
       "      <td>Angola</td>\n",
       "      <td>N/A</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>AIA</td>\n",
       "      <td>Anguilla</td>\n",
       "      <td>N/A</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>ALA</td>\n",
       "      <td>Åland Islands</td>\n",
       "      <td>N/A</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>5</th>\n",
       "      <td>ALB</td>\n",
       "      <td>Albania</td>\n",
       "      <td>N/A</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>6</th>\n",
       "      <td>AND</td>\n",
       "      <td>Andorra</td>\n",
       "      <td>N/A</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>7</th>\n",
       "      <td>ARE</td>\n",
       "      <td>United Arab Emirates</td>\n",
       "      <td>Abu Dhabi</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>8</th>\n",
       "      <td>ARE</td>\n",
       "      <td>United Arab Emirates</td>\n",
       "      <td>Ajman</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>9</th>\n",
       "      <td>ARE</td>\n",
       "      <td>United Arab Emirates</td>\n",
       "      <td>Dubai</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>10</th>\n",
       "      <td>ARE</td>\n",
       "      <td>United Arab Emirates</td>\n",
       "      <td>Fujairah</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>11</th>\n",
       "      <td>ARE</td>\n",
       "      <td>United Arab Emirates</td>\n",
       "      <td>Ras Al Khaimah</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>12</th>\n",
       "      <td>ARE</td>\n",
       "      <td>United Arab Emirates</td>\n",
       "      <td>Sharjah</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>13</th>\n",
       "      <td>ARE</td>\n",
       "      <td>United Arab Emirates</td>\n",
       "      <td>Umm Al Quwain</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>14</th>\n",
       "      <td>ARG</td>\n",
       "      <td>Argentina</td>\n",
       "      <td>N/A</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>15</th>\n",
       "      <td>ARM</td>\n",
       "      <td>Armenia</td>\n",
       "      <td>N/A</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>16</th>\n",
       "      <td>ATF</td>\n",
       "      <td>French Southern Territories</td>\n",
       "      <td>N/A</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>17</th>\n",
       "      <td>ATG</td>\n",
       "      <td>Antigua and Barbuda</td>\n",
       "      <td>Antigua</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>18</th>\n",
       "      <td>ATG</td>\n",
       "      <td>Antigua and Barbuda</td>\n",
       "      <td>Barbuda</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>19</th>\n",
       "      <td>AUS</td>\n",
       "      <td>Australia</td>\n",
       "      <td>Australian Capital Territory</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "   Country Code (alpha3)                 Country Name  \\\n",
       "0                    ABW                        Aruba   \n",
       "1                    AFG                  Afghanistan   \n",
       "2                    AGO                       Angola   \n",
       "3                    AIA                     Anguilla   \n",
       "4                    ALA                Åland Islands   \n",
       "5                    ALB                      Albania   \n",
       "6                    AND                      Andorra   \n",
       "7                    ARE         United Arab Emirates   \n",
       "8                    ARE         United Arab Emirates   \n",
       "9                    ARE         United Arab Emirates   \n",
       "10                   ARE         United Arab Emirates   \n",
       "11                   ARE         United Arab Emirates   \n",
       "12                   ARE         United Arab Emirates   \n",
       "13                   ARE         United Arab Emirates   \n",
       "14                   ARG                    Argentina   \n",
       "15                   ARM                      Armenia   \n",
       "16                   ATF  French Southern Territories   \n",
       "17                   ATG          Antigua and Barbuda   \n",
       "18                   ATG          Antigua and Barbuda   \n",
       "19                   AUS                    Australia   \n",
       "\n",
       "                  State/Province  \n",
       "0                            N/A  \n",
       "1                            N/A  \n",
       "2                            N/A  \n",
       "3                            N/A  \n",
       "4                            N/A  \n",
       "5                            N/A  \n",
       "6                            N/A  \n",
       "7                      Abu Dhabi  \n",
       "8                          Ajman  \n",
       "9                          Dubai  \n",
       "10                      Fujairah  \n",
       "11                Ras Al Khaimah  \n",
       "12                       Sharjah  \n",
       "13                 Umm Al Quwain  \n",
       "14                           N/A  \n",
       "15                           N/A  \n",
       "16                           N/A  \n",
       "17                       Antigua  \n",
       "18                       Barbuda  \n",
       "19  Australian Capital Territory  "
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "# Query the area endpoint\n",
    "area_url = f\"{EAPI_ENDPOINT}/calculation/area\"\n",
    "response = requests.get(area_url, headers=request_headers)\n",
    "\n",
    "if response.status_code == 200:\n",
    "    area_data = response.json()\n",
    "    \n",
    "    # Create a list to hold location data\n",
    "    location_list = []\n",
    "    countries_with_states = []\n",
    "    \n",
    "    for location in area_data['locations']:\n",
    "        alpha3 = location.get('alpha3', '')\n",
    "        country_name = location.get('countryName', '')\n",
    "        state_provinces = location.get('stateProvinces', [])\n",
    "        \n",
    "        if state_provinces:\n",
    "            countries_with_states.append(country_name)\n",
    "            # If there are state/provinces, create a row for each\n",
    "            for state in state_provinces:\n",
    "                location_list.append({\n",
    "                    'Country Code (alpha3)': alpha3,\n",
    "                    'Country Name': country_name,\n",
    "                    'State/Province': state\n",
    "                })\n",
    "        else:\n",
    "            # If no state/provinces, just add the country\n",
    "            location_list.append({\n",
    "                'Country Code (alpha3)': alpha3,\n",
    "                'Country Name': country_name,\n",
    "                'State/Province': 'N/A'\n",
    "            })\n",
    "    \n",
    "    locations_df = pd.DataFrame(location_list)\n",
    "    \n",
    "    print(f\"Total countries available: {len(area_data['locations'])}\")\n",
    "    print(f\"Countries with state/province subdivisions: {len(countries_with_states)}\\n\")\n",
    "    print(\"Sample locations (first 20 rows):\")\n",
    "    display_summary(locations_df.head(20))\n",
    "else:\n",
    "    print(f\"Error: {response.status_code}\")\n",
    "    print(response.text)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Search Metadata (Special Case)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Get Available Locations\n",
    "\n",
    "**Endpoint**: `GET /factor/search/area`\n",
    "\n",
    "This endpoint returns all available countries and their state/province subdivisions (where applicable) for which emission factors can be searched. The response includes:\n",
    "- **alpha3**: ISO 3166-1 alpha-3 country code\n",
    "- **countryName**: Full country name\n",
    "- **stateProvinces**: Array of state/province names (for countries with regional factors)\n",
    "\n",
    "Understanding location availability is crucial because:\n",
    "- Emission factors vary significantly by region\n",
    "- Some countries have state/province-level granularity\n",
    "- Regional factors reflect local energy grids, fuel compositions, and regulations\n",
    "- You can plan your searches based on available geographic coverage\n",
    "\n",
    "**Note**: The Search API only has an area endpoint. It does not have types or units endpoints since it searches across all factor types."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Total countries available for factor search: 244\n",
      "Countries with state/province subdivisions: 10\n",
      "\n",
      "Sample locations (first 20 rows):\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>Country Code (alpha3)</th>\n",
       "      <th>Country Name</th>\n",
       "      <th>State/Province</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>ABW</td>\n",
       "      <td>Aruba</td>\n",
       "      <td>N/A</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>AFG</td>\n",
       "      <td>Afghanistan</td>\n",
       "      <td>N/A</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>AGO</td>\n",
       "      <td>Angola</td>\n",
       "      <td>N/A</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>AIA</td>\n",
       "      <td>Anguilla</td>\n",
       "      <td>N/A</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>ALA</td>\n",
       "      <td>Åland Islands</td>\n",
       "      <td>N/A</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>5</th>\n",
       "      <td>ALB</td>\n",
       "      <td>Albania</td>\n",
       "      <td>N/A</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>6</th>\n",
       "      <td>AND</td>\n",
       "      <td>Andorra</td>\n",
       "      <td>N/A</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>7</th>\n",
       "      <td>ARE</td>\n",
       "      <td>United Arab Emirates</td>\n",
       "      <td>Abu Dhabi</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>8</th>\n",
       "      <td>ARE</td>\n",
       "      <td>United Arab Emirates</td>\n",
       "      <td>Ajman</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>9</th>\n",
       "      <td>ARE</td>\n",
       "      <td>United Arab Emirates</td>\n",
       "      <td>Dubai</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>10</th>\n",
       "      <td>ARE</td>\n",
       "      <td>United Arab Emirates</td>\n",
       "      <td>Fujairah</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>11</th>\n",
       "      <td>ARE</td>\n",
       "      <td>United Arab Emirates</td>\n",
       "      <td>Ras Al Khaimah</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>12</th>\n",
       "      <td>ARE</td>\n",
       "      <td>United Arab Emirates</td>\n",
       "      <td>Sharjah</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>13</th>\n",
       "      <td>ARE</td>\n",
       "      <td>United Arab Emirates</td>\n",
       "      <td>Umm Al Quwain</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>14</th>\n",
       "      <td>ARG</td>\n",
       "      <td>Argentina</td>\n",
       "      <td>N/A</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>15</th>\n",
       "      <td>ARM</td>\n",
       "      <td>Armenia</td>\n",
       "      <td>N/A</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>16</th>\n",
       "      <td>ATF</td>\n",
       "      <td>French Southern Territories</td>\n",
       "      <td>N/A</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>17</th>\n",
       "      <td>ATG</td>\n",
       "      <td>Antigua and Barbuda</td>\n",
       "      <td>Antigua</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>18</th>\n",
       "      <td>ATG</td>\n",
       "      <td>Antigua and Barbuda</td>\n",
       "      <td>Barbuda</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>19</th>\n",
       "      <td>AUS</td>\n",
       "      <td>Australia</td>\n",
       "      <td>Australian Capital Territory</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "   Country Code (alpha3)                 Country Name  \\\n",
       "0                    ABW                        Aruba   \n",
       "1                    AFG                  Afghanistan   \n",
       "2                    AGO                       Angola   \n",
       "3                    AIA                     Anguilla   \n",
       "4                    ALA                Åland Islands   \n",
       "5                    ALB                      Albania   \n",
       "6                    AND                      Andorra   \n",
       "7                    ARE         United Arab Emirates   \n",
       "8                    ARE         United Arab Emirates   \n",
       "9                    ARE         United Arab Emirates   \n",
       "10                   ARE         United Arab Emirates   \n",
       "11                   ARE         United Arab Emirates   \n",
       "12                   ARE         United Arab Emirates   \n",
       "13                   ARE         United Arab Emirates   \n",
       "14                   ARG                    Argentina   \n",
       "15                   ARM                      Armenia   \n",
       "16                   ATF  French Southern Territories   \n",
       "17                   ATG          Antigua and Barbuda   \n",
       "18                   ATG          Antigua and Barbuda   \n",
       "19                   AUS                    Australia   \n",
       "\n",
       "                  State/Province  \n",
       "0                            N/A  \n",
       "1                            N/A  \n",
       "2                            N/A  \n",
       "3                            N/A  \n",
       "4                            N/A  \n",
       "5                            N/A  \n",
       "6                            N/A  \n",
       "7                      Abu Dhabi  \n",
       "8                          Ajman  \n",
       "9                          Dubai  \n",
       "10                      Fujairah  \n",
       "11                Ras Al Khaimah  \n",
       "12                       Sharjah  \n",
       "13                 Umm Al Quwain  \n",
       "14                           N/A  \n",
       "15                           N/A  \n",
       "16                           N/A  \n",
       "17                       Antigua  \n",
       "18                       Barbuda  \n",
       "19  Australian Capital Territory  "
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "# Query the area endpoint\n",
    "area_url = f\"{EAPI_ENDPOINT}/factor/search/area\"\n",
    "response = requests.get(area_url, headers=request_headers)\n",
    "\n",
    "if response.status_code == 200:\n",
    "    area_data = response.json()\n",
    "    \n",
    "    # Create a list to hold location data\n",
    "    location_list = []\n",
    "    countries_with_states = []\n",
    "    \n",
    "    for location in area_data['locations']:\n",
    "        alpha3 = location.get('alpha3', '')\n",
    "        country_name = location.get('countryName', '')\n",
    "        state_provinces = location.get('stateProvinces', [])\n",
    "        \n",
    "        if state_provinces:\n",
    "            countries_with_states.append(country_name)\n",
    "            # If there are state/provinces, create a row for each\n",
    "            for state in state_provinces:\n",
    "                location_list.append({\n",
    "                    'Country Code (alpha3)': alpha3,\n",
    "                    'Country Name': country_name,\n",
    "                    'State/Province': state\n",
    "                })\n",
    "        else:\n",
    "            # If no state/provinces, just add the country\n",
    "            location_list.append({\n",
    "                'Country Code (alpha3)': alpha3,\n",
    "                'Country Name': country_name,\n",
    "                'State/Province': 'N/A'\n",
    "            })\n",
    "    \n",
    "    locations_df = pd.DataFrame(location_list)\n",
    "    \n",
    "    print(f\"Total countries available for factor search: {len(area_data['locations'])}\")\n",
    "    print(f\"Countries with state/province subdivisions: {len(countries_with_states)}\\n\")\n",
    "    print(\"Sample locations (first 20 rows):\")\n",
    "    display_summary(locations_df.head(20))\n",
    "else:\n",
    "    print(f\"Error: {response.status_code}\")\n",
    "    print(response.text)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Other Metadata Endpoints\n",
    "\n",
    "The following APIs work the same way as the examples above. Simply replace the endpoint name in the URL:\n",
    "\n",
    "### Scope 1 APIs (Direct Emissions)\n",
    "\n",
    "**Mobile Combustion API:**\n",
    "- `GET /mobile/types` - Get all mobile vehicle types\n",
    "- `GET /mobile/units?type={type}` - Get units for a specific vehicle type\n",
    "- `GET /mobile/area` - Get available countries and regions\n",
    "\n",
    "**Stationary Combustion API:**\n",
    "- `GET /stationary/types` - Get all fuel types\n",
    "- `GET /stationary/units?type={type}` - Get units for a specific fuel type\n",
    "- `GET /stationary/area` - Get available countries and regions\n",
    "\n",
    "### Scope 2 APIs (Indirect Energy Emissions)\n",
    "\n",
    "**Location-Based Emissions API:**\n",
    "- `GET /location/types` - Get all energy types (electricity, steam, etc.)\n",
    "- `GET /location/units?type={type}` - Get units for a specific energy type\n",
    "- `GET /location/area` - Get available countries and regions\n",
    "\n",
    "### Scope 3 APIs (Other Indirect Emissions)\n",
    "\n",
    "**Transportation and Distribution API:**\n",
    "- `GET /transportation-and-distribution/types` - Get all transportation types\n",
    "- `GET /transportation-and-distribution/units?type={type}` - Get units for a specific transportation type\n",
    "- `GET /transportation-and-distribution/area` - Get available countries and regions\n",
    "\n",
    "### General APIs\n",
    "\n",
    "**Factor API:**\n",
    "- `GET /factor/types` - Get all activity types with emission factors\n",
    "- `GET /factor/units?type={type}` - Get units for a specific activity type\n",
    "- `GET /factor/area` - Get available countries and regions\n",
    "\n",
    "### Usage Pattern\n",
    "\n",
    "All endpoints follow the same request/response pattern shown in the examples above:\n",
    "\n",
    "1. **Types endpoint**: Returns a list of available types/categories\n",
    "2. **Units endpoint**: Returns valid units for a specific type (requires `type` query parameter)\n",
    "3. **Area endpoint**: Returns available countries and state/province subdivisions\n",
    "\n",
    "Simply copy the code from the examples above and replace:\n",
    "- The endpoint path (e.g., `/fugitive/` → `/mobile/`)\n",
    "- The column names in DataFrames for clarity\n",
    "- The example type values when querying units\n",
    "\n",
    "All responses use the same JSON structure, so the parsing code remains identical."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Related Links\n",
    "\n",
    "[Emissions API Developer Guide](https://developer.ibm.com/apis/catalog/ghgemissions--ibm-envizi-emissions-api/Introduction)"
   ]
  }
 ],
 "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.11.9"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}