API

This page will go through the steps to connect with the Ecochain API

Product API

Created by 
Last updated Sep 17, 2018
 

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

LINKS

Link Rel
Description
self Self link
impacts Link to the definition of this impact

Company

The Company owning the Products

LINKS

Link Rel
Description
self Self link
products Link to list Products for this Company

Scenario

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

LINKS

Link Rel
Description
self Self link
impacts Link to list of Impacts for this Scenario
products Link 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 Rel
Description
self Self link
impactDefinition Link to list of Impacts for this Product
scenarios Link to list of Scenarios connected to this Product
company Link to the Company owning this Product

LIST RESULT LINKS

Link Rel
Description
product Link to Product to which these Impacts belong
scenario Link 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!

 

3rd party applications and SSO

 
Created by 
Last updated Sep 19, 2018
 
 

With the API, it's possible to interact with Ecochain data as a 3rd party application.

When the link to the application is built into the Ecochain platform, it's even possible have SSO capabilities for users.

 

 

At the time of writing, our API is not fully SSO compliant, but we solve it with a custom flow, where the user first logs into the Ecochain platform, and then opens the 3rd party application with an app specific link.

3rd party application developers would then not expose any login capability of their own, but expect the access and refresh tokens to be passed to them in the form of a GET request.

The following 'launch' parameters will be sent with the GET request when opening the 3rd party application:

  • access_token
  • expires_in
  • refresh_token
  • token_type

It's then the responsibility of the 3rd party applicaiton to extract the value of the 'access_token' parameter and in all following requests to the API, pass it in as a Bearer token.

Let's say that you have developed an app to display footprint data for any products.
Your company is called Acme, and you'd like for Ecochain customers to use your app for displaying their products.

Windmill Company is an Ecochain customer, and they would log into Ecochain to eventually use your app for displaying their products.

Here's how the components work together across the different environments

 

 

  1. User is logged into Ecochain and clicks the 3rd party app launch button
    Frontend logic will open a new browser tab and send a GET request to our internal web controller
  2. Our web controller will authenticate the user against the API server and receive an access token
  3. Our web controller will send a GET request with launch parameters to the launch URL of your app
    E.g. 

    curl -X GET ‘https://acme.com/launch?access_token=ABCDEF&expires_in=3600&refresh_token=GHIJKL&token_type=Bearer
  4. Your controller will extract the 4 parameters, and use the access token to make requests to the Ecochain API

    E.g. First get the current user

    curl -H "Authorization: Bearer ABCDEF" https://app.ecochain.com/api/v1/users/me

    then get the current company

    curl -H "Authorization: Bearer ABCDEF" https://app.ecochain.com/api/v1/companies/me

    then get all products for the company

    curl -H "Authorization: Bearer ABCDEF" https://app.ecochain.com/api/v1/companies/{companyId}/products
  5. Your controller will render the page with contents fetched from the API

As you can see, we've made SSO really simple for 3rd party application developers.
All you need to do is expose an endpoint that can receive GET requests with the 4 launch parameters and render the user interface.