ICAO Carbon Emission Calculator (ICEC) API: Release Candidate 3

International Civil Aviation Organization

Prepared by: ICAO e-Business Team

01/Oct/2018

Carbon Calculator API Documentation RC 3 Revision History Date Version Initial 01/Oct/2018 RC 3 Initial 24/Oct/2017 RC 2 Initial 15/Aug/2017 RC 1 Beta 20/Apr/2017 BETA

Table of Contents

ICAO CARBON EMISSION CALCULATOR (ICEC) API ...... 3 Introduction ...... 3 Request an Access ...... 3 Authentication and Security ...... 3

METHODS - DESCRIPTION ...... 4 Authentication tokens ...... 4 Authentication token expiration ...... 4 Requests the output of Carbon Emissions ...... 4 • Arguments ...... 5 • Itineraries entity ...... 5 • Request Code ...... 5 • Response Code ...... 5 Requests the output of Carbon Emissions – UN Methodology ...... 6 • Arguments ...... 6 • Itineraries entity ...... 6 • Request Code ...... 7 • Response Code ...... 8 List of city code and name ...... 9

Carbon Calculator API Documentation RC 3 ICAO CARBON EMISSION CALCULATOR (ICEC) API

Introduction

This document is meant to be a part of the general Carbon Calculator methodology developed for estimating the amount of carbon emissions (CO2) generated by a passenger in a flight, for use in carbon offsetting programmes.

The ICAO Carbon Emission Calculator (ICEC) API provides the ability for third-party software already developed or being developed by other International Organization to fully integrate with the ICAO Carbon Emission Calculator.

The API will allow the ICAO mobile applications (Carbon Emission Calculator) to connect to a centralized database.

Request an Access

To be able to use the ICAO Carbon Emission Calculator (ICEC) API, you need to request an access by sending your request to [email protected]. Please clearly specify the subject of the request, e.g. ICAO Carbon Emission Calculator (ICEC) API. ICAO’s Office of the Environment (ENV) will then issue the following details allowing you to start using the API:

• URL of the API => https://applications.icao.int/ICECAPI/ • Username, Password => username and password allowing you to request a token • Documentation of the API

Authentication and Security

The API handles an authentication system provided by JSON Web Tokens (JWT) protocol. When an application requires access to the Carbon Emission Calculator API, credentials will be issued to the user. The e-Business Team will be in charge to handle access to clients.

Carbon Calculator API Documentation RC 2 Page 3 of 9 METHODS - DESCRIPTION

Authentication tokens

To make a web API call, you must supply an authentication token on the call. The token acts like an electronic key that lets you access the API.

Verbs Path Description

/auth/token Request access token

An authentication token request contains three basic elements:

Component Specifies End Point /auth/token Content type application/json Grant type password Credentials Username, password

Authentication token expiration

Access tokens issued by the Authorization Server expire one hour after they are issued. When an access token expires, then the application should generate another JWT, sign it, and request another access token.

Requests the output of Carbon Emissions

Request the Carbon Emissions resources must contain the authentication token in the header To do this, specify an HTTP header in the following format:

Component Specifies Authorization Bearer

Allow the third-party software to connect with ICAO Carbon Emission Calculator application.

Verbs Path Description

/api/carbonemission Perform Carbon Emission Calculate

Carbon Calculator API Documentation RC 3 • Arguments

DATA TYPE PARAMETER NAME DESCRIPTION FIELD REQUIREMENT String Indicator (M)etric or (S)tandard Required Array Itineraries An array containing flight itinerary entity (defined below) Required

• Itineraries entity

DATA TYPE PARAMETER NAME DESCRIPTION FIELD REQUIREMENT String Departure The airport of departure 3 letter IATA CODE Required String Arrival The airport of arrival 3 letter IATA CODE Required String Indicator (M)Metric or (S)Standard Required String TravelClass Class of travel: Required

Economic classes: Y,S,B,H,K,L,M,N,Q,T,V,X Premium classes: F,A,P,R,C,J,D,I,Z,W,E

• Request Code

{ Indicator: "M", Itineraries: [ { Departure: "CDG", Arrival: "JFK", TravelClass: "G" } ] }

• Response Code

Code DESCRIPTION 200 Return a delimited string containing the ICAO data for each leg of the input flight itinerary, in the following format:

/ / /

Example : Y/4340.0/56047.6/274.5,Y/11000.0/102932.3/1259.6,Y/11000.0/102932.3/1259.6,Y/4340.0/56047.6/274. 5

404 Not found

Carbon Calculator API Documentation RC 3 Requests the output of Carbon Emissions – UN Methodology

Verbs Path Description

/api/un/carbonemission Perform Carbon Emission Calculate using UN methodology

• Arguments

DATA TYPE PARAMETER NAME DESCRIPTION FIELD REQUIREMENT String Indicator (M)etric or (S)tandard Required Array Itineraries An array containing flight Required itinerary entity (defined below) Integer Year Year of data (YYYY) Required

• Itineraries entity

Economic classes: Y,S,B,H,K,L,M,N,Q,T,V,X Premium classes: F,A,P,R,C,J,D,I,Z,W,E

Integer Year Year of data (YYYY) Required

Carbon Calculator API Documentation RC 3 • Request Code JSON format of UN API request. The parameters should be included in the request body.

{ Itineraries: [ { Departure: "FAO", Arrival: "JFK", TravelClass: "E"} ], Year: 2015, Indicator: "M" }

{ Itineraries: [ { Departure: "YUL", Arrival: "JFK", TravelClass: "E" }, { Departure: "JFK", Arrival: "MIA", TravelClass: "E" } ], Year: 2015, Indicator: "M" }

{ Itineraries: [ { Departure: "CDG", Arrival: "JFK", TravelClass: "E" } ], Year: 2015, Indicator: "M" }

Carbon Calculator API Documentation RC 3 • Response Code JSON format of UN API response.

Code DESCRIPTION 200 Return a JSON containing the ICAO data for each leg of the input flight itinerary, in the following format: Example 1: [ { "route": "FAO-JFK", "class": "E", "cO2RemainingAfterOtherOffsetting": 437.01628712945296, "tripDistance": 8768, "additionalCO2UncertaintyLowKg": -78.407995690412633, "additionalCO2UncertaintyHighKg": 432.53846264509104, "cO2OffsetFromOtherSoucesKg": 60.965529546264975, "messages": "Average value computed due to a missing connecting airport between: FAO and JFK. There are 32 possible connecting airports for this route.", "indicator": "M" } ] Example 2: [ { "route": "YUL-JFK", "class": "E", "cO2RemainingAfterOtherOffsetting": 119.8, "tripDistance": 536, "additionalCO2UncertaintyLowKg": 0, "additionalCO2UncertaintyHighKg": 0, "cO2OffsetFromOtherSoucesKg": 0, "messages": "", "indicator": "M" }, { "route": "JFK-MIA", "class": "E", "cO2RemainingAfterOtherOffsetting": 155.7, "tripDistance": 1756, "additionalCO2UncertaintyLowKg": 0, "additionalCO2UncertaintyHighKg": 0, "cO2OffsetFromOtherSoucesKg": 0, "messages": "", "indicator": "M" }, { "route": "YUL-JFK JFK-MIA", "class": "E", "cO2RemainingAfterOtherOffsetting": 275.5,

Carbon Calculator API Documentation RC 3 "tripDistance": 2292, "additionalCO2UncertaintyLowKg": 0, "additionalCO2UncertaintyHighKg": 0, "cO2OffsetFromOtherSoucesKg": 0, "messages": "", "indicator": "M" } ] Example 3: [ { "route": "CDG-JFK", "class": "F", "cO2RemainingAfterOtherOffsetting": 653.3, "tripDistance": 5829, "additionalCO2UncertaintyLowKg": 0, "additionalCO2UncertaintyHighKg": 0, "cO2OffsetFromOtherSoucesKg": 0, "messages": "", "indicator": "M" } ] 404 Not found

List of city code and name

The list of city codes and names can be integrated to the client side by using the database_sample.accdb (CityCodeMap table).

By having this list, it is possible to create an airport code search and provide it as a parameter to the UN methodology API endpoint.

Carbon Calculator API Documentation RC 3