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>