Quickstart: Read and Write EPDs

In this guide we will create a simple Python script which prints out some EPDs available from the BuildingTransparency.org openEPD server.

Walkthrough

Set up Python environment and install Library

Ensure you have a working python 3.11+ with pip.
Ensure you have virtualenv module by running pip install virtualenv.
Create a directory for your project.
Open a terminal and enter the project directory.
Create a new virtual environment for your sample walkthrough. python -m venv .venv
This will create a directory .venv within your sample project directory, which will contain all dependencies
Activate the newly created virtual environment:
Linux or Mac: source ./.venv/bin/activate
Windows: .\.venv\Scripts\activate
Install openepd library with pip install openepd[api-client]==1.*. This library contains both Pydantic models for openEPD objects and API client to access the API in a type-safe way.
The current working major version is 1.*; while the 2.* library is in development.

Obtain API key for the BuildingTransparency openEPD API

Visit EC3 and sign up for an account.
When logged in, Navigate to EC3 Key Management, and create a new API key.

Run sample script

Following script will print out the 5 most recently updated EPDs for a ready mix concrete with compressive strength greater than 30 MPa at 28 days.

This script expects an environment variable containing OPENEPD_API_TOKEN, please set it to the key obtained previously.

To provide an env var on Linux/mac, run export OPENEPD_API_TOKEN=your_api_key_here, on Windows, run set OPENEPD_API_TOKEN=your_api_key in the terminal before executing script.

import os

# import API client
from openepd.api.sync_client import OpenEpdApiClientSync

EC3_BASE_URL = "https://buildingtransparency.org/epds/"


def run_openepd_script():
    # ensure we have an API token
    token = os.getenv("OPENEPD_API_TOKEN", None)
    if not token:
        raise ValueError(
            "OPENEPD_API_TOKEN environment variable should be set."
            "Create a key at "
            "https://buildingtransparency.org/ec3/manage-apps/keys")

    # create an API client
    client = OpenEpdApiClientSync(
        base_url="https://openepd.buildingtransparency.org/api",
        auth_token=token)

    # search query uses Open Material Filter - special language for
    # querying EPD's material's performance
    # parameters
    omf_query = ('!EC3 search("ReadyMix") '
                 'valid_until: >"2024-03-08" '
                 'and specs.concrete.strength_28d: >"30 MPa" '
                 '!pragma oMF("1.0/1")')

    print("> Connecting to openEPD API...")
    print("> Searching for ReadyMixes with compressive "
          "strength greater than 30 MPa at 28th day...")

    # Execute API call to the server.
    # Response is wrapped in a lazy iterator which
    # will fetch more data as needed; see openepd.api.StreamingListResponse
    response = client.epds.find(omf_query, page_size=5)
    print(f"< Total EPDs found: {response.get_total_count()}")

    print("> Fetching first 5 EPDs. Might take a few seconds...")
    # fetch first 5 EPDs. The API client provides a
    # transparent iterator which would load more pages
    # as needed, but we only need first 5 objects here
    epd_iterator = response.iterator()
    for epd in [next(epd_iterator) for _ in range(5)]:
        # print nicely formatted result
        print("< Found EPD:")
        id_field = f"{'id             '}: {epd.id}"
        name_field = f"{'mix name       '}: {epd.product_name}"
        description_field = f"{'description    '}: {epd.product_description}"
        link = f"{'See at EC3     '}: {EC3_BASE_URL}{epd.id}"

        print("\n".join([id_field, name_field, description_field, link]))
        print("\n")

    print("Done.")


# module entry point when ran as script
if __name__ == '__main__':
    run_openepd_script()

If everything is correct, you should get a list of few EPDs printed out in a terminal. You can navigate to the EC3 to review documents in more details.

$ python openepd_script.py

> Connecting to openEPD API...
> Searching for ReadyMixes with 
> compressive strength greater than 30 MPa at 28th day...
< Total EPDs found: 23204
> Fetching first 5 EPDs. Might take a few seconds...
< Found EPD:
id             : ec3qcxra
mix name       : 5045SAE
description    : 5000 3/4 45% slag a/e
See at EC3     : https://buildingtransparency.org/epds/ec3qcxra


< Found EPD:
id             : ec3cp7pp
mix name       : 503440SAE
description    : 5000 3/4 40% slag a/e
See at EC3     : https://buildingtransparency.org/epds/ec3cp7pp


< Found EPD:
id             : ec38gt91
mix name       : 453440SAE
description    : 4500 3/4 40% slag a/e
See at EC3     : https://buildingtransparency.org/epds/ec38gt91


< Found EPD:
id             : ec3am03k
mix name       : 453440SAE
description    : 4500 3/4 40% slag a/e
See at EC3     : https://buildingtransparency.org/epds/ec3am03k


< Found EPD:
id             : ec30jwgc
mix name       : 503440SAE
description    : 5000 3/4 40% slag a/e
See at EC3     : https://buildingtransparency.org/epds/ec30jwgc


Done.

Further Exploration

If you would like to simply explore the API, you can use the interactive REST API explorer. It uses the same API key obtained in this guide.