Cathay Pacific (Hong Kong International Airport, HKG) Airports API

You need to power Cathay Pacific (IATA: CX) flight experiences tied to Hong Kong International Airport (IATA: HKG)—from schedules to live status—without reinventing data pipelines. By the end of this article you will query FlightLabs for Cathay Pacific schedules, understand how to connect that data to live tracking and airport context, and ship production-safe polling, caching, and error handling for apps and airport displays.

Context: Cathay Pacific (CX) at Hong Kong International Airport (HKG)

Cathay Pacific is the flag carrier of Hong Kong (IATA: CX). Its primary hub is Hong Kong International Airport (IATA: HKG). This post focuses on building Cathay Pacific- and HKG-specific features using FlightLabs endpoints for schedules, real-time status, and reference data.

Which FlightLabs endpoints matter for CX at HKG?

The following endpoints are most useful when you’re building Cathay Pacific- and HKG-centric features. All responses are JSON via a simple REST interface, authenticated with your API key.

Quickstart: Query Cathay Pacific schedules

Use the schedules service to fetch CX flights. For an airline-level query, pass iataCode=CX and type=airline. You’ll need your API key.

curl -s 'https://api.goflightlabs.com/flights-schedules?iataCode=CX&type=airline&api_key=YOUR_API_KEY'

Response structure includes a top-level success boolean and a data.schedules array. Each schedule item provides planned times and terminal information. Times are in ISO-8601 with UTC (Z suffix).

Parse schedules and surface terminals and times (Python)

The snippet below calls the same endpoint and extracts CX flight numbers, plus scheduled UTC times and terminals for quick display on an arrivals/departures board.

import os
import requests
from datetime import datetime, timezone

API_KEY = os.getenv("FLIGHTLABS_API_KEY", "YOUR_API_KEY")
BASE = "https://api.goflightlabs.com"

params = {
"iataCode": "CX", # Cathay Pacific
"type": "airline", # airline-level schedules
"api_key": API_KEY
}

r = requests.get(f"{BASE}/flights-schedules", params=params, timeout=20)
r.raise_for_status()
payload = r.json()

if not payload.get("success"):
raise SystemExit("API returned success=false")

schedules = payload.get("data", {}).get("schedules", [])
for s in schedules:
flight_no = s.get("flight_number")
dep = s.get("departure", {})
arr = s.get("arrival", {})
dep_sched = dep.get("scheduled") # e.g., '2024-03-20T08:00:00Z'
arr_sched = arr.get("scheduled")
dep_term = dep.get("terminal")
arr_term = arr.get("terminal")

# Safely parse UTC timestamps for internal normalization
def to_utc(ts):
try:
return datetime.fromisoformat(ts.replace("Z", "+00:00")).astimezone(timezone.utc)
except Exception:
return None

dep_utc = to_utc(dep_sched)
arr_utc = to_utc(arr_sched)

print({
"flight_number": flight_no,
"dep_airport": dep.get("airport"),
"arr_airport": arr.get("airport"),
"dep_utc": dep_utc.isoformat() if dep_utc else None,
"arr_utc": arr_utc.isoformat() if arr_utc else None,
"dep_terminal": dep_term,
"arr_terminal": arr_term
})

For production, cache schedule responses and progressively enrich with real-time status (status, gates, estimated arrival) to minimize calls. When you detect changes (e.g., estimated drift or gate assignments), update your UI rather than constantly re-rendering the entire list.

Official example: Real-time tracking response structure

Use this sample to understand how live CX flight fields look in practice, including status, terminals, gates and aircraft position. In production, substitute Cathay Pacific flights and HKG as applicable—field names and structure remain the same.

{
"success": true,
"data": {
"flight": {
"iata": "AA123",
"icao": "AAL123",
"number": "123",
"status": "en-route",
"departure": {
"airport": "JFK",
"scheduled": "2024-03-20T10:00:00Z",
"actual": "2024-03-20T10:05:00Z",
"terminal": "8",
"gate": "B12"
},
"arrival": {
"airport": "LAX",
"scheduled": "2024-03-20T13:15:00Z",
"estimated": "2024-03-20T13:20:00Z",
"terminal": "4",
"gate": "45A"
},
"position": {
"latitude": 39.8729,
"longitude": -98.7372,
"altitude": 35000,
"speed": 495,
"heading": 270
}
}
}
}

Fields to wire into your CX/HKG experience:

• flight.status: Operational state to drive labels (e.g., “En Route”).
• departure.scheduled/actual and arrival.scheduled/estimated: UTC timestamps for schedule baselines and live estimates.
• terminal and gate: Route passengers or staff updates to the correct areas at HKG.
• position: Use latitude/longitude and altitude to visualize in-flight progress and compute dynamic ETAs.

Official example: Airport information structure

For context around HKG operations (time zone, terminals, weather), tap the airport information model. Below is the official sample which illustrates the structure. For HKG, the fields will represent Hong Kong specifics; handle them the same way.

{
"success": true,
"data": {
"airport": {
"iata": "JFK",
"icao": "KJFK",
"name": "John F. Kennedy International Airport",
"location": {
"lat": 40.6413,
"lon": -73.7781,
"city": "New York",
"country": "United States"
},
"timezone": "America\/New_York",
"terminals": [
"1",
"2",
"4",
"5",
"7",
"8"
],
"runways": [
{
"length_ft": 14511,
"width_ft": 150,
"surface": "concrete",
"designator": "13L\/31R"
}
],
"weather": {
"temp_c": 22,
"visibility_km": 10,
"wind": {
"speed_kts": 8,
"direction_deg": 180
}
}
}
}
}

Practical implications for HKG apps:

• timezone: Normalize to/from UTC for display to travelers and to schedule background jobs correctly.
• terminals: Cross-check CX terminal assignments at HKG to route users efficiently.
• weather: Optional but useful for delay risk messaging on CX departures/arrivals at HKG.

Official example: Schedule response structure

Here is the official schedule schema you will receive when calling the schedules service. The same structure applies when you query for Cathay Pacific (iataCode=CX) or for HKG-bound/outbound flights depending on the type filter you use.

{
"success": true,
"data": {
"schedules": [
{
"flight_number": "UA456",
"departure": {
"airport": "SFO",
"scheduled": "2024-03-20T08:00:00Z",
"terminal": "3"
},
"arrival": {
"airport": "ORD",
"scheduled": "2024-03-20T14:15:00Z",
"terminal": "1"
},
"aircraft": {
"type": "Boeing 787-9",
"registration": "N123UA"
},
"airline": {
"name": "United Airlines",
"iata": "UA"
}
}
]
}
}

Fields to surface:

• flight_number and airline.iata: Identify each CX flight consistently, even across codeshare contexts in your UI.
• departure/arrival.scheduled: Use as baseline for timetable views; all times are in UTC.
• terminal: Populate HKG terminal tiles in your departure/arrival boards.
• aircraft.type and registration: Optional details for ops dashboards and enthusiast views.

How to combine endpoints for CX at HKG

In production, you will usually query schedules first, then hydrate items with real-time data, and finally overlay airport context for user-facing details.

1. Fetch Cathay Pacific schedules via iataCode=CX and type=airline.
2. When a departure is imminent or in progress, request real-time status to get status, gates, and estimates.
3. Display with airport attributes (timezone, terminal list). All timestamps are UTC; convert to Asia/Hong_Kong for local display.

Use cases tied to Cathay Pacific and HKG

1) Flight status pages for CX at HKG

Start with schedules for all CX flights today, then augment flights approaching their window with real-time fields: flight.status, departure.actual, arrival.estimated, terminals and gates. Update the UI only when status or estimates change to limit API calls.

2) Delay monitoring and notifications

Pair schedules with delay signals from the delay prediction endpoint. Even without explicit delay values in schedule responses, you can react to arrival.estimated drift from arrival.scheduled in real-time updates to trigger traveler or crew alerts.

3) Route analysis for CX network planning anchored to HKG

List all Cathay Pacific routes using the routes endpoint, filtered to those touching HKG. Union this with historical data to see which markets have consistent operations and where to allocate display capacity or app prominence.

Time zones, polling, caching, and pagination

• UTC as source of truth: All sample timestamps are UTC (Z). Convert UTC to Asia/Hong_Kong for local HKG views. Keep UTC internally for comparisons and analytics.
• Polling frequency: For pre-departure/arrival windows (e.g., two hours before a CX flight), poll real-time status at a modest cadence. Outside the window, depend on cached schedules and back off aggressively.
• Caching: Cache schedules for a rolling day partition (e.g., keyed by airline CX and service date). Bust cache when you detect meaningful changes (status, estimated times, gate/terminal).
• Handling cancelled/diverted: Check flight.status for non-standard states as defined in the documentation. If a flight is cancelled or diverted, flag the card persistently and avoid repeated notifications.
• Pagination: Schedules can be large on peak days. Implement pagination using the API’s documented approach; if no explicit pagination fields are present, slice by time windows (e.g., hourly) and cache by window.

Error handling and reliability patterns

• Check the success field first. Short-circuit logic if success is false and log payloads for diagnosis.
• Timeouts and retries: Use conservative per-call timeouts (10–20s in CLI, lower in services) and bounded retries with jitter. Avoid retry storms during wide outages.
• Graceful degradation: If real-time calls fail, show schedule-only views with a badge like “Live data unavailable.”
• Schema stability: Use .get() accessors and null checks for optional fields like terminal/gate to prevent crashes when data is not present.

Field-by-field implementation notes for CX at HKG

• flight.status: Drive state machine in UI—Scheduled → Boarding (if available) → En Route → Landed. Treat unexpected states as exceptions that require operator attention.
• departure.actual and arrival.estimated: Derive delays by comparing actual/estimated against scheduled. All values are UTC; do comparisons in UTC, then render in local time.
• terminal and gate: Present clearly. Gates can change; when they do, add a visual “updated” indicator.
• position: Use latitude/longitude, speed, and heading to render maps. For privacy and performance, throttle map updates to a sensible cadence.

From HKG views to airline-wide apps

Once you’ve validated CX + HKG, you can extend the same code paths to other Cathay Pacific stations and partner routes. The JSON structures are consistent across endpoints, so you can reuse your data models and UI components with different filters and keys.

Testing with MCP and documentation

• Interactive exploration: Use the MCP to try queries and inspect responses before wiring your app.
• Deep dives: Read the parameter and schema notes in the Documentation to confirm optional fields, pagination strategies, and any rate-limit guidance.

Comparison: Choosing the right endpoint for your CX/HKG feature

Production details that save you time

• Normalize everything to UTC internally, then convert to Asia/Hong_Kong in the view layer.
• Use idempotent writes in your cache keyed by flight_number + service date + airline.iata to avoid dupes when multiple updates arrive.
• Gate/terminal volatility: Treat these as mutable fields and log changes to drive staff notifications at HKG.
• Codeshares: When both marketing and operating carriers are present in your internal data, consistently prioritize Cathay Pacific (iataCode=CX) for customer-facing labels. Align your logic with fields available in the schedule and real-time responses; where codeshare specifics are needed, consult the documentation for the exact fields to use.

Security and deployment

• Store the API key in your secret manager or environment variables, never in client-side code.
• Implement server-side aggregation when polling multiple CX flights for HKG to consolidate API calls and reduce client overhead.
• Monitor response schema versions through automated tests that validate the presence of critical fields (status, times, terminals).

Reference: Real-time, airport, and schedule JSONs together

For convenience, here are the three official JSON structures you’ll handle most in a CX/HKG integration.

Real-time Flight Tracking

{
"success": true,
"data": {
"flight": {
"iata": "AA123",
"icao": "AAL123",
"number": "123",
"status": "en-route",
"departure": {
"airport": "JFK",
"scheduled": "2024-03-20T10:00:00Z",
"actual": "2024-03-20T10:05:00Z",
"terminal": "8",
"gate": "B12"
},
"arrival": {
"airport": "LAX",
"scheduled": "2024-03-20T13:15:00Z",
"estimated": "2024-03-20T13:20:00Z",
"terminal": "4",
"gate": "45A"
},
"position": {
"latitude": 39.8729,
"longitude": -98.7372,
"altitude": 35000,
"speed": 495,
"heading": 270
}
}
}
}

Airport Information

{
"success": true,
"data": {
"airport": {
"iata": "JFK",
"icao": "KJFK",
"name": "John F. Kennedy International Airport",
"location": {
"lat": 40.6413,
"lon": -73.7781,
"city": "New York",
"country": "United States"
},
"timezone": "America\/New_York",
"terminals": [
"1",
"2",
"4",
"5",
"7",
"8"
],
"runways": [
{
"length_ft": 14511,
"width_ft": 150,
"surface": "concrete",
"designator": "13L\/31R"
}
],
"weather": {
"temp_c": 22,
"visibility_km": 10,
"wind": {
"speed_kts": 8,
"direction_deg": 180
}
}
}
}
}

Flight Schedule

{
"success": true,
"data": {
"schedules": [
{
"flight_number": "UA456",
"departure": {
"airport": "SFO",
"scheduled": "2024-03-20T08:00:00Z",
"terminal": "3"
},
"arrival": {
"airport": "ORD",
"scheduled": "2024-03-20T14:15:00Z",
"terminal": "1"
},
"aircraft": {
"type": "Boeing 787-9",
"registration": "N123UA"
},
"airline": {
"name": "United Airlines",
"iata": "UA"
}
}
]
}
}

Pricing and getting access

FlightLabs offers a Starter plan at $24.99/month and a trial (7 days or 50 requests) so you can test your CX/HKG integration before shipping. Sign up to obtain your API key and start calling endpoints within minutes.

• Get your key: Register
• Read parameter details: Documentation
• Explore live: MCP

FAQ

• How do I scope schedules specifically to Cathay Pacific?
  Use the schedules endpoint with iataCode=CX and type=airline. Cache results by service date and refresh periodically.
• How should I handle time zones for HKG displays?
  Store and compare times in UTC. Convert to Asia/Hong_Kong in the view layer, and display both local and UTC to staff if helpful.
• What if a flight is cancelled or diverted?
  Inspect flight.status from real-time tracking. When a non-standard outcome occurs (such as cancellation or diversion per the docs), persist the state, suppress repeated alerts, and provide clear messaging.
• How often should I poll real-time status?
  Increase frequency within a tight pre-departure/arrival window for CX flights at HKG; back off outside that window and rely on cached schedules. Avoid exceeding your quota by diffing previous responses and updating only when values change.
• How can I test quickly without wiring my app?
  Use the MCP for interactive requests and the Documentation for parameters and sample payloads. Once confident, switch the same calls into your code.

Build your Cathay Pacific + HKG flight experiences now. Get an API key and start integrating with the schedules and real-time endpoints in minutes: Register. For request/response specifics, visit the Documentation and test directly in MCP.