Flight Duration API

SITA Advanced Data Services
dots.support@sita.aero

version 1.1.0-SNAPSHOT

Table of Contents

1 Revision History
2 Registration and API Sign Up
3 SITA Flight Duration API
- 3.1 Resources
4 Error Response
5 Appendix A - Definitions, Acronyms and Abbreviations
6 Appendix B - SITA Flight Duration API Use Cases

1 Revision History

Date	Version	Description	Author
`2 February 2021`	`1.0`	`Initial version`	`R Bacchetti`
`12 October 2021`	`1.1`	`Split by airline, min, max and percentile breakdown options added`	`D McGowan`
`26 October 2022`	`1.2`	`Reformatting documentation and general tidy up`	`L Kenny`

2 Registration and API Sign Up

To access the APIs you will need a registration key, also known as an API key. These can be obtained by creating an account on https://www.developer.aero/ and registering your interest for access to the API.

2.1 API Key Usage

The API key will be passed in an HTTP header as follows:

Name of header: x-apiKey
Value of header: The API key as generated for the application.

2.2 Security

All incoming requests will be REST over HTTPS.
Users are authenticated using their API key.

2.3 Flight Duration API Structure

The scheme, domain and high level path parameters portion of the URL is:

https://host:port/duration/{version}

Where duration is the functional domain. The current version is v2.

Function	Method	Description
`/{originAirport}/{destinationAirport}`	`GET`	`Returns the average flight duration between two airports in minutes.`
`/{originAirport}/{destinationAirport}/{airlineCode}`	`GET`	`Returns the average flight duration between two airports operated by airline in minutes.`

3 SITA Flight Duration API

Flight Duration API provides duration statistics for flights between two airports based on data collected from the SITA Flight Information system.

The metrics available include average duration, min duration, max duration, and percentile breakdown. Each of these can be displayed as an aggregate figure (e.g. average duration for all airlines) or split out per airline.

3.1 Resources

This section describes Flight Duration API with regards to:

Detailed API structure
Example requests and responses
JSON schema for request (where appropriate) and responses
Error response codes and formats

3.1.1 GET Duration stats by Airports for all Airlines

Path parameters

/{version}/{originAirport}/{destinationAirport}
Parameter	Description
`version`	The version of this API.
`originAirport`	3-character IATA or 4-character ICAO origin airport code
`destinationAirport`	3-character IATA or 4-character ICAO destination airport code

Request headers

Name	Description
`Content-Type`	Content type of this request. Required value is 'application/json'
`X-apiKey`	Authorization header that contains the API key

Curl request

$ curl 'https://sitaopen-qa.api.aero/duration/v2/JFK/MIA' -i -X GET \
    -H 'X-apiKey: FAKE KEY' \
    -H 'Content-Type: application/json'

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 132

{
  "originAirport" : "JFK",
  "destinationAirport" : "MIA",
  "stats" : [ {
    "airline" : "*",
    "average" : 189
  } ]
}

Response fields

Path	Type	Description
`stats[].average`	`String`	Average duration
`stats[]`	`Object`	Duration stats (average, min, max, percentile breakdown)
`originAirport`	`String`	Origin Airport
`stats[].airline`	`String`	Airline
`destinationAirport`	`String`	Destination Airport

3.1.2 GET Duration stats by Airports with Min, Max and Percentiles

Path parameters

/{version}/{originAirport}/{destinationAirport}
Parameter	Description
`version`	The version of this API.
`originAirport`	3-character IATA or 4-character ICAO origin airport code
`destinationAirport`	3-character IATA or 4-character ICAO destination airport code

Request parameters

Parameter	Description
`showMinMax`	Boolean value - Use this to have the min and max durations in the response
`showPercentiles`	Boolean value - Use this to have the duration percentiles returned

Request headers

Name	Description
`Content-Type`	Content type of this request. Required value is 'application/json'
`X-apiKey`	Authorization header that contains the API key

Curl request

$ curl 'https://sitaopen-qa.api.aero/duration/v2/JFK/MIA?showMinMax=true&showPercentiles=true' -i -X GET \
    -H 'X-apiKey: FAKE KEY' \
    -H 'Content-Type: application/json'

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 330

{
  "originAirport" : "JFK",
  "destinationAirport" : "MIA",
  "stats" : [ {
    "airline" : null,
    "average" : 189,
    "min" : 174,
    "max" : 204,
    "percentiles" : {
      "1" : 174,
      "99" : 204,
      "5" : 174,
      "75" : 192,
      "50" : 190,
      "25" : 185,
      "95" : 203
    }
  } ]
}

Response fields

Path	Type	Description
`stats[].percentiles.50`	`String`	50th percentile
`stats[].percentiles.95`	`String`	95th percentile
`destinationAirport`	`String`	Destination Airport
`stats[].airline`	`String`	Airline
`stats[].min`	`String`	Min duration
`stats[].percentiles[]`	`Object`	Duration percentiles breakdown
`stats[].percentiles.5`	`String`	5th percentile
`stats[].percentiles.25`	`String`	25th percentile
`stats[].percentiles.75`	`String`	75th percentile
`originAirport`	`String`	Origin Airport
`stats[]`	`Object`	Duration stats (average, min, max, percentile breakdown)
`stats[].average`	`String`	Average duration
`stats[].max`	`String`	Max duration
`stats[].percentiles.1`	`String`	1st percentile
`stats[].percentiles.99`	`String`	99th percentile

3.1.3 GET Duration stats by Airports and split by Airline

Path parameters

/{version}/{originAirport}/{destinationAirport}
Parameter	Description
`version`	The version of this API.
`originAirport`	3-character IATA or 4-character ICAO origin airport code
`destinationAirport`	3-character IATA or 4-character ICAO destination airport code

Request parameters

Parameter	Description
`split`	Used to specify how the duration stats should be split. Currently only 'airline' is supported

Request headers

Name	Description
`Content-Type`	Content type of this request. Required value is 'application/json'
`X-apiKey`	Authorization header that contains the API key

Curl request

$ curl 'https://sitaopen-qa.api.aero/duration/v2/JFK/MIA?split=airline' -i -X GET \
    -H 'X-apiKey: FAKE KEY' \
    -H 'Content-Type: application/json'

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 185

{
  "originAirport" : "JFK",
  "destinationAirport" : "MIA",
  "stats" : [ {
    "airline" : "AA",
    "average" : 189
  }, {
    "airline" : "DL",
    "average" : 189
  } ]
}

Response fields

Path	Type	Description
`stats[].average`	`String`	Average duration
`stats[]`	`Object`	Duration stats (average, min, max, percentile breakdown)
`originAirport`	`String`	Origin Airport
`stats[].airline`	`String`	Airline
`destinationAirport`	`String`	Destination Airport

3.1.4 GET Duration stats by Airports and split by Airline and show Min, Max

Path parameters

/{version}/{originAirport}/{destinationAirport}
Parameter	Description
`version`	The version of this API.
`originAirport`	3-character IATA or 4-character ICAO origin airport code
`destinationAirport`	3-character IATA or 4-character ICAO destination airport code

Request parameters

Parameter	Description
`split`	Used to specify how the duration stats should be split. Currently only 'airline' is supported
`showMinMax`	Boolean value - Use this to have the min and max durations in the response

Request headers

Name	Description
`Content-Type`	Content type of this request. Required value is 'application/json'
`X-apiKey`	Authorization header that contains the API key

Curl request

$ curl 'https://sitaopen-qa.api.aero/duration/v2/JFK/MIA?split=airline&showMinMax=true' -i -X GET \
    -H 'X-apiKey: FAKE KEY' \
    -H 'Content-Type: application/json'

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 257

{
  "originAirport" : "JFK",
  "destinationAirport" : "MIA",
  "stats" : [ {
    "airline" : "AA",
    "average" : 189,
    "min" : 174,
    "max" : 204
  }, {
    "airline" : "DL",
    "average" : 189,
    "min" : 174,
    "max" : 204
  } ]
}

Response fields

Path	Type	Description
`originAirport`	`String`	Origin Airport
`stats[].airline`	`String`	Airline
`stats[].min`	`String`	Min duration
`destinationAirport`	`String`	Destination Airport
`stats[]`	`Object`	Duration stats (average, min, max, percentile breakdown)
`stats[].average`	`String`	Average duration
`stats[].max`	`String`	Max duration

3.1.5 GET Duration stats by Airports and split by Airline and show Min, Max and Percentiles

Path parameters

/{version}/{originAirport}/{destinationAirport}
Parameter	Description
`version`	The version of this API.
`originAirport`	3-character IATA or 4-character ICAO origin airport code
`destinationAirport`	3-character IATA or 4-character ICAO destination airport code

Request parameters

Parameter	Description
`split`	Used to specify how the duration stats should be split. Currently only 'airline' is supported
`showMinMax`	Boolean value - Use this to have the min and max durations in the response
`showPercentiles`	Boolean value - Use this to have the duration percentiles returned

Request headers

Name	Description
`Content-Type`	Content type of this request. Required value is 'application/json'
`X-apiKey`	Authorization header that contains the API key

Curl request

$ curl 'https://sitaopen-qa.api.aero/duration/v2/JFK/MIA?split=airline&showMinMax=true&showPercentiles=true' -i -X GET \
    -H 'X-apiKey: FAKE KEY' \
    -H 'Content-Type: application/json'

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 579

{
  "originAirport" : "JFK",
  "destinationAirport" : "MIA",
  "stats" : [ {
    "airline" : "AA",
    "average" : 189,
    "min" : 174,
    "max" : 204,
    "percentiles" : {
      "1" : 174,
      "99" : 204,
      "5" : 174,
      "75" : 192,
      "50" : 190,
      "25" : 185,
      "95" : 203
    }
  }, {
    "airline" : "DL",
    "average" : 189,
    "min" : 174,
    "max" : 204,
    "percentiles" : {
      "1" : 177,
      "99" : 200,
      "5" : 177,
      "75" : 198,
      "50" : 189,
      "25" : 181,
      "95" : 200
    }
  } ]
}

Response fields

Path	Type	Description
`stats[].percentiles.50`	`String`	50th percentile
`stats[].percentiles.95`	`String`	95th percentile
`destinationAirport`	`String`	Destination Airport
`stats[].airline`	`String`	Airline
`stats[].min`	`String`	Min duration
`stats[].percentiles[]`	`Object`	Duration percentiles breakdown
`stats[].percentiles.5`	`String`	5th percentile
`stats[].percentiles.25`	`String`	25th percentile
`stats[].percentiles.75`	`String`	75th percentile
`originAirport`	`String`	Origin Airport
`stats[]`	`Object`	Duration stats (average, min, max, percentile breakdown)
`stats[].average`	`String`	Average duration
`stats[].max`	`String`	Max duration
`stats[].percentiles.1`	`String`	1st percentile
`stats[].percentiles.99`	`String`	99th percentile

3.1.6 GET Duration stats by Airports for a specific Airline and show Min, Max and Percentiles

Path parameters

/{version}/{originAirport}/{destinationAirport}/{airlineCode}
Parameter	Description
`version`	The version of this API.
`originAirport`	3-character IATA or 4-character ICAO origin airport code
`destinationAirport`	3-character IATA or 4-character ICAO destination airport code
`airlineCode`	2-character IATA or 3-character ICAO airline code

Request parameters

Parameter	Description
`showMinMax`	Boolean value - Use this to have the min and max durations in the response
`showPercentiles`	Boolean value - Use this to have the duration percentiles returned

Request headers

Name	Description
`Content-Type`	Content type of this request. Required value is 'application/json'
`X-apiKey`	Authorization header that contains the API key

Curl request

$ curl 'https://sitaopen-qa.api.aero/duration/v2/JFK/MIA/AA?showMinMax=true&showPercentiles=true' -i -X GET \
    -H 'X-apiKey: FAKE KEY' \
    -H 'Content-Type: application/json'

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 330

{
  "originAirport" : "JFK",
  "destinationAirport" : "MIA",
  "stats" : [ {
    "airline" : "AA",
    "average" : 189,
    "min" : 174,
    "max" : 204,
    "percentiles" : {
      "1" : 174,
      "99" : 204,
      "5" : 174,
      "75" : 192,
      "50" : 190,
      "25" : 185,
      "95" : 203
    }
  } ]
}

Response fields

Path	Type	Description
`stats[].percentiles.50`	`String`	50th percentile
`stats[].percentiles.95`	`String`	95th percentile
`destinationAirport`	`String`	Destination Airport
`stats[].airline`	`String`	Airline
`stats[].min`	`String`	Min duration
`stats[].percentiles[]`	`Object`	Duration percentiles breakdown
`stats[].percentiles.5`	`String`	5th percentile
`stats[].percentiles.25`	`String`	25th percentile
`stats[].percentiles.75`	`String`	75th percentile
`originAirport`	`String`	Origin Airport
`stats[]`	`Object`	Duration stats (average, min, max, percentile breakdown)
`stats[].average`	`String`	Average duration
`stats[].max`	`String`	Max duration
`stats[].percentiles.1`	`String`	1st percentile
`stats[].percentiles.99`	`String`	99th percentile

4 Error Response

Response fields

Path	Type	Description
`errors.error[].invalidParam`	`String`	Indicates the invalid query parameter
`errors.error[].description`	`String`	Error Description
`errors`	`Object`	Object that holds the error information
`errors.error[].code`	`Number`	Duration API Internal Error Code
`errors.error[]`	`Array`	Array of errors

Curl request

$ curl 'https://sitaopen-qa.api.aero/duration/v1/AMS/INVALID_AIRPORT_CODE' -i -X GET \
    -H 'X-apiKey: FAKE_API_KEY' \
    -H 'Content-Type: application/json'

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 164

{
  "errors" : {
    "error" : [ {
      "description" : "Airport not found",
      "code" : 2020,
      "invalidParam" : "destinationAirport"
    } ]
  }
}

5 Appendix A - Definitions, Acronyms and Abbreviations

Term	Definition

6 Appendix B - SITA Flight Duration API Use Cases

Scenario:	As an API user I want to make a request to the Duration API to return flight duration statistics between 2 specified airports
Request:	GET /duration/v2/LHR/DXB
Response:	Returns flight duration statistics between LHR and DXB

Scenario:	As an API user I want to make a request to the Duration API to return flight duration statistics between 2 specified airports with a given airline
Request:	GET /duration/v2/LHR/DXB/AA
Response:	Returns flight duration statistics between LHR and DXB for the airline AA

Scenario:	As an API user I want to make a request to the Duration API to return the average flight duration time between 2 airports in minutes
Request:	GET /duration/v1/LHR/DXB
Response:	Returns average flight duration times between LHR and DUB in minutes

Scenario:	As an API user I want to make a request to the Duration API to return the average flight duration time between 2 airports in minutes for a specific airline
Request:	GET /duration/v1/LHR/DXB/AA
Response:	Returns average flight duration times between LHR and DUB in minutes for the airline AA

Last updated 2022-10-28 12:55:05 +0100

Flight Duration API

About us

Contact