Real Estate

Table of contents

• Overview

• Setup

  • Authentication Token

• Query

  • Output Description

• Related Links

Overview

Use the Real Estate API to calculate emissions from building operations and real estate portfolios. The API supports emissions accounting aligned with Scope 3 Category 15 (Investments) under the GHG Protocol, covering operational energy use in commercial and residential buildings such as Office, Retail, Warehouse, and residential mortgage-related property categories.

In the API request, you provide the building type, area, and unit of measurement. The API response provides a breakdown of emissions by gas and an aggregate CO2e value.

Setup

Ensure that Python 3+ is installed on your system.

Note: To run this notebook, you must first add your credentials to '../../../auth/secrets.ini' in the following format:

[EAPI]
api.pat_token = <Your Emissions API PAT token>
api.tenant_id = <Your Emissions API Tenant Id>

# Install the prerequisite Python packages.
%pip install pandas configparser IPython requests

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 a Bearer Token by using your api_key configured in secrets.ini.

config = configparser.RawConfigParser()
config.read(['../../../auth/secrets.ini','../../../auth/config.ini'])

EAPI_PAT_TOKEN      = config.get('EAPI', 'api.pat_token')
EAPI_TENANT_ID      = config.get('EAPI', 'api.tenant_id')
EAPI_CLIENT_ID      = 'ghgemissions-' + EAPI_TENANT_ID

EAPI_AUTH_CLIENT_ID = 'saascore-' + EAPI_TENANT_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}/real-estate"

auth_request_headers: dict = {}
auth_request_headers["X-IBM-Client-Id"] = EAPI_AUTH_CLIENT_ID
auth_request_headers["X-IBM-Envizi-Pat"] = EAPI_PAT_TOKEN

verify = True

auth_url = f"{EAPI_AUTH_ENDPOINT}"

response = requests.post(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 (below) queries IBM Envizi - Emissions API for the emissions generated from 12,345 square meters of Commercial Office space in New York, USA:

payload = {
  "activity": {
    "type": "Commercial Real Estate:Office",
    "value": 12345,
    "unit": "m2"
  },
  "location": {
    "country": "USA",
    "stateProvince": "New York"
  },
  "time": {
    "date": "2022-01-01"
  }
}

# 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 <>`__.

if response.text != "":
    # Get the response as json
    response_json = response.json()

    # Get json and convert to dataframe
    json_str = json.dumps(response_json)
    dict = json.loads(json_str)
    dataframe = pd.json_normalize(dict)

    # display
    print("\n\n")
    pd.set_option('display.max_colwidth', None)
    display( dataframe)
else:
    print("Empty Response")

	transactionId	totalCO2e	energy(MWh)	unit	description
0	c174b8d2-428f-41ca-96bb-7bb73bedc61f	520700.941288	2750.216841	kgCO2e	The Commercial Real Estate emissions factor used to calculate this result was obtained from the CBECS factor set for the United States year 2022 and the region New York.

Output Explanation

transactionId - An Emissions API transaction id.

totalCO2e - The total emissions as CO2 equivalent (CO2e)

energy(MWh) - Total energy consumption of households, expressed in megawatt-hours

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.

Related Links

Emissions API Developer Guide