Table of Contents:
- Background
- Overview
- What's Available
- Getting Access
- Key Responsibility
- Rate Limits
- API Endpoints
- Example Requests
- Response Codes
- API Specification
- 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 the 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.
Overview
The Federal LCA Commons API provides REST access to publicly available life cycle assessment (LCA) data hosted on the National Agricultural Library (NAL) API gateway. It is intended primarily to assist users who want to search, retrieve, or download LCA datasets. Data retrieved via the API is managed through api.data.gov, which handles API key management and rate limiting.
For more background information on key concepts, data element descriptions, and the purpose of the LCA Commons API, see the LCA API Reference Guide Supplement.
What's Available
The API provides five authenticated endpoints covering the most common data access workflows:
- Searching datasets across repositories.
- Downloading individual datasets as JSON-LD.
- Preparing and downloading full repository files.
- Retrieving files attached to specific datasets.
Two of the five endpoints are two-step processes requiring a token from the first call to complete the second.
Getting Access
Anyone may access and use the API. However, a valid data.gov API key must be incorporated into each API request. Register to obtain your free API key.
Demo Key:
A demo key is available for initial testing and exploration. The demo key is rate limited and is not suitable for production use or automated workflows.
Use DEMO_KEY to test any example in this guide. Replace DEMO_KEY with your assigned API key before building applications or running automated scripts. Below is a general formatting example:
|
https://api.nal.usda.gov/FederalLCACommonsapi/search?query=concrete&api_key=DEMO_KEY |
|---|
Key Responsibility
It is the API key holder's responsibility to ensure their key is not made publicly available. Any API key discovered in a public location online will be deactivated to prevent misuse. Always use environment variables or configuration files to store keys outside of any source code.
Rate Limits
The API currently enforces a default limit of 1,000 requests per hour per API key, which is sufficient for most research and application use cases. Exceeding this limit will temporarily block the key for one hour. If you need a higher rate limit, please contact the FLCAC team via the Contact Us form.
The rate limits for the DEMO_KEY are:
- Hourly Limit: 30 requests per IP address per hour
- Daily Limit: 50 requests per IP address per day
Rate Limit Error Response:
If your API key exceeds the rate limits, you will receive a response with an HTTP status code of 429 (Too Many Requests).
More detailed information on rate limits may be found at the api.data.gov developer manual.
API Endpoints
All Five endpoints use the HTTP GET method and are accessible via the base URL:
| Method | Endpoint | Purpose | Notes |
|---|---|---|---|
| GET | /ws/public/search | Search datasets across all repositories | Single Call |
| GET | /ws/public/browse/{group}/{repo}/{type}/{refId} | Download a single dataset as JSON-LD | Single Call |
| GET | /ws/public/download/json/prepare/{group}/{repo} | Prepare full repository download. Returns a token | Step 1 of 2 |
| GET | /ws/public/download/json/{token} | Download the prepared zip file using the token | Step 2 of 2 |
| GET | /ws/public/repository/file/{group}/{repo}/{type}/{refId}/{path} | Download a specific file attached to a dataset | Two Steps |
| ⚠ Two-step workflows: Endpoints 3, 4, and 5 involve multi-step calls. Endpoints 3 and 4 must be used together. Endpoint 3 returns a token, and endpoint 4 uses that token to download the file. Endpoint 5 requires retrieving the dataset record first (step 1) to obtain the file path, then downloading the file using that path (step 2). |
|---|
For the complete endpoint reference, including history, repository, and all parameters, request and response schemas, and advanced endpoints, see the Federal LCA Commons API Specification.
Example Requests
All examples below use DEMO_KEY. Replace with your assigned API key for production use. Examples are show in both cURL and Python.
|
⚠ Note for Python: Make sure you have the following at the beginning of the script: import requests API_KEY = "DEMO_KEY" BASE_URL = "https://api.nal.usda.gov/FederalLCACommonsapi/" |
|---|
1. Search Datasets
Search for datasets across all public repositories using a keyword query.
cURL:
curl -X GET "https://api.nal.usda.gov/FederalLCACommonsapi/search/?query=concrete&api_key=DEMO_KEY"
Python:
import requests
API_KEY = "DEMO_KEY"
BASE_URL = "https://api.nal.usda.gov/FederalLCACommonsapi/"
response = requests.get(f"{BASE_URL}/search", params={
"query": "concrete",
"api_key": API_KEY
})
print(response.json())
Key parameters that can be included:
- query - keyword to search across dataset names and metadata.
- group - filter results to a specific group (e.g. US_Environmental_Protection_Agency)
- type - filter by model type (e.g. PROCESS, FLOW)
- page/ pageSize - paginate result (default pageSize is 10)
2. Download an Individual Dataset
Retrieve a single dataset as JSON-LD by providing the group, repository, model type, and dataset UUID.
cURL:
Python:
response = requests.get(
f"{BASE_URL}/browse/National_Renewable_Energy_Laboratory"
"/USLCI_Database_Public/PROCESS"
"/935ae747-5a9c-3718-b6a4-df622378456a",
params={"api_key": API_KEY}
)
print(response.json())
Key parameters that can be included:
- group - the group that owns the repository
- repo - the repository name
- type - the model type (e.g. PROCESS, FLOW, SOURCE)
- refId - the UUID of the specific dataset
3 & 4. Prepare and download a full repository (two-steps)
To download an entire repository as a JSON-LD zip file, you must first request a download token (Step 1), then use that token to download the file (Step 2).
Step 1: Prepare the download (returns a token):
cURL:
Python:
response = requests.get(
f"{BASE_URL}/download/json/prepare"
"/National_Renewable_Energy_Laboratory"
"/USLCI_Database_Public",
params={"api_key": API_KEY}
)
token = response.json().get("token")
print("Token:", token)
Step 2: Download using the token:
cURL:
curl -X GET "https://api.nal.usda.gov/FederalLCACommonsapi/download/json/{token}?api_key=DEMO_KEY"
--output repository_download.zip
Python:
response = requests.get(
f"{BASE_URL}/download/json/repository"
"/National_Renewable_Energy_Laboratory"
f"/USLCI_Database_Public/{token}",
params={"api_key": API_KEY}
)
with open("repository_download.zip", "wb") as f:
f.write(response.content)
5. Download a dataset Attachment (two-steps):
Retrieve a file attached to a specific dataset. First list the available files, then download the one you need.
Step 1: List files attached to a dataset
cURL:
Python:
response = requests.get(
f"{BASE_URL}/browse/National_Renewable_Energy_Laboratory"
"/USLCI_Database_Public/SOURCE"
"/b85b5e5f-5a30-4242-9c8e-886864eee9a0",
params={"api_key": API_KEY}
)
print(response.json())
Step 2: Download the specific file:
cURL:
--output formic_acid_diagram.jpg
Python:
response = requests.get(
f"{BASE_URL}/repository/file/National_Renewable_Energy_Laboratory"
"/USLCI_Database_Public/SOURCE/b85b5e5f-5a30-4242-9c8e-886864eee9a0"
"/formic%20acid%20diagram.jpg",
params={"api_key": API_KEY}
)
with open("formic_acid_diagram.jpg", "wb") as f:
f.write(response.content)
Response Codes
Every API request will return an HTTP status code indicating success or failure.
| Status Code | Meaning |
|---|---|
| 200 OK | Request was successful. Data is returned in the response body. |
| 400 Bad Request | The request was invalid, likely due to a missing or incorrect parameter. |
| 403 Forbidden | The API key is missing, invalid, or does not have permission to access the resource. |
| 404 Not Found | The request resource (dataset, repository, or token) could not be found. |
| 406 Not Acceptable | The repository schema version is not supported. |
| 500 Internal Server Error | An error occurred on the server. Try again or contact the FLCAC team if it persists. |
When an error occurs, always check the status code first before retrying. For instance, a 403 typically means a missing or incorrect API key. A 404 means the group, repository, or dataset identifier in the URL does not exist or is misspelled.
API Specification
The LCA Commons API specification provides a complete technical reference for all available endpoints, including full parameter definitions, request and response schemas, and supported data types. It is intended for users who need detailed technical information beyond what is covered in this guide.
The specification is available to users in the following formats:
- HTML - This is a static HTML version available for reference.
- Swagger UI - An interactive version which allows users to explore endpoints and test calls directly in their browser.
- JSON - The HTML page also includes a link to download the specification in JSON format.
The HTML and Swagger UI formats are based on the Swagger 2.0 specification. The JSON version available for download from the HTML page reflects OpenAPI 3.0.0, which is part of the OpenAPI initiative.
Getting Help
If you encounter issues or have questions while using the API:
- Refer to this guide or the Federal LCA Commons API Specification.
- Browse the FLCAC Documentation Site for data structure guidance, glossary, and FAQs.
- Check for any known issues or announcements.
- Submit questions or report issues via the Contact Us form.