Loading

Basic Concepts

There are several concepts you should familiarise yourself with before delving into the API. They are listed below.

Authentication

We have implemented the OAuth 2.0 spec for authenticating against the API. This is the #1 thing that developers new to the CAPA API struggle with, so it is strongly recommended that you fully read the section on authentication.

Terminologies

A Profile within CAPA refers to a company, organisation, country or other entity. If you're looking for information relating to a specific company, you'll likely want to find their profile details. See the page on Profiles for more information.

There's some slight differences in the API when it comes to what certain data types are called to vs what they are called on the CAPA website frontend. This is due to marketing reasons. To clarify:

  • Reports on the CAPA website are referred to as articles within the API.
  • Research Publications on the CAPA website are referred to as reports within the API.

Request/Response Formats

All responses (with the exception of OAuth token responses) are returned as a JSON object containing one or more keys:

KeyDescription
dataIf data is returned from the request, it will be contained within this key.
errorsIf the request has resulted in one or more errors, then the errors will be returned as an array of objects containing the closest HTTP status code that would match the error, along with a short description of the error.
metaIf there's any useful data related to the request, it will appear in this key (ie. when pulling down codeshares for an airline, the meta key will contain a value listing the maximum codeshares for all airlines).

The only deviation from this format is successful responses to OAuth token requests - they don't use the data key, instead everything is inside the root object.

Rate Limiting

API requests are rate-limited using a variable leaky bucket algorithm. This is to ensure that any badly written or unexpectedly popular applications don't overload the API.

An X-Rate-Limit header will be returned with every request that is subject to rate limiting. It will contain two values separated by a slash - the first value will be how "full" your bucket is and the second will be the size of the bucket. Once these two values are equal (or the first is greater than the second), no more requests will be accepted. The token bucket empties at a rate of 1 per second, allowing you to burst requests, so long as the total number stays below the maximum bucket size.

The bucket will fill at a rate of 1 per request for most requests, however in times of high load or if you are doing complicated queries the bucket will fill at a higher rate (variable, based on the amount of processing required).

For example, X-Rate-Limit: 10 / 45 means that your token bucket is 10 requests full. If you waited a second, the value would be 9 / 45, and 5 seconds later after that it would be 4 / 45. If you were to keep hitting the server with requests then it would eventually reach 45 / 45 and subsequent requests would return a 429 error. Wait one second and it'd be 44 / 45, or wait 45 seconds and you'll be back down to 1 / 45 on the next request.

IATA Code Caveats

An important thing to remember when dealing with airline profiles is that IATA codes are not unique. People tend to assume they are unique identifiers for airlines when working with them for the first time, and in most cases they will be unique, but not always. An example of two airlines using the same IATA code under a controlled duplicate scheme are Silk Way West and Aerocaribbean - both use a code of 7L. Wikipedia has a good explanation on the historical reasons for why IATA codes aren't unique:

Airline designator codes follow the format xx(a), i.e., two alphanumeric characters (letters or digits) followed by an optional letter. Although the IATA standard provides for three-character airline designators, IATA has not used the optional third character in any assigned code. This is because some legacy computer systems, especially the "central reservations systems", have failed to comply with the standard, notwithstanding the fact that it has been in place for twenty years. The codes issued to date comply with IATA Resolution 762, which provides for only two characters. These codes thus comply with the current airline designator standard, but use only a limited subset of its possible range.

Schedule Types

There are numerous types of schedule, identified by one (or more) letters. They are listed below:

IdentifierSchedule type
AAdditional cargo/mail service
CCharter passengers only
FCargo/mail service with loose loaded cargo and/or preloaded devices
GAdditional normal passenger service
JNormal passenger service
MMail only
QPassenger/cargo in cabin (combi)
SPassenger shuttle mode
UPassenger service operated by surface vehicle
VCargo/mail service operated by surface vehicle

We include schedules of type J, S, F, Q, G, C in capacity counts.

Traffic Restriction Codes

Some schedules operate under traffic restrictions. This affects which schedules are displayed, as well as how we count capacity. A list of traffic restriction codes are below:

CodeRestriction
Ano local traffic
Blocal traffic only
Clocal and domestic connecting traffic only
Dqualified international online connecting or stopover traffic only
Equalified international online connecting or stopover traffic only
Flocal and online connecting traffic only
Gqualified online connecting traffic only
Hsegment not to be displayed
Itechnical landing
Kconnecting traffic only
Minternational online stopover taffic only
Ninternational connecting traffic only
Ointernational online connecting traffic only
Qinternational online connecting or stopover traffic only
Tonline stopover traffic only
Vconnecting or stopover traffic only
Winternational connecting or stopover traffic only
Xonline connecting or stopover traffic only
Yonline connecting traffic only
Ztraffic restrictions do not apply equally to passenger/cargo/mail

We include unrestricted flights in our capacity counts, as well as any operating under B, C, F restrictions.

Resizing Images

Image URLs that are returned from the CAPA API point to the full-sized original image. Normally you do not want to display this image to customers, as most images are often huge and their file sizes are in the range of 4MB or over.

The CAPA image server can automatically resize and cache images on-the-fly, if you modify the requested URL to include resize parameters. For example, if you requested an image with a URL of:

https://images.cdn.centreforaviation.com/stories/new_image_database/locations/london_bridge_Airplane_window_cityscape.jpg

...then you'd end up with a 23.7MB file with dimensions of 7304x5088 pixels. That is completely impractical for almost all use cases.

To resize it to something usable, you can specify the height required:

https://images.cdn.centreforaviation.com/stories/new_image_database/locations/london_bridge_Airplane_window_cityscape-1200x.jpg

This will output an image that is 1200 pixels wide and 151KB, which is much more usable. If you wanted to resize it by the height instead of the width:

https://images.cdn.centreforaviation.com/stories/new_image_database/locations/london_bridge_Airplane_window_cityscape-x800.jpg

Now you've got an image that has been resized to 800 pixels height and 142KB. You could also change the file format to PNG, by appending .png to the end of the URL:

https://images.cdn.centreforaviation.com/stories/new_image_database/locations/london_bridge_Airplane_window_cityscape-x800.jpg.png

That would shrink the filesize down from 142KB to 107KB.

You can also force dimensions to stretch images:

https://images.cdn.centreforaviation.com/stories/new_image_database/locations/london_bridge_Airplane_window_cityscape-1200x300.jpg

That will give you an image that has been stretched to 1200x300 pixels.

Note that you can only resize downwards. If you try to resize an image up further than its original dimensions, the original image will be returned instead of a resized one.

IMPORTANT: note that any images requested that do not have a specific change to the file format requested will be served as WebP if the request includes image/webp in the Accept headers. You can override this by adding a querystring of ?nowebp=1 to the request. So a request of:

https://images.cdn.centreforaviation.com/stories/new_image_database/locations/london_bridge_Airplane_window_cityscape-1200x300.jpg

...will return a WebP file, even though the extension is .jpeg. However...

https://images.cdn.centreforaviation.com/stories/new_image_database/locations/london_bridge_Airplane_window_cityscape-1200x300.jpg?nowebp=1

...will give you a JPEG.