Overview of the EC3 Python Wrapper

On By Jared

Intro

Earlier this year I began a little side project to make a Python wrapper for the EC3 BuildingTransparency API. I was originally introduced to the EC3 tool and their EPD (Environmental Product Declaration) database a few years back when I was first getting into quantifying embodied carbon if building structures at Walter P Moore. I recommend anyone interested in this topic who is unfamiliar with the EC3 tool to check out their website and learn more. In short, they’ve been amassing a worldwide database of EPDs for building materials, and have provided tools to connect this data into building projects in order to help quantify environmental impacts. Building Transparency has also made their API available for others to develop tools for interacting with their data.

Why I Made it

While working on some custom tools for querying the EC3 database I often found myself wrestling with the API to get the queries right – the breadth of what the BuildingTransparency API enables is also what makes it very challenging to use. This prompted the idea to build a wrapper in Python (the programming language I tend to use most) to help make these queries and the clean-up of their responses a little easier. I had shelved the idea for some time as there was not any pressing need for it in my day-to-day, but decided to take it on as a little side project with one of the main goals being simply to improve my coding skills. Additionally, over the past year I happened to have a couple former colleagues (who also dabble in Python) asking about how they might interact with the EC3 API – so there were potentially others I figured might benefit from this project.

What it does

The wrapper is currently focused on querying the EC3 database as opposed to wrapping functionality around uploading EPDs or projects. Perhaps in the future the wrapper will expand to include this, but it is not currently a priority. The primary goal of the wrapper is to make queries simpler. Below is an example of a query of EPDs first without the wrapper and then with the wrapper.

#Without the wrapper
import requests
import json

url = "https://etl-api.cqd.io/api/materials"

headers = {
  'Content-Type': 'application/json',
  'X-Total-Count': '100',
  'X-Page-Size': '100',
  'X-Total-Pages': '1',
  'Authorization': USER_TOKEN
}

param_dict = {"concrete_compressive_strength_at_28d__target":"3000 psi", "lightweight":True, "jurisdiction":"US-NY", "epd__date_validity_ends__gt":"2022-04-04"}

response = requests.request("GET", url, headers=headers, params=param_dict)
#With the wrapper
from ec3 import EC3Materials
ec3_materials = EC3Materials(bearer_token=USER_TOKEN)

param_dict = {"concrete_compressive_strength_at_28d__target":"3000 psi", "lightweight":True, "jurisdiction":"US-NY"}

epd_records = ec3_materials.get_materials(params=param_dict)

A couple other functionalities worth highlighting here that the wrapper can help with are cleaning up the responses and searching for materials within a given postal code. By default responses from the BuildingTransparency API will include every possible field regardless of whether a value exists or not, which makes the responses very heavy and ugly to work with. The default setting in the wrapper will remove all null values, though this setting can be changed if you prefer to return the full response.

 

In order to allow for searching of materials within a certain radius of a given postal code, the wrapper incorporates the pgeocode python package to convert postal codes into latitude and longitude. This allows for a frequent request I’ve heard for being able to search for materials and products within a certain region (without having to setup a project in EC3). I built a demonstration Streamlit app that makes use of this functionality for searching concrete mix suppliers within a region. Below is an example of a query for materials within a given region:

#Conduct a search of normal weights concrete mixes between 2000 psi and 8000 psi within a radius of a given postal code
mat_param_dict =   {
                    "product_classes":{"EC3":"Concrete >> ReadyMix"},
                    "lightweight":False, 
                    "concrete_compressive_strength_at_28d__gt":"2000 psi", 
                    "concrete_compressive_strength_at_28d__lt":"8000 psi", 
                    }

ec3_materials.return_fields = ["id", "concrete_compressive_strength_28d", "gwp", "plant_or_group"]
ec3_materials.sort_by = "concrete_compressive_strength_28d" #This will sort the responses based on the field assiged to the 'sort_by' property
ec3_materials.only_valid = True
ec3_materials.max_records = 50
postal_code = 10001

mat_records = ec3_materials.get_materials_within_region(postal_code, plant_distance="10 mi", return_all=False, params=mat_param_dict)

Where it's Going

There’s plenty of functionality within EC3 that is yet to be wrapped by this project. As needs come up I will likely continue to expand and improve what’s currently there. As an open source project, I also welcome any others interested in contributing to do so either directly on github or by providing feedback on potential use cases.