Core concepts

This guide will help you set up your initial access to the ecoinvent API.

Versions & System Models

ecoinvent operates on a versioned database system. Each API request that retrieves or processes data must reference a specific version and system model of the underlying environmental database.

• Versions: Represent different releases of the environmental database (e.g., "3.9", "3.8")

• System Models: Represent different modeling approaches within each version (e.g., "cutoff", "consequential")

All data retrieval endpoints (/datasets and /indicators) require specifying which version and system model to use. If not explicitly provided, the API defaults to the latest available version and cutoff system model. The /versions endpoint allows you to discover all available combinations.

Dataset Identification (IDs)

ecoinvent uses several types of identifiers to reference datasets and methods:

• Dataset ID: A unique identifier (ID) that is automatically generated by the API, it does not change between versions.*

• Spold ID: The API also supports lookup by UUIDs used in the ecoinvent SPOLD2 file format, these UUIDs can be for activities, geographies and products.

*it might happen that a dataset will be merged, deleted, or manipulated which requires an ID change

LCIA methods & indicators

The ecoinvent database offers various indicators to assess environmental impact. Each indicator is part of a selected method and category. This means that the same indicator can have a different score, depending on the selected method & category. The /indicators endpoint allows you to discover all available combinations.

Example: GPW100 is part of the IPCC 2021 method, but multiple categories (climate change: fossil, climate change: total, etc.). In this case, requesting GWP100 in each category will have its own ID and be reported as a separate indicator.

User Identification

Using the ecoinvent API will require different kinds of user identifiers, each serving a specific purpose:

• Username: necessary to identify as a customer with an ecoinvent license. These credentials won't be needed in the API, but are important to access the API client on your account.

• API client: to use the ecoinvent API, you need the API client, which allows you to generate access tokens. You can find more information on the Authentication page.

• User-Id: Important to report for which user a dataset or indicator is retrieved. According to your license, you might have specific usage limitations. You can find more information on the User limits & reporting page.

API recommendation

For consistency across API usage, we recommend:

1. Use the search endpoints to find datasets and retrieve their computed IDs

2. Store these computed IDs for use with the datasetsendpoint in subsequent requests

3. Make sure to use the correct IDs in new versions of the database, in case datasets or indicators change

For more information about the ecoinvent database, visit our Knowledge Base