Using the Federal LCA Commons Public API

[dt-woods]

Background: The ElectricityLCI relies on the Federal LCA Commons' public API to get GreenDelta's unit groups and flow property data (typically provided in their databases as a radio button when creating a database from scratch, for example, the 'units and flow properties' option). To make the ElectricityLCI's baseline JSON-LD files complete, we opt to include them. Additionally, the EPA's pedrigree matrices for flow and process data quality are also taken from the Federal LCA Commons' USLCI repository. These data calls are handled in the olca_jsonld_writer.py module.

The Federal LCA Commons hosts a user guide for their API¹.

It doesn't look like JSON data can be exported directly over the internet for these assets; therefore, we will implement the request for a JSON-LD preparation token, then download the ZIP file over the internet.

The Python dependencies needed for this include:

import io
import json
from zipfile import ZipFile

import requests
import olca_schema as o

First, let's define the URL for JSON-LD preparation:

url = "https://www.lcacommons.gov/lca-collaboration/ws/public/download/json"

The flow properties and unit groups are available in the Elementary Flow List repository².

To get a token for downloading the flow property and unit groups, we add to the base URL the group name (Federal_LCA_Commons), the repository name (elementary_flow_list), and query the flow property path, as follows:

# Token for JSON-LD with flow properties and unit groups
token_url = url + "/prepare/Federal_LCA_Commons/elementary_flow_list?path=FLOW_PROPERTY"

The token is a string of letters and number provided by the Federal LCA Commons' API service. To get a token, we send a GET request.

token = requests.get(token_url).content.decode()

With the token, we can now get the JSON-LD ZIP file from the server using the original URL.

# Retrieve the JSON-LD content from the server
r = requests.get(f"{url}/{token}")

We have options on how to handle the content returned: (1) save it to ZIP file locally, or (2) read the ZIP content and extract the data we want. In ElectricityLCI, we choose the latter.

# Initialize empty lists for storing all the unit groups and flow properties
u_list = []
p_list = []

# Read the ZIP file for unit groups and flow properties (each in a separate JSON)
with ZipFile(io.BytesIO(r.content)) as z:
    for name in z.namelist():
        if name.startswith("unit") and name.endswith("json"):
            # Read the JSON data as a dictionary and create an olca-schema object
            u_dict = json.loads(z.read(name))
            u_obj = o.UnitGroup.from_dict(u_dict)
            u_list.append(u_obj)
        elif name.startswith("flow_") and name.endswith("json"):
            p_dict = json.loads(z.read(name))
            p_obj = o.FlowProperty.from_dict(p_dict)
            p_list.append(p_obj)

This should give you lists of unit group and flow property olca-schema objects. You can then use the olca_schema.zipio class to write these objects to a different JSON-LD file.

To get the data quality indicator matrices, we redefine the token URL.

# Token for JSON-LD with data quality indicators
token_url = url + "/prepare/Federal_LCA_Commons/Fed_Commons_core_database?path=DQ_SYSTEM"

We then repeat the process above to get the token for the JSON-LD data from the server.

token = requests.get(token_url).content.decode()

Again, we use the token to access the JSON-LD ZIP file from the server.

# Retrieve the JSON-LD content from the server
r = requests.get(f"{url}/{token}")

In this case, we are only getting three files:

1. The process pedigree matrix (DQ_SYSTEM)
2. The flow pedigree matrix (DQ_SYSTEM)
3. The source of these matrices (SOURCE)

d_list = []
s_list = []
if r.ok:
    with ZipFile(io.BytesIO(r.content)) as z:
        for name in z.namelist():
            if name.startswith("dq_systems") and name.endswith("json"):
                d_dict = json.loads(z.read(name))
                d_obj = o.DQSystem.from_dict(d_dict)
                d_list.append(d_obj)
            elif name.startswith("sources") and name.endswith("json"):
                s_dict = json.loads(z.read(name))
                s_obj = o.Source.from_dict(s_dict)
                s_list.append(s_obj)

This should give you lists of DQ systems (there are two) and a list that includes the source for them.

Footnotes

1. https://www.lcacommons.gov/lca-commons-api-guide ↩

2. https://www.lcacommons.gov/lca-collaboration/Federal_LCA_Commons/elementary_flow_list/datasets ↩