Search¶
Table of contents
Overview
Setup
Authentication Token
Query
Output Description
Related Links
Overview¶
This notebook demonstrates how to use the Search API to find and browse multiple emission factors that match specific criteria. It allows users to:
Search for emission factors using keywords (e.g., “gas”, “electricity”)
Filter results by location and date
Navigate through paginated results to explore all available options
Compare different emission factors before selecting one for calculations
The Search API is valuable for exploration and discovery, helping users understand what emission factors are available before making calculations or when they need to compare multiple methodologies. This is particularly useful when exploring available emissions factors for a specific activity type or region. The results include detailed information about each factor, including its source, scope, unit of measurement, and emissions values, presented in a paginated format for easy navigation through large result sets.
Setup¶
Ensure that you have Python installed in your system. Python 3+ is required.
Note: To run this notebook, you must first add your credentials to config.read('../../../auth/secrets.ini') in the following format:
[EAPI]
api.api_key = <Your GHG APIs API key>
api.client_id = <Your GHG APIs client Id>
api.org_id = <Your GHG APIs Org Id>
[ ]:
# Install the packages below using pip/pip3 based on your python version.
%pip install pandas configparser IPython requests
[1]:
import pandas as pd
import configparser
import requests
import json
from IPython.display import display as display_summary
Authentication Token¶
Run the following code snippet to generate the Auth Bearer Token by using your api_key configured in secrets.ini.
[2]:
config = configparser.RawConfigParser()
config.read(['../../../auth/secrets.ini','../../../auth/config.ini'])
EAPI_API_KEY = config.get('EAPI', 'api.api_key')
EAPI_TENANT_ID = config.get('EAPI', 'api.tenant_id')
EAPI_ORG_ID = config.get('EAPI', 'api.org_id')
EAPI_AUTH_ENDPOINT = config.get('EAPI', 'api.auth_endpoint')
EAPI_BASE_URL = config.get('EAPI', 'api.base_url')
EAPI_ENDPOINT = f"{EAPI_BASE_URL}/factor/search"
EAPI_AUTH_CLIENT_ID = 'saascore-' + EAPI_TENANT_ID
EAPI_CLIENT_ID = 'ghgemissions-' + EAPI_TENANT_ID
auth_request_headers: dict = {}
auth_request_headers["X-IBM-CLIENT-ID"] = EAPI_AUTH_CLIENT_ID
auth_request_headers["X-API-KEY"] = EAPI_API_KEY
verify = True
auth_url = f"{EAPI_AUTH_ENDPOINT}?orgId={EAPI_ORG_ID}"
response = requests.get(url = auth_url,
headers = auth_request_headers,
verify = verify
)
if response.status_code == 200:
jwt_token = response.text
print("Authentication Success")
else:
print("Authentication Failed")
print(response.text)
Authentication Success
Query¶
The example request payload demonstrates how to search for emission factors using IBM Envizi - Emissions API by specifying location (India), a keyword (“gas”), pagination parameters (page 1, 30 results), and a reference date (January 4, 2024).
[3]:
payload = {
"location": {
"country": "ind"
},
"activity": {
"search": "gas"
},
"pagination": {
"page": 1,
"size": 30
},
"time": {
"date": "2024-01-04"
}
}
[4]:
# Create the query headers
request_headers: dict = {}
request_headers["Content-Type"] = "application/json"
request_headers["x-ibm-client-id"] = EAPI_CLIENT_ID
request_headers["Authorization"] = "Bearer " + jwt_token
# Submit the request
response = requests.post(EAPI_ENDPOINT,
headers = request_headers,
data = json.dumps(payload))
For more information about allowable parameters for the payload, please see `Emissions API Developer Guide <>`__.
[5]:
if response.status_code == 200 and response.text:
# Parse the JSON response
response_json = response.json()
# Extract the factors list
factors_list = response_json.get('factors', [])
# Create dataframe from factors list
df_factors = pd.json_normalize(factors_list)
# Display settings and results
print(f"\nFound {len(factors_list)} matching factors\n")
pd.set_option('display.max_colwidth', None)
display_summary(df_factors)
else:
print(f"Error: {response.status_code}")
print(f"Response: {response.text}")
Found 30 matching factors
| factorSet | source | activityType | activityUnit | effectiveFrom | publishedFrom | region | factorId | |
|---|---|---|---|---|---|---|---|---|
| 0 | Managed - eGRID & US Climate Leaders | Supply Chain Greenhouse Gas Emission Factors v1.3 by NAICS-6, Publisher: U.S. EPA Office of Research and Development (ORD). Published on: 10-July-2024 | Mining, except oil and gas | USD | 01/01/2024 | 01/01/2024 | Earth | 162166 |
| 1 | Managed - eGRID & US Climate Leaders | Supply Chain Greenhouse Gas Emission Factors v1.3 by NAICS-6, Publisher: U.S. EPA Office of Research and Development (ORD). Published on: 10-July-2024 | Mining, except oil and gas | USD | 01/01/2024 | 01/01/2024 | Earth | 162167 |
| 2 | Managed - eGRID & US Climate Leaders | Supply Chain Greenhouse Gas Emission Factors v1.3 by NAICS-6, Publisher: U.S. EPA Office of Research and Development (ORD). Published on: 10-July-2024 | Mining, except oil and gas | USD | 01/01/2024 | 01/01/2024 | Earth | 162168 |
| 3 | Managed - eGRID & US Climate Leaders | Supply Chain Greenhouse Gas Emission Factors v1.3 by NAICS-6, Publisher: U.S. EPA Office of Research and Development (ORD). Published on: 10-July-2024 | Mining, except oil and gas | USD | 01/01/2024 | 01/01/2024 | Earth | 162169 |
| 4 | Managed - eGRID & US Climate Leaders | Supply Chain Greenhouse Gas Emission Factors v1.3 by NAICS-6, Publisher: U.S. EPA Office of Research and Development (ORD). Published on: 10-July-2024 | Mining, except oil and gas | USD | 01/01/2024 | 01/01/2024 | Earth | 162170 |
| 5 | Managed - eGRID & US Climate Leaders | Supply Chain Greenhouse Gas Emission Factors v1.3 by NAICS-6, Publisher: U.S. EPA Office of Research and Development (ORD). Published on: 10-July-2024 | Mining, except oil and gas | USD | 01/01/2024 | 01/01/2024 | Earth | 162171 |
| 6 | Managed - eGRID & US Climate Leaders | US EPA. Feb 2024. EPA Centre for Climate Leadership. Emission Factors for Greenhouse Gas Inventories - https://www.epa.gov/climateleadership/ghg-emission-factors-hub | Natural Gas | 100 cf | 01/01/2024 | 01/01/2024 | Earth | 162923 |
| 7 | Managed - eGRID & US Climate Leaders | US EPA. Feb 2024. EPA Centre for Climate Leadership. Emission Factors for Greenhouse Gas Inventories - https://www.epa.gov/climateleadership/ghg-emission-factors-hub | Natural Gas | 1000 cf | 01/01/2024 | 01/01/2024 | Earth | 162924 |
| 8 | Managed - eGRID & US Climate Leaders | US EPA. Feb 2024. EPA Centre for Climate Leadership. Emission Factors for Greenhouse Gas Inventories - https://www.epa.gov/climateleadership/ghg-emission-factors-hub | Natural Gas | ccf | 01/01/2024 | 01/01/2024 | Earth | 162925 |
| 9 | Managed - eGRID & US Climate Leaders | US EPA. Feb 2024. EPA Centre for Climate Leadership. Emission Factors for Greenhouse Gas Inventories - https://www.epa.gov/climateleadership/ghg-emission-factors-hub | Natural Gas | cf | 01/01/2024 | 01/01/2024 | Earth | 162926 |
| 10 | Managed - eGRID & US Climate Leaders | US EPA. Feb 2024. EPA Centre for Climate Leadership. Emission Factors for Greenhouse Gas Inventories - https://www.epa.gov/climateleadership/ghg-emission-factors-hub | Natural Gas - Scope 2 | cf | 01/01/2024 | 01/01/2024 | Earth | 169709 |
| 11 | Managed - eGRID & US Climate Leaders | US EPA. Feb 2024. EPA Centre for Climate Leadership. Emission Factors for Greenhouse Gas Inventories - https://www.epa.gov/climateleadership/ghg-emission-factors-hub | Natural Gas - Scope 3 | cf | 01/01/2024 | 01/01/2024 | Earth | 162927 |
| 12 | Managed - eGRID & US Climate Leaders | US EPA. Feb 2024. EPA Centre for Climate Leadership. Emission Factors for Greenhouse Gas Inventories - https://www.epa.gov/climateleadership/ghg-emission-factors-hub | Natural Gas | dekatherms | 01/01/2024 | 01/01/2024 | Earth | 162928 |
| 13 | Managed - eGRID & US Climate Leaders | US EPA. Feb 2024. EPA Centre for Climate Leadership. Emission Factors for Greenhouse Gas Inventories - https://www.epa.gov/climateleadership/ghg-emission-factors-hub | Natural Gas | GJ | 01/01/2024 | 01/01/2024 | Earth | 162929 |
| 14 | Managed - eGRID & US Climate Leaders | US EPA. Feb 2024. EPA Centre for Climate Leadership. Emission Factors for Greenhouse Gas Inventories - https://www.epa.gov/climateleadership/ghg-emission-factors-hub | Natural Gas | kBtu | 01/01/2024 | 01/01/2024 | Earth | 162930 |
| 15 | Managed - eGRID & US Climate Leaders | US EPA. Feb 2024. EPA Centre for Climate Leadership. Emission Factors for Greenhouse Gas Inventories - https://www.epa.gov/climateleadership/ghg-emission-factors-hub | Natural Gas | kWh | 01/01/2024 | 01/01/2024 | Earth | 162931 |
| 16 | Managed - eGRID & US Climate Leaders | US EPA. Feb 2024. EPA Centre for Climate Leadership. Emission Factors for Greenhouse Gas Inventories - https://www.epa.gov/climateleadership/ghg-emission-factors-hub | Natural Gas | m3 | 01/01/2024 | 01/01/2024 | Earth | 162933 |
| 17 | Managed - eGRID & US Climate Leaders | US EPA. Feb 2024. EPA Centre for Climate Leadership. Emission Factors for Greenhouse Gas Inventories - https://www.epa.gov/climateleadership/ghg-emission-factors-hub | Natural Gas - Scope 3 | m3 | 01/01/2024 | 01/01/2024 | Earth | 162934 |
| 18 | Managed - eGRID & US Climate Leaders | US EPA. Feb 2024. EPA Centre for Climate Leadership. Emission Factors for Greenhouse Gas Inventories - https://www.epa.gov/climateleadership/ghg-emission-factors-hub | Natural Gas | MJ | 01/01/2024 | 01/01/2024 | Earth | 162935 |
| 19 | Managed - eGRID & US Climate Leaders | US EPA. Feb 2024. EPA Centre for Climate Leadership. Emission Factors for Greenhouse Gas Inventories - https://www.epa.gov/climateleadership/ghg-emission-factors-hub | Natural Gas | MMBtu | 01/01/2024 | 01/01/2024 | Earth | 162936 |
| 20 | Managed - eGRID & US Climate Leaders | US EPA. Feb 2024. EPA Centre for Climate Leadership. Emission Factors for Greenhouse Gas Inventories - https://www.epa.gov/climateleadership/ghg-emission-factors-hub | Natural Gas - Scope 3 | MMBtu | 01/01/2024 | 01/01/2024 | Earth | 162937 |
| 21 | Managed - eGRID & US Climate Leaders | US EPA. Feb 2024. EPA Centre for Climate Leadership. Emission Factors for Greenhouse Gas Inventories - https://www.epa.gov/climateleadership/ghg-emission-factors-hub | Natural Gas | therms | 01/01/2024 | 01/01/2024 | Earth | 162938 |
| 22 | Managed - eGRID & US Climate Leaders | US EPA. Feb 2024. EPA Centre for Climate Leadership. Emission Factors for Greenhouse Gas Inventories - https://www.epa.gov/climateleadership/ghg-emission-factors-hub | Natural Gas - CO2 Only | therms | 01/01/2024 | 01/01/2024 | Earth | 162939 |
| 23 | Managed - eGRID & US Climate Leaders | US EPA. Feb 2024. EPA Centre for Climate Leadership. Emission Factors for Greenhouse Gas Inventories - https://www.epa.gov/climateleadership/ghg-emission-factors-hub | Natural Gas - Scope 2 | therms | 01/01/2024 | 01/01/2024 | Earth | 162940 |
| 24 | Managed - eGRID & US Climate Leaders | US EPA. Feb 2024. EPA Centre for Climate Leadership. Emission Factors for Greenhouse Gas Inventories - https://www.epa.gov/climateleadership/ghg-emission-factors-hub | Natural Gas - Scope 3 | therms | 01/01/2024 | 01/01/2024 | Earth | 162941 |
| 25 | Managed - eGRID & US Climate Leaders | Supply Chain Factors Dataset v1.1.1, Tab: 2016_Detail_Commodity, Citation: Ingwersen, W. AND M. Li. Supply Chain Greenhouse Gas Emission Factors for US Industries and Commodities. U.S. Environmental Protection Agency, Washington, DC, EPA/600/R-20/001, 2020. | Natural Gas | USD | 01/01/2024 | 01/01/2024 | Earth | 164378 |
| 26 | Managed - eGRID & US Climate Leaders | Supply Chain Greenhouse Gas Emission Factors v1.3 by NAICS-6, Publisher: U.S. EPA Office of Research and Development (ORD). Published on: 10-July-2024 | Oil and gas extraction | USD | 01/01/2024 | 01/01/2024 | Earth | 162285 |
| 27 | Managed - eGRID & US Climate Leaders | Supply Chain Greenhouse Gas Emission Factors v1.3 by NAICS-6, Publisher: U.S. EPA Office of Research and Development (ORD). Published on: 10-July-2024 | Oil and gas extraction | USD | 01/01/2024 | 01/01/2024 | Earth | 162286 |
| 28 | Managed - eGRID & US Climate Leaders | Supply Chain Factors Dataset v1.1.1, Tab: 2016_Summary_Commodity, Citation: Ingwersen, W. AND M. Li. Supply Chain Greenhouse Gas Emission Factors for US Industries and Commodities. U.S. Environmental Protection Agency, Washington, DC, EPA/600/R-20/001, 2020. | Oil and gas extraction | USD | 01/01/2024 | 01/01/2024 | Earth | 164065 |
| 29 | Managed - eGRID & US Climate Leaders | Supply Chain Factors Dataset v1.1.1, Tab: 2016_Summary_Commodity, Citation: Ingwersen, W. AND M. Li. Supply Chain Greenhouse Gas Emission Factors for US Industries and Commodities. U.S. Environmental Protection Agency, Washington, DC, EPA/600/R-20/001, 2020. | Oil and gas extraction | USD | 01/01/2024 | 01/01/2024 | Earth | 164131 |
Output Description¶
transactionId - An Emissions API transaction id.
totalCO2e - The total emissions as CO2 equivalent (CO2e)
CO2 - The amount of CO2 (Carbon Dioxide) in the CO2e value.
CH4 - The amount of CH4 (Methane) in the CO2e value.
N2O - The amount of N2O (Nitrous Oxide) in the CO2e value.
HFC - The amount of HFCs (Hydrofluorocarbons) in the CO2e value.
PFC - The amount of PFCs (Perfluorocarbons) in the CO2e value.
SF6 - The amount of SF6 (Sulphur Hexafluoride) in the CO2e value.
NF3 - The amount of NF3 (Nitrogen Trifluoride) in the CO2e value.
bioCo2 - The amount of bio CO2 in the CO2 value.
indirectCo2e - The amount of CO2e that is indirect in the CO2e value.
unit - The unit of measure of the values.
description - A description of the source factor set of the factor used in the calculation.