Basic Concepts
There are several concepts you should familiarise yourself with before delving into the API. They are listed below.
- Authentication
- Terminologies
- Request/Response Formats
- Rate Limiting
- IATA Code Caveats
- Schedule Types
- Traffic Restriction Codes
- Resizing Images
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:
| Key | Description |
|---|---|
| data | If data is returned from the request, it will be contained within this key. |
| errors | If 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. |
| meta | If 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:
| Identifier | Schedule type |
|---|---|
| A | Additional cargo/mail service |
| C | Charter passengers only |
| F | Cargo/mail service with loose loaded cargo and/or preloaded devices |
| G | Additional normal passenger service |
| J | Normal passenger service |
| M | Mail only |
| Q | Passenger/cargo in cabin (combi) |
| S | Passenger shuttle mode |
| U | Passenger service operated by surface vehicle |
| V | Cargo/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:
| Code | Restriction |
|---|---|
| A | no local traffic |
| B | local traffic only |
| C | local and domestic connecting traffic only |
| D | qualified international online connecting or stopover traffic only |
| E | qualified international online connecting or stopover traffic only |
| F | local and online connecting traffic only |
| G | qualified online connecting traffic only |
| H | segment not to be displayed |
| I | technical landing |
| K | connecting traffic only |
| M | international online stopover taffic only |
| N | international connecting traffic only |
| O | international online connecting traffic only |
| Q | international online connecting or stopover traffic only |
| T | online stopover traffic only |
| V | connecting or stopover traffic only |
| W | international connecting or stopover traffic only |
| X | online connecting or stopover traffic only |
| Y | online connecting traffic only |
| Z | traffic 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.