Skip to main content

Flight Duration API

 

Overview

Flight duration Service provides a simple API that allows users to determine the average flight duration in minutes. This average time is based on historical flight data collected by the SITA Flight Information system over the past number of years.

This API answers the below questions”

What was the total time of the flight?

See our 'Try it Now'  page for more details.

 

Flight Duration API

 

1 Revision History

Date Version Description

2 February 2021

1.0

Initial version

12 October 2021

1.1

Split by airline, min, max and percentile breakdown options added

26 October 2022

1.2

Reformatting documentation and general tidy up

08 August 2023

1.2

Added rate limit and OAuth

2 Registration and API Sign Up

SITA Flight Duration API is a REST based service which provides information about flight durations around the world.

To access the APIs you will need 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 Authentication

To access the APIs an OAuth access token must be supplied. To obtain an OAuth token a request must be sent to the https://sitaopen.api.aero/duration/oauth/token endpoint using the OAuth2 Client Credential flow, using your API key as the client_id, and your consumer secret as the client_secret.

Once an access token has been obtained, it can be placed in the Authorization HTTP header as a bearer token, for example:

Authorization: Bearer eyJ92dNw9dka...

2.2 Security

  • All incoming requests will be REST over HTTPS.

  • Users are authenticated using their API key.

  • Certain response payload elements will be filtered based on permissions associated with their token.

2.3 Flight Duration API Structure

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

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.

2.4 Rate Limiting

All incoming requests are subject to a rate limiting restriction. The following headers are included in HTTP responses:

Header Description

X-RateLimit-Limit

The total number of requests allowed in the current time window

X-RateLimit-Remaining

The number of requests left for the current time window

X-RateLimit-Policy

The policy describing how many request per time window are allowed

X-RateLimit-Reset

The number of seconds remaining in the current time window. Header not displayed after rate limit has been exceeded

retry-after

The epoch timestamp at which the current rate limit window resets. Header only displayed after rate limit has been exceeded

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
Table 1. /{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'

Authorization

Authorization header that contains the access token.

Curl request
$ curl 'https://sitaopen-qa.api.aero/duration/v2/JFK/MIA' -i -X GET \
    -H 'Authorization: Bearer eyJkb2N1bWVudGF0aW9uIiwidG9rZW4ifQ...' \
    -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

destinationAirport

String

Destination Airport

originAirport

String

Origin Airport

stats[]

Object

Duration stats (average, min, max, percentile breakdown)

stats[].airline

String

Airline

stats[].average

String

Average duration

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

Path parameters
Table 1. /{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

Query 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'

Authorization

Authorization header that contains the access token.

Curl request
$ curl 'https://sitaopen-qa.api.aero/duration/v2/JFK/MIA?showMinMax=true&showPercentiles=true' -i -X GET \
    -H 'Authorization: Bearer eyJkb2N1bWVudGF0aW9uIiwidG9rZW4ifQ...' \
    -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,
      "5" : 174,
      "25" : 185,
      "50" : 190,
      "75" : 192,
      "95" : 203,
      "99" : 204
    }
  } ]
}
Response fields
Path Type Description

destinationAirport

String

Destination Airport

originAirport

String

Origin Airport

stats[]

Object

Duration stats (average, min, max, percentile breakdown)

stats[].airline

String

Airline

stats[].average

String

Average duration

stats[].max

String

Max duration

stats[].min

String

Min duration

stats[].percentiles.1

String

1st percentile

stats[].percentiles.25

String

25th percentile

stats[].percentiles.5

String

5th percentile

stats[].percentiles.50

String

50th percentile

stats[].percentiles.75

String

75th percentile

stats[].percentiles.95

String

95th percentile

stats[].percentiles.99

String

99th percentile

stats[].percentiles[]

Object

Duration percentiles breakdown

3.1.3 GET Duration stats by Airports and split by Airline

Path parameters
Table 1. /{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

Query 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'

Authorization

Authorization header that contains the access token.

Curl request
$ curl 'https://sitaopen-qa.api.aero/duration/v2/JFK/MIA?split=airline' -i -X GET \
    -H 'Authorization: Bearer eyJkb2N1bWVudGF0aW9uIiwidG9rZW4ifQ...' \
    -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

destinationAirport

String

Destination Airport

originAirport

String

Origin Airport

stats[]

Object

Duration stats (average, min, max, percentile breakdown)

stats[].airline

String

Airline

stats[].average

String

Average duration

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

Path parameters
Table 1. /{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

Query 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'

Authorization

Authorization header that contains the access token.

Curl request
$ curl 'https://sitaopen-qa.api.aero/duration/v2/JFK/MIA?split=airline&showMinMax=true' -i -X GET \
    -H 'Authorization: Bearer eyJkb2N1bWVudGF0aW9uIiwidG9rZW4ifQ...' \
    -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

destinationAirport

String

Destination Airport

originAirport

String

Origin Airport

stats[]

Object

Duration stats (average, min, max, percentile breakdown)

stats[].airline

String

Airline

stats[].average

String

Average duration

stats[].max

String

Max duration

stats[].min

String

Min duration

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

Path parameters
Table 1. /{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

Query 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'

Authorization

Authorization header that contains the access token.

Curl request
$ curl 'https://sitaopen-qa.api.aero/duration/v2/JFK/MIA?split=airline&showMinMax=true&showPercentiles=true' -i -X GET \
    -H 'Authorization: Bearer eyJkb2N1bWVudGF0aW9uIiwidG9rZW4ifQ...' \
    -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,
      "5" : 174,
      "25" : 185,
      "50" : 190,
      "75" : 192,
      "95" : 203,
      "99" : 204
    }
  }, {
    "airline" : "DL",
    "average" : 189,
    "min" : 174,
    "max" : 204,
    "percentiles" : {
      "1" : 177,
      "5" : 177,
      "25" : 181,
      "50" : 189,
      "75" : 198,
      "95" : 200,
      "99" : 200
    }
  } ]
}
Response fields
Path Type Description

destinationAirport

String

Destination Airport

originAirport

String

Origin Airport

stats[]

Object

Duration stats (average, min, max, percentile breakdown)

stats[].airline

String

Airline

stats[].average

String

Average duration

stats[].max

String

Max duration

stats[].min

String

Min duration

stats[].percentiles.1

String

1st percentile

stats[].percentiles.25

String

25th percentile

stats[].percentiles.5

String

5th percentile

stats[].percentiles.50

String

50th percentile

stats[].percentiles.75

String

75th percentile

stats[].percentiles.95

String

95th percentile

stats[].percentiles.99

String

99th percentile

stats[].percentiles[]

Object

Duration percentiles breakdown

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

Path parameters
Table 1. /{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

Query 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'

Authorization

Authorization header that contains the access token.

Curl request
$ curl 'https://sitaopen-qa.api.aero/duration/v2/JFK/MIA/AA?showMinMax=true&showPercentiles=true' -i -X GET \
    -H 'Authorization: Bearer eyJkb2N1bWVudGF0aW9uIiwidG9rZW4ifQ...' \
    -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,
      "5" : 174,
      "25" : 185,
      "50" : 190,
      "75" : 192,
      "95" : 203,
      "99" : 204
    }
  } ]
}
Response fields
Path Type Description

destinationAirport

String

Destination Airport

originAirport

String

Origin Airport

stats[]

Object

Duration stats (average, min, max, percentile breakdown)

stats[].airline

String

Airline

stats[].average

String

Average duration

stats[].max

String

Max duration

stats[].min

String

Min duration

stats[].percentiles.1

String

1st percentile

stats[].percentiles.25

String

25th percentile

stats[].percentiles.5

String

5th percentile

stats[].percentiles.50

String

50th percentile

stats[].percentiles.75

String

75th percentile

stats[].percentiles.95

String

95th percentile

stats[].percentiles.99

String

99th percentile

stats[].percentiles[]

Object

Duration percentiles breakdown

4 Error Response

Response fields

Path Type Description

errors

Object

Object that holds the error information

errors.error[]

Array

Array of errors

errors.error[].code

Number

Duration API Internal Error Code

errors.error[].description

String

Error Description

errors.error[].invalidParam

String

Indicates the invalid query parameter

Curl request

$ curl 'https://sitaopen-qa.api.aero/duration/v2/AMS/INVALID_AIRPORT_CODE' -i -X GET \
    -H 'Authorization: Bearer eyJkb2N1bWVudGF0aW9uIiwidG9rZW4ifQ...' \
    -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

 

Contact Us

For subscription and sales queries, please contact:

Product Inquiries

Contact Us

 

For Flight Duration API related queries, please contact:

Technical Support Team

Contact Us

contact-icon

Do you have a question? We are here, ready to help

Get in touch

About us

We are the world's leading specialist in air transport communications and IT solutions. 

 

bottom navigation SITA logo