Terminology
Glossary of terms used throughout the docs and in response headers.
Aircraft models (planes)
| Term | Definition | Example |
|---|
| Slug | Unique stable identifier used internally. Case-insensitive, kebab-case. | airbus-a320-200 |
| IATA | 3-character code defined by IATA. | 320 (A320), 388 (A380) |
| ICAO | 4-character code defined by ICAO. | A320, A388, B789 |
| Family | Group of planes sharing an airframe. The renderer reuses the same image when a variant doesn't exist. | airbus-a320-family |
Airlines
| Term | Definition | Example |
|---|
| Slug | Unique stable identifier. | air-france, emirates |
| IATA | 2-character code. | AF, EK |
| ICAO | 3-character code. | AFR, UAE |
| Canonical brand | Short official display name. | "Air France", "Emirates" |
Liveries
| Term | Definition |
|---|
| Base | Airline's current main livery. |
| Special livery | Temporary or event livery (e.g. expo-2020, real-madrid). |
| Blank | Unpainted aircraft (factory image delivered by manufacturer). |
| Fallback | When the requested livery doesn't exist, the API falls back to base then blank. The x-fallback-reason header indicates the cause. |
View / orientation
| Term | Definition |
|---|
| Angle | Horizontal view in degrees (0 = front, 90 = right profile, 180 = rear, 270 = left profile, top = top-down view). |
| Gear | Landing gear state (down or up). |
| Pitch | Vertical inclination — number in degrees between -45 (nose-down) and 45 (nose-up). |
| Align | Vertical alignment within the canvas (bottom, center, top). |
Render / output
| Term | Definition |
|---|
| Canvas | The PNG/JPEG/WebP returned by the API, of size width × height. |
| Bbox | Bounding rectangle of the aircraft inside the source PNG. |
| Content size | Effective aircraft size after resizing into the canvas. |
| zoomType | contain (whole aircraft fits) or fill (canvas filled, may crop). |
| zoomLevel | Content size multiplier (1 = default, 0.5 = smaller, 2 = larger). |
| marginPercent | Margin between content and canvas edge as a percent (0–45). |
Cache
| Term | Definition |
|---|
| Edge cache | Cloudflare cache local to the datacenter. Default TTL 24 hours. |
| R2 | Cloudflare object storage; long-term persistence of pre-rendered assets and compositions. |
| Composed asset | PNG generated on the fly and persisted in R2 for subsequent requests. |
cf-cache-status | Header indicating HIT, MISS, REVALIDATED, STALE, ... |
x-image-source | Where the image came from (r2-livery, r2-base, r2-blank, composed, watermark-overlay). |
Security / auth
| Term | Definition |
|---|
| API key | Hex/base64 shared string. x-api-key header (or Authorization: Bearer, or ?api-key=). |
| Watermarked | Image served without a valid key: a central watermark indicates the request is not authenticated. |
x-auth-status | Diagnostic header: unauthorized or absent (auth OK). |
