An official website of the United States government.

Official websites use .gov
A .gov website belongs to an official government organization in the United States.

Secure .gov websites use HTTPS
A lock ( ) or https:// means you've safely connected to the .gov website. Share sensitive information only on official, secure websites.

Life Cycle Assessment Commons

LCA Commons API Guide

Table of Contents:

  1. Background
  2. Purpose
  3. Key Concepts
  4. API Endpoints Overview
  5. API Endpoints List
  6. How to Use the API
  7. Example Requests
  8. Handling Responses
  9. Getting Help

 

Background

The Federal LCA Commons is a collaborative platform for Life Cycle Assessment (LCA) data management and sharing. LCA is a methodology used to assess environmental impacts associated with all stages of a product's life, from raw material extraction through materials processing, manufacture, distribution, use, repair and maintenance, and disposal or recycling.

The LCA Collaboration Server is a core component of the LCA Commons ecosystem, designed to facilitate the storage, management, and sharing of LCA data among researchers, practitioners, and decision-makers in various fields related to environmental assessment and sustainable development.

 

Purpose

The LCA Commons API provides public access to life cycle data for research and analysis in various fields including agriculture, energy, transportation, construction, defense, and environmental. This guide is designed to help users—whether new to the API, developers, or researchers—retrieve datasets, access group and repository information, and utilize LCA Commons' resources through easy-to-use API calls. It provides clear instructions on how to interact with the public API, allowing seamless integration of LCA data into applications and research tools. By following this guide, users will understand how to access various types of public data without needing authentication, enabling them to gather information for use in their projects, research, or analyses.

 

Key Concepts 

The LCA Commons API allows for the retrieval of publicly available life cycle data, metadata about groups, and repositories. Understanding these core concepts will help you effectively use the API.

Public API:

A set of methods that allow unrestricted access to public datasets and metadata. Unlike private APIs, public APIs don't require authentication, making them easier to access by any user without the need for a login.

Dataset:

A dataset in the context of LCA refers to a structured collection of data that quantifies various environmental aspects, such as carbon emissions, resource usage, and waste generation, for a specific product, process, or system. Datasets often represent inputs and outputs across the life cycle of a product, allowing researchers and practitioners to assess its environmental impact.

Repository:

Repositories in the LCA Commons API are digital locations where datasets are stored. A repository can hold multiple datasets and often includes metadata, such as when the datasets were created, the group that owns them, and the purpose of the data. Repositories are used to organize datasets by theme or project, such as "Energy Use Data" or "Agricultural Emissions."

Group:

A group in LCA Commons refers to a collection of repositories and datasets that are associated with a specific team, project, or organization. Public groups contain datasets that are available for anyone to access, allowing for broader data sharing and collaboration.

GET Method:

The HTTP GET method is used to request and retrieve data from the server. In the context of the public API, GET requests are used to access datasets, repository information, and group details without modifying any data.

Metadata:

Metadata refers to "data about data." In this API, metadata includes information like dataset names, descriptions, creation dates, and ownership details. It helps users understand the context and scope of the dataset without needing to download or access the entire dataset.

JSON (JavaScript Object Notation):

A lightweight data format used for storing and transporting structured data. JSON is easy to read and write for both humans and machines, and it is the standard format used in the LCA Commons API for data exchange.

JSON-LD (JSON for Linked Data):

JSON-LD is an extension of the JSON format, designed specifically for representing linked data. It allows datasets to be structured in a way that links related data points across the web, making the data more compatible and accessible for analysis. For the LCA Commons, JSON-LD is used to provide more meaningful and relevant representations of environmental data, which can be leveraged for better data integration and more complex queries.

For example, when users prepare to download repositories in JSON-LD format, they are getting data structured to enable comprehensive, linked insights that can be used in complex life cycle assessments or aggregated with other datasets.

The API also uses version-controlled schemas to ensure consistency and compatibility when retrieving data in JSON-LD format. The current openLCA schema version (v2.0), https://greendelta.github.io/olca-schema/intro.html, defines the structure of Life Cycle Assessment data provided by the LCA Commons. 

Data Element Descriptions:

The API allows access to several types of LCA data, including:

  • ModelType: Represents the classification of data such as ACTOR, CATEGORY, FLOW, and PROCESS.
  • FlowType: Describes the nature of data flows to include ELEMENTARY_FLOW and PRODUCT_FLOW.
  • ProcessType: Provides information about the type of processes, such as UNIT_PROCESS and LCI_RESULT. These elements help users structure queries and better understand the LCA datasets available in the Commons. 

 

API Endpoints Overview

The API provides access to publicly available data via a series of well-structured endpoints. This section explains how to interact with the API, what HTTP methods are supported, and how users can utilize the available parameters to retrieve specific data.

 

HTTP Method: GET

The LCA Commons Public API follows REST principles and uses the GET method. The GET method is part of the HTTP protocol and is used to retrieve data from a server without making any changes to the resources on the server. In the context of the LCA Commons, the GET method allows users to request datasets, group information, and repository metadata.

  • GET requests are read-only, meaning they will not modify any data on the server.
  • GET requests are consistent, meaning multiple identical requests will return the same result.

 

Endpoint URL Structure

Each API endpoint is accessed via a unique URL. The general format for the API endpoints is:

https: //lcacommons.gov/lca-collaboration/ws/public/{resource}/{id}

 

  • Base URL: This is the common base URL for all public API endpoints (https: //lcacommons.gov/lca-collaboration/ws/public/).
  • Resource: Represents the type of data you want to access, such as data, groups, or repository.
  • ID: The unique identifier for the specific dataset, group, or repository you want to retrieve. Some endpoints allow searching without an ID, while others require it.

 

Parameters

Some endpoints allow users to pass parameters in the request to filter or customize the data returned. Parameters can be passed either as part of the URL (path parameters) or as query parameters (appended to the URL with a ?).

Path Parameters:

Path parameters are part of the URL structure and are used to specify the resource or entity you are trying to access.

Example of a path parameter in a dataset request:

https: //lcacommons.gov/lca-collaboration/ws/public/data/{dataset}

 

In the above example, {dataset} is the unique identifier for the dataset you wish to retrieve. The actual request would replace {dataset} with a valid identifier, such as sample_dataset.

Query Parameters:

Query parameters are optional filters or variables you can append to the URL to modify the results returned by the API. They are appended to the URL after a ? symbol.

Example of a query parameter in a search request:

https: //lcacommons.gov/lca-collaboration/ws/public/search?query=environment

In the example, the query parameter is used to search for datasets related to "environment."

 

API Endpoints List

 

HTTP METHOD ENDPOINT DESCRIPTION PARAMETER
GET /ws/public/browse/{group}/{repo}/{type}/{refId} Download a dataset from the specified repository. group, repo, type, refId, commitId
GET /ws/public/groups List accessible groups for the client. page, pageSize, filter, onlyIfCanWrite
GET /ws/public/repository List public repositories including basic settings. None
GET ws/public/repository/{group}/{repo} Get settings of a public repository. group, repo
GET /ws/public/search Search for datasets across the collaboration server. query, group, repositoryId, type, categoryPaths, flowType, processType, modellingApproach, validFromYear, validUntilYear, location, contact, page, pageSize, filter
GET /ws/public/download/json/prepare/{group}/{repo} Prepare a repository for download as a JSON-LD zip-archive. group, repo, commitId, path
GET /ws/public/download/json/{token} Download a prepared JSON-LD zip-archive. token
GET /ws/public/repository/avatar/{group}/{repo} Get the avatar for a public repository. group, repo
GET /ws/public/repository/file/{group}/{repo}/{type}/{refId}/{path} Get a specific file from a repository's dataset. group, repo, type, refId, commitId, path
GET /ws/public/search/flowLinks/{flowRefId} Search for datasets that consume, emit, or produce a specific flow. flowRefId, commitId, direction, repositoryId, page, pageSize, filter

 

How to Use the API

The API provides several ways to access datasets and metadata. While cURL is a popular tool for sending API requests, you can also use programming languages such as Python, R, and JavaScript with their corresponding libraries, as well as API software like Postman for a more user-friendly interface.

Guide to Making a Request:

  1. Select the Endpoint: 
    • Identify the correct API endpoint for the data you need.
      • Datasets, repository information, or group data
  2. Construct the Request: 
  3. Pagination and Filtering:
    • The API supports pagination and filtering to help users handle large datasets more efficiently. 
      • Pagination: Use the page and pageSize parameters to control the number of results returned and navigate between pages of results.
      • Filtering: Use query parameters like filter or query to narrow down your results based on specific terms or categories. For a quick example of how this works, review the Example Requests section of this document.
  4. Send the Request:
    • cURL: Allows you to send requests directly from the terminal.
    • Python: Use libraries like requests to send HTTP requests.
    • R: Use httr or curl packages for API requests.
    • JavaScript: Use fetch or axios to make API calls from the browser or Node.js.
    • API Software: A graphical API client, like Postman, allows users to automate, build, test, and send requests without coding.
  5. Handle the Response: 
    • The API returns responses in JSON format. 
    • You can parse this data and integrate it into your application or workflow.

 

Example Requests

1. Get a List of Public Groups

  • To retrieve a list of public groups, you can make a request to the /ws/public/groups endpoint.
curl -X GET "https: //lcacommons.gov/lca-collaboration/ws/public/groups?page=1&pageSize=10"
  • Parameters:
    • page: The page number of results to return.
    • pageSize: The number of results per page.

 

2. Search for Datasets by Query

  • You can search for datasets across the collaboration server by providing a search query, such as "energy," using the /ws/public/search endpoint.
curl -X GET "https: //lcacommons.gov/lca-collaboration/ws/public/search?query=energy&page=1&pageSize=5"
  • Parameters:
    • query: The search term to look for datasets related to energy.
    • page: The page number of results.
    • pageSize: The number of results to return.

 

3. Download a Prepared JSON-LD Archive

  • To download a dataset as a JSON-LD zip-archive, you can first prepare the repository by requesting a download token from the /ws/public/download/json/prepare/{group}/{repo} endpoint, and then use the token to download the file.

    • Step 1: Prepare the download

      curl -X GET "https: //lcacommons.gov/lca-collaboration/ws/public/download/json/prepare/PublicGroup/SampleRepo"

    • Step 2: Use the token from the first response to download the archive

      curl -X GET "https: //lcacommons.gov/lca-collaboration/ws/public/download/json/abcdef123456"
  • Parameters:
    • Token: The download token provided in the first request.

 

4. Retrieve Metadata of a Public Repository

  • To get settings and metadata about a public repository, use the /ws/public/repository/{group}/{repo} endpoint.
curl -X GET "https: //lcacommons.gov/lca-collaboration/ws/public/repository/PublicGroup/SampleRepo"
  • Parameters:
    • group: The name of the group that owns the repository.
    • repo: The repository's unique identifier.

 

5. Get a Specific File from a Repository

  • To retrieve a specific file from a repository's dataset, use the /ws/public/repository/file/{group}/{repo}/{type}/{refId}/{path} endpoint.
curl -X GET "https: //lcacommons.gov/lca-collaboration/ws/public/repository/file/PublicGroup/SampleRepo/DATA/12345/file.txt"
  • Parameters:
    • group: The group name.
    • repo: The repository name.
    • type: The type of file (e.g., DATA).
    • refId: The reference ID of the dataset.
    • path: The file path within the repository.

 

Handling Responses

When interacting with the LCA Commons API, each request will result in an HTTP response. The response includes both the data (if the request was successful) and an HTTP status code, which indicates the result of the request. Understanding these response codes is important for interpreting the success or failure of your API calls and for troubleshooting any issues that arise.

The LCA Commons API will provide appropriate response codes for both successful and failed requests. Here’s how to interpret the most common HTTP status codes returned by the public API:

  • 200 OK: The request was successful, and the data is returned.
  • 400 Bad Request: The request was invalid, likely due to incorrect parameters.
  • 404 Not Found: The requested resource (such as a dataset or repository) could not be found.
  • 500 Internal Server Error: An error occurred on the server, and the request couldn’t be processed.

 

When an API request fails, it’s important to handle errors to avoid crashes or unexpected behavior. It's a good practice to always check the response code to determine the outcome of the request.

 

Getting Help

If you encounter issues or have questions while using the API:

  1. Refer to this documentation first.
  2. Check for any known issues or announcements.
  3. Send a message via the "Contact Us" form.

 

Questions about this documentation please contact:

Arnetta Knight, Product Manager

Email: arnetta.knight@usda.gov

 

 

Top of Page