Skip to main content

Quick start

Getting started with the flight emissions API is quick and easy. Here are the steps needed.

Acquire API credentials​

If you don't yet have API credentials, you can contact us to get started.

Authenticate to the API​

Our API uses OAuth 2.0 tokens to authorize API calls. Access token can be acquired from the token endpoint using basic auth (combine client id and client secret with : and base64 encode it):

POST https://api.oncarbon.app/oauth2/token?grant_type=client_credentials
Authorization: Basic <base64(client_id:client_secret)>
Content-Type: application/x-www-form-urlencoded

The returned access token is valid for 12 hours.

Fetch emissions for flight itineraries​

Form a JSON payload of flight itineraries for which to get emissions for. For example to get emissions for a single itinerary from Helsinki to London and back:

POST https://api.oncarbon.app/v1/flights/flight-itineraries/emissions
Authorization: Bearer <access_token>

with payload:

{
  "itineraries": [
    {
      "slices": [
        {
          "sliceId": "there",
          "segments": [
            {
              "aircraftCode": "321",
              "operatingAirlineCode": "AY",
              "departureAirportCode": "HEL",
              "arrivalAirportCode": "LHR",
              "departureTime": "2022-06-04T14:05:00+03",
              "flightNumber": "1335"
            }
          ]
        },
        {
          "sliceId": "back",
          "segments": [
            {
              "aircraftCode": "321",
              "operatingAirlineCode": "AY",
              "departureAirportCode": "LHR",
              "arrivalAirportCode": "HEL",
              "departureTime": "2022-06-10T16:10:00+01",
              "flightNumber": "1336"
            }
          ]
        }
      ]
    }
  ]
}

which will give us the following response:

{
  "itineraries": [
    {
      "type": "itinerary-emissions",
      "oncarbonId": "MzIxLkhFTC5MSFIuQVkuMTMzNS4yMDIyLTA2LTA0VDE0OjA1OjAwKzAzfjMyMS5MSFIuSEVMLkFZLjEzMzYuMjAyMi0wNi0xMFQxNjoxMDowMCswMQ~Zx1gqA7-tz860Q3a2i776I89wKo",
      "emissions": {
        "co2ePerSeat": 674
      },
      "slices": [
        {
          "sliceId": "there",
          "emissions": {
            "co2ePerSeat": 336
          },
          "segments": [
            {
              "emissions": {
                "co2ePerSeat": 336
              }
            }
          ]
        },
        {
          "sliceId": "back",
          "emissions": {
            "co2ePerSeat": 338
          },
          "segments": [
            {
              "emissions": {
                "co2ePerSeat": 338
              }
            }
          ]
        }
      ]
    }
  ]
}

Present the emissions on a web page​

With the Oncarbon UI components the itinerary's emissions can be visualized. First, import the library:

<script
  type="module"
  src="https://cdn.jsdelivr.net/npm/@oncarbon/ui-components/dist/oncarbon/oncarbon.esm.js"
></script>
<script
  nomodule
  src="https://cdn.jsdelivr.net/npm/@oncarbon/ui-components/dist/oncarbon/oncarbon.js"
></script>

Then, we can display the itinerary details in a popover that is opened with a button click:

<onc-flight-itinerary-info
  itinerary-oncarbon-id="MzIxLkhFTC5MSFIuQVkuMTMzNS4yMDIyLTA2LTA0VDE0OjA1OjAwKzAzfjMyMS5MSFIuSEVMLkFZLjEzMzYuMjAyMi0wNi0xMFQxNjoxMDowMCswMQ~Zx1gqA7-tz860Q3a2i776I89wKo"
>
  <button>Open the popover</button>
</onc-flight-itinerary-info>

Offset the emissions​

Offsetting emissions is done in two steps. First you calculate how much it costs to offset the emissions of an itinerary and then you buy the compensation credits.

To get the price to offset the emissions of the above mentioned itinerary you send the following request:

POST https://api.oncarbon.app/v1/compensation/price
Authorization: Bearer <access_token>

with payload:

{
  "oncarbonId": "MzIxLkhFTC5MSFIuQVkuMTMzNS4yMDIyLTA2LTA0VDE0OjA1OjAwKzAzfjMyMS5MSFIuSEVMLkFZLjEzMzYuMjAyMi0wNi0xMFQxNjoxMDowMCswMQ~Zx1gqA7-tz860Q3a2i776I89wKo",
  "currency": "USD"
}

gives the following response, where the price is in eurocents and in USD cents:

{
  "emissionsCo2ePerSeat": 674,
  "amountInEurCents": 3370,
  "conversion": {
    "amount": 2934,
    "currency": "USD"
  }
}

After that you can buy carbon credits in euros for the entire itinerary or part of it with the following request:

POST https://api.oncarbon.app/v1/compensation/transaction
Authorization: Bearer <access_token>

with payload:

{
  "amountInEurCents": 3000,
  "referenceId": "My reference for this transaction",
  "oncarbonId": "MzIxLkhFTC5MSFIuQVkuMTMzNS4yMDIyLTA2LTA0VDE0OjA1OjAwKzAzfjMyMS5MSFIuSEVMLkFZLjEzMzYuMjAyMi0wNi0xMFQxNjoxMDowMCswMQ~Zx1gqA7-tz860Q3a2i776I89wKo"
}

returns the id for the created transaction:

{
  "id": "1dd8132d-ed65-4960-ba88-e68a8b946058"
}