Product API

Summary

Published product information is available via an API.

The API schema and documentation is available as a Swagger template here.
And a Postman demo environment is available here.

The documentation above includes example queries that can be executed against a real environment with a predefined setup.
So you don't even have to follow the steps below if you just quickly want to play around with the API...

Below is a schematic representation of the components in the API, and how to use the links to navigate between them:

The green circles represent resources, which can contain links to other resources.
When they are stacked, it means an array of such resources can be returned.

When the relationship arrow points to the top of a stack, or just to a single resource, it means that link will return a single resource.
When the relationship arrow points to the bottom of a stack, it means that the link will return an array of resources.

The main entrypoint is the search query (/products), which returns an array of Product resources.
Another useful entrypoint is the impact definitions query (/impactdefinitions), which returns all the impact definitions available to you.

Product

A product calculated by Company, containing Impacts and linked to Scenarios

Link RelDescription
selfSelf link
impactsLink to the definition of this impact

Company

The Company owning the Products

Links
Link RelDescription
selfSelf link
productsLink to list Products for this Company

Scenario

A usage or end-of-life Scenario linked to Products

Links
Link RelDescription
selfSelf link
impactsLink to list of Impacts for this Scenario
productsLink to list of Products connected to this Scenario

Impact

The calculated impact against a midpoint or endpoint.
The list of impacts returned depends on the 'LCA Standard' setting in your EcoChain account.

Links
Link RelDescription
selfSelf link
impactDefinitionLink to list of Impacts for this Product
scenariosLink to list of Scenarios connected to this Product
companyLink to the Company owning this Product
Link RelDescription
productLink to Product to which these Impacts belong
scenarioLink to Scenario to which these Impacts belong

Impact Definition

Impacts are given as id-value pairs in the API.
In the table below you'll find their english names, units and to which LCA Standard and presentation they belong to.

The impact definitions here are also available through the impactdefinitions endpoint, but in the API you'll only see impact definitions corresponding to the LCA standard configured for your EcoChain account.

LCA Standard

Presentation

Name

Unit

BETA! ReCiPe

BETA Full

ReCiPe Midpoint (H) Marine eutrophication

kg N eq

BETA! ReCiPe

BETA Full

ReCiPe Midpoint (H) Fossil depletion

kg oil eq

BETA! ReCiPe

BETA Full

Environmental Price 2017 (low PM10)

Euro

BETA! ReCiPe

BETA Full

ReCiPe Midpoint (H) Freshwater ecotoxicity

kg 1,4-DB eq

BETA! ReCiPe

BETA Full

ReCiPe Midpoint (H) Particulate matter formation

kg PM10 eq

BETA! ReCiPe

BETA Full

ReCiPe Midpoint (H) Terrestrial acidification

kg SO<sub>2</sub> eq

BETA! ReCiPe

BETA Full

ReCiPe Midpoint (H) Terrestrial ecotoxicity

kg 1,4-DB eq

BETA! ReCiPe

BETA Full

ReCiPe Endpoint (H,A) Human Health

points

BETA! ReCiPe

BETA Full

ReCiPe Midpoint (H) Metal depletion

kg Fe eq

BETA! ReCiPe

BETA Full

ReCiPe (H,A) Single Score

points

BETA! ReCiPe

BETA Full

ReCiPe Midpoint (H) Climate change

kg CO<sub>2</sub> eq

BETA! ReCiPe

BETA Full

ReCiPe Midpoint (H) Freshwater eutrophication

kg P eq

BETA! ReCiPe

BETA Full

ReCiPe Midpoint (H) Ozone depletion

kg CFC-11 eq

BETA! ReCiPe

BETA Full

ReCiPe Midpoint (H) Water depletion

m3

BETA! ReCiPe

BETA Full

Costs

Euro

BETA! ReCiPe

BETA Full

ReCiPe Midpoint (H) Marine ecotoxicity

kg 1,4-DB eq

BETA! ReCiPe

BETA Full

ReCiPe Midpoint (H) Human toxicity

kg 1,4-DB eq

BETA! ReCiPe

BETA Full

ReCiPe Midpoint (H) Photochemical oxidant formation

kg NMVOC

BETA! ReCiPe

BETA Full

ReCiPe Midpoint (H) Ionising radiation

kg U235 eq

BETA! ReCiPe

BETA Full

ReCiPe Midpoint (H) Agricultural land occupation

m2a

BETA! ReCiPe

BETA Full

ReCiPe Endpoint (H,A) Resources

points

BETA! ReCiPe

BETA Full

ReCiPe Midpoint (H) Urban land occupation

m2a

BETA! ReCiPe

BETA Full

ReCiPe Midpoint (H) Natural land transformation

m2

BETA! ReCiPe

BETA Full

ReCiPe Endpoint (H,A) Ecosystems

points

BETA! ReCiPe

BETA Full

Environmental Price 2017

Euro

Dutch (MRPI, EN15804, ISO14040, ISO14044)

Full

Non-hazardous waste disposed

kg

Dutch (MRPI, EN15804, ISO14040, ISO14044)

Full

Eutrophication potential

kg PO<sub>4</sub> <sup>3−</sup>-eq

Dutch (MRPI, EN15804, ISO14040, ISO14044)

Full

Exported energy

MJ

Dutch (MRPI, EN15804, ISO14040, ISO14044)

Full

Hazardous waste disposed

kg

Dutch (MRPI, EN15804, ISO14040, ISO14044)

Full

Abiotic depletion potential for fossil resources

MJ

Dutch (MRPI, EN15804, ISO14040, ISO14044)

Full

Use of non-renewable secondary fuels

MJ

Dutch (MRPI, EN15804, ISO14040, ISO14044)

Full

Human toxicity potential

kg 1,4-DB-eq

Dutch (MRPI, EN15804, ISO14040, ISO14044)

Full

Use of renewable primary energy excluding renewable primary energy resources used as raw materials

MJ

Dutch (MRPI, EN15804, ISO14040, ISO14044)

Full

Use of renewable primary energy resources used as raw materials

MJ

Dutch (MRPI, EN15804, ISO14040, ISO14044)

Full

Use of non-renewable primary energy resources used as raw materials

MJ

Dutch (MRPI, EN15804, ISO14040, ISO14044)

Full

Acidification potential of land and water

kg SO<sub>2</sub>-eq

Dutch (MRPI, EN15804, ISO14040, ISO14044)

Full

Total use of renewable primary energy resources

MJ

Dutch (MRPI, EN15804, ISO14040, ISO14044)

Full

Use of net fresh water

m<sup>3</sup>

Dutch (MRPI, EN15804, ISO14040, ISO14044)

Full

Components for re-use

kg

Dutch (MRPI, EN15804, ISO14040, ISO14044)

Full

Materials for energy recovery

kg

Dutch (MRPI, EN15804, ISO14040, ISO14044)

Full

Formation potential of tropospheric ozone photochemical oxidants

kg ethene-eq

Dutch (MRPI, EN15804, ISO14040, ISO14044)

Full

Depletion potential of the stratospheric ozone layer

kg CFC-11-eq

Dutch (MRPI, EN15804, ISO14040, ISO14044)

Full

Freshwater aquatic ecotoxicity potential

kg 1,4-DB-eq

Dutch (MRPI, EN15804, ISO14040, ISO14044)

Full

Total use of non-renewable primary energy resources

MJ

Dutch (MRPI, EN15804, ISO14040, ISO14044)

Full

Use of non-renewable primary energy excluding non-renewable primary energy resources used as raw materials

MJ

Dutch (MRPI, EN15804, ISO14040, ISO14044)

Full

Costs

Euro

Dutch (MRPI, EN15804, ISO14040, ISO14044)

Full

Use of renewable secondary fuels

MJ

Dutch (MRPI, EN15804, ISO14040, ISO14044)

Full

Materials for recycling

kg

Dutch (MRPI, EN15804, ISO14040, ISO14044)

Full

Terrestrial ecotoxicity potential

kg 1,4-DB-eq

Dutch (MRPI, EN15804, ISO14040, ISO14044)

Full

Radioactive waste disposed

kg

Dutch (MRPI, EN15804, ISO14040, ISO14044)

Full

Marine aquatic ecotoxicity potential

kg 1,4-DB-eq

Dutch (MRPI, EN15804, ISO14040, ISO14044)

Full

Global warming potential

kg CO<sub>2</sub>-eq

Dutch (MRPI, EN15804, ISO14040, ISO14044)

Full

Environmental Costs Indicator

Euro

Dutch (MRPI, EN15804, ISO14040, ISO14044)

Full

Abiotic depletion potential for non-fossil resources

kg Sb-eq

Dutch (MRPI, EN15804, ISO14040, ISO14044)

Full

Use of secondary material

kg

Dutch (MRPI, EN15804, ISO14040, ISO14044)

Shortened

Total use of renewable primary energy resources

MJ

Dutch (MRPI, EN15804, ISO14040, ISO14044)

Shortened

Use of net fresh water

m<sup>3</sup>

Dutch (MRPI, EN15804, ISO14040, ISO14044)

Shortened

Ecotoxicity (total)

kg 1,4-DB-eq

Dutch (MRPI, EN15804, ISO14040, ISO14044)

Shortened

Formation potential of tropospheric ozone photochemical oxidants

kg ethene-eq

Dutch (MRPI, EN15804, ISO14040, ISO14044)

Shortened

Depletion potential of the stratospheric ozone layer

kg CFC-11-eq

Dutch (MRPI, EN15804, ISO14040, ISO14044)

Shortened

Waste (total)

kg

Dutch (MRPI, EN15804, ISO14040, ISO14044)

Shortened

Total use of non-renewable primary energy resources

MJ

Dutch (MRPI, EN15804, ISO14040, ISO14044)

Shortened

Costs

Euro

Dutch (MRPI, EN15804, ISO14040, ISO14044)

Shortened

Abiotic resource depletion (total)

kg Sb eq

Dutch (MRPI, EN15804, ISO14040, ISO14044)

Shortened

Global warming potential

kg CO<sub>2</sub>-eq

Dutch (MRPI, EN15804, ISO14040, ISO14044)

Shortened

Environmental Costs Indicator

Euro

European (EN15804, ISO14040, ISO14044)

Full

Non-hazardous waste disposed

kg

European (EN15804, ISO14040, ISO14044)

Full

Eutrophication potential

kg PO<sub>4</sub> <sup>3−</sup>-eq

European (EN15804, ISO14040, ISO14044)

Full

Exported energy

MJ

European (EN15804, ISO14040, ISO14044)

Full

Hazardous waste disposed

kg

European (EN15804, ISO14040, ISO14044)

Full

Abiotic depletion potential for fossil resources

MJ

European (EN15804, ISO14040, ISO14044)

Full

Use of non-renewable secondary fuels

MJ

European (EN15804, ISO14040, ISO14044)

Full

Use of renewable primary energy excluding renewable primary energy resources used as raw materials

MJ

European (EN15804, ISO14040, ISO14044)

Full

Use of renewable primary energy resources used as raw materials

MJ

European (EN15804, ISO14040, ISO14044)

Full

Use of non-renewable primary energy resources used as raw materials

MJ

European (EN15804, ISO14040, ISO14044)

Full

Acidification potential of land and water

kg SO<sub>2</sub>-eq

European (EN15804, ISO14040, ISO14044)

Full

Total use of renewable primary energy resources

MJ

European (EN15804, ISO14040, ISO14044)

Full

Use of net fresh water

m<sup>3</sup>

European (EN15804, ISO14040, ISO14044)

Full

Components for re-use

kg

European (EN15804, ISO14040, ISO14044)

Full

Materials for energy recovery

kg

European (EN15804, ISO14040, ISO14044)

Full

Formation potential of tropospheric ozone photochemical oxidants

kg ethene-eq

European (EN15804, ISO14040, ISO14044)

Full

Depletion potential of the stratospheric ozone layer

kg CFC-11-eq

European (EN15804, ISO14040, ISO14044)

Full

Total use of non-renewable primary energy resources

MJ

European (EN15804, ISO14040, ISO14044)

Full

Use of non-renewable primary energy excluding non-renewable primary energy resources used as raw materials

MJ

European (EN15804, ISO14040, ISO14044)

Full

Costs

Euro

European (EN15804, ISO14040, ISO14044)

Full

Use of renewable secondary fuels

MJ

European (EN15804, ISO14040, ISO14044)

Full

Materials for recycling

kg

European (EN15804, ISO14040, ISO14044)

Full

Radioactive waste disposed

kg

European (EN15804, ISO14040, ISO14044)

Full

Global warming potential

kg CO<sub>2</sub>-eq

European (EN15804, ISO14040, ISO14044)

Full

Abiotic depletion potential for non-fossil resources

kg Sb-eq

European (EN15804, ISO14040, ISO14044)

Full

Use of secondary material

kg

European (EN15804, ISO14040, ISO14044)

Shortened

Total use of renewable primary energy resources

MJ

European (EN15804, ISO14040, ISO14044)

Shortened

Use of net fresh water

m<sup>3</sup>

European (EN15804, ISO14040, ISO14044)

Shortened

Formation potential of tropospheric ozone photochemical oxidants

kg ethene-eq

European (EN15804, ISO14040, ISO14044)

Shortened

Depletion potential of the stratospheric ozone layer

kg CFC-11-eq

European (EN15804, ISO14040, ISO14044)

Shortened

Waste (total)

kg

European (EN15804, ISO14040, ISO14044)

Shortened

Total use of non-renewable primary energy resources

MJ

European (EN15804, ISO14040, ISO14044)

Shortened

Costs

Euro

European (EN15804, ISO14040, ISO14044)

Shortened

Global warming potential

kg CO<sub>2</sub>-eq

SBK Bepalingsmethode

Full

Non-hazardous waste disposed

kg

SBK Bepalingsmethode

Full

Eutrophication potential

kg PO<sub>4</sub> <sup>3−</sup>-eq

SBK Bepalingsmethode

Full

Hazardous waste disposed

kg

SBK Bepalingsmethode

Full

Human toxicity potential

kg 1,4-DB-eq

SBK Bepalingsmethode

Full

Acidification potential of land and water

kg SO<sub>2</sub>-eq

SBK Bepalingsmethode

Full

Total use of renewable primary energy resources

MJ

SBK Bepalingsmethode

Full

Use of net fresh water

m<sup>3</sup>

SBK Bepalingsmethode

Full

Formation potential of tropospheric ozone photochemical oxidants

kg ethene-eq

SBK Bepalingsmethode

Full

Depletion potential of the stratospheric ozone layer

kg CFC-11-eq

SBK Bepalingsmethode

Full

Freshwater aquatic ecotoxicity potential

kg 1,4-DB-eq

SBK Bepalingsmethode

Full

Total use of non-renewable primary energy resources

MJ

SBK Bepalingsmethode

Full

Costs

Euro

SBK Bepalingsmethode

Full

Total energy

MJ

SBK Bepalingsmethode

Full

Terrestrial ecotoxicity potential

kg 1,4-DB-eq

SBK Bepalingsmethode

Full

Radioactive waste disposed

kg

SBK Bepalingsmethode

Full

Marine aquatic ecotoxicity potential

kg 1,4-DB-eq

SBK Bepalingsmethode

Full

Global warming potential

kg CO<sub>2</sub>-eq

SBK Bepalingsmethode

Full

Abiotic depletion potential for fossil resources

kg Sb-eq

SBK Bepalingsmethode

Full

Environmental Costs Indicator

Euro

SBK Bepalingsmethode

Full

Abiotic depletion potential for non-fossil resources

kg Sb-eq

SBK Bepalingsmethode

Shortened

Total use of renewable primary energy resources

MJ

SBK Bepalingsmethode

Shortened

Use of net fresh water

m<sup>3</sup>

SBK Bepalingsmethode

Shortened

Ecotoxicity (total)

kg 1,4-DB-eq

SBK Bepalingsmethode

Shortened

Formation potential of tropospheric ozone photochemical oxidants

kg ethene-eq

SBK Bepalingsmethode

Shortened

Depletion potential of the stratospheric ozone layer

kg CFC-11-eq

SBK Bepalingsmethode

Shortened

Waste (total)

kg

SBK Bepalingsmethode

Shortened

Total use of non-renewable primary energy resources

MJ

SBK Bepalingsmethode

Shortened

Costs

Euro

SBK Bepalingsmethode

Shortened

Abiotic resource depletion (total)

kg Sb eq

SBK Bepalingsmethode

Shortened

Global warming potential

kg CO<sub>2</sub>-eq

SBK Bepalingsmethode

Shortened

Environmental Costs Indicator

Euro

Getting access

To use this API with real data, you'll first need to create an API key and secret.

Under Settings, and Company Information, you'll find a section for Client API Keys.
Click on the Generate Key/Secret button to create a new keypair.

You'll see a new Public Key and Private Secret appear.
Copy the secret to a safe place.
It's important to understand that the secret is like a password, and should never be included in any sourcecode or shared with anyone!

The next time you view the page, you won't be able to see the secret.
You can however regenerate it if you lost it.

Click on the description, and start typing to enter a description for the keypair.

Usage

To use the API, you'll first need to exchange your Public Key and Private Secret for an access token.
This access token is valid for a short time. Each time it becomes invalid, you'll need to follow this authentication step to get a valid access token again.

Authentication

There are two ways to authenticate.
You could include your credentials in:

  • Request body, or
  • Basic Auth header

Request body

E.g. using curl:

curl -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=client_credentials&client_id=KEY_34F69848D30E3296FD346BE8F53DBE23F02C08FFBB15F3394294FA5D508A06BA&client_secret=secret_13808685c217427ebd8b54b5a9f84cc2a667bbc2" -v https://app.ecochain.com/api/v1/authenticate

Basic Auth

E.g. using curl:

curl -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=client_credentials" -u KEY_34F69848D30E3296FD346BE8F53DBE23F02C08FFBB15F3394294FA5D508A06BA:secret_13808685c217427ebd8b54b5a9f84cc2a667bbc2 -v  https://app.ecochain.com/api/v1/authenticate

Token Response

With both methods above, the access token will be returned as JSON:

{
    "access_token": "ZXlKMGVYQWlPaUpLVjFRaUxDSmhiR2NpT2lKSVV6STFOaUlzSW1wMGFTSTZJbVJoTkRSaU5EWTRMVGRsWTJFdE5EWmlaUzA0TVRjMkxURTBZV0k0TnpaalpqUXlOaUo5LmV5SnBjM01pT2lKbFkyOWphR0ZwYmk1amIyMGlMQ0pxZEdraU9pSmtZVFEwWWpRMk9DMDNaV05oTFRRMlltVXRPREUzTmkweE5HRmlPRGMyWTJZME1qWWlMQ0pwWVhRaU9qRTFNelUyTVRjeU5UUXNJbVY0Y0NJNk1UVXpOVFl5TURnMU5Dd2lkV2xrSWpvaVMwVlpYMEpFUWtRd1JqWTRNVFl5UkRReE5FTkZRMEUzT1RJd05UQXdNRUUxUVRrek1UWTRRMFpHT0RFeU9UUTJORFkzT0RsRU1rRkZORUZDUTBWRk56WTRRamNpTENKeWIyeGxjeUk2ZXlKVVdWQlBNeTVHYkc5M09rVjJaWEo1WW05a2VTSTZlMzBzSWxSWlVFOHpMa1pzYjNjNlFYVjBhR1Z1ZEdsallYUmxaRlZ6WlhJaU9udDlMQ0pGWTI5RGFHRnBiaTVRWVdOcllXZGxPbVp2YjNSd2NtbHVkQ0k2ZTMwc0lrVmpiME5vWVdsdUxsQmhZMnRoWjJVNlptOXZkSEJ5YVc1MFgzQmhhV1FpT250OWZTd2liR05oVTNSaGJtUmhjbVFpT2lJeVpqTmlZalF5TXkxbE9HTTBMV0kwWldNdFpEZzNZaTFtTnpkbE5UYzROV05oTlRraUxDSjJZV3hwWkVOdmJYQmhibWxsY3lJNld5SXlZV0ZtWVRObU1DMWtObU00TFRRM1lqSXRZVEF4WWkxa056VTFNV1F4Tm1JNE5HVWlMQ0k1TkdVek1EaGlOUzFsTmpkbUxUUXpZall0T0dKbE1DMWhZMlJrWldFMlpESmtPV1VpTENKaU5EUXlZbUptT0MweU1qRm1MVFEyTlRJdFlUSTJZUzFtTVdFeFpHVXdNRGN3TlRZaVhYMC5QSW9DX1ZjU2dmRl9KSTZBRDVEOHY2ZWNGaEJXcnI2eTZkbldMNXIwNlA4",
    "expires_in": 3600,
    "refresh_token": null,
    "token_type": "Bearer"
}

The access_token should then be included in every following request.

You'll notice the empty refresh_token here. That's only used when one of the client-ip specific authentication methods are used.
And that's mostly through internal links from the EcoChain platform.

Searching

We've created some Postman examples which should help you get started with using the API.

  1. First, install Postman,
  2. Then click here to open the example project with predefined queries to run them in Postman.

  3. Make sure you've got the 'production sandbox' environment selected in Postman

The examples in Postman are configured to use a specific example account in EcoChain.
Important: Execute one of the 'authenticate' queries before the others.

Have fun!