Turkish Airlines (SXM) Flights API

You need to surface Turkish Airlines (IATA: TK) flight data that’s relevant to Princess Juliana International Airport (IATA: SXM) in a way your app can trust and ship. By the end of this guide, you’ll pull TK schedules with one request, understand how to layer in live status, and know exactly which fields to watch for terminals, gates, and delays—plus how to cache, poll, and handle diversions cleanly.

Turkish Airlines context

Turkish Airlines (IATA: TK) is the flag carrier of Türkiye. Its main hub is Istanbul Airport. For apps focused on SXM, TK flights may appear as long-haul segments, through connections, or as codeshares. This guide shows how to query TK data and structure your downstream logic so TK movements related to SXM are easy to monitor and display.

Which FlightLabs endpoints to use for TK at SXM

FlightLabs exposes REST endpoints that return JSON. You can combine schedules for discovery and planning with real-time status for day-of operations, plus routes for analytics. The table below compares what you’ll get from each relevant category when you’re working with Turkish Airlines and SXM.

Get Turkish Airlines schedules (filtering for SXM downstream)

Start by pulling TK schedules via the schedules endpoint. You can then filter by SXM in your application. All times returned are ISO 8601 in UTC unless otherwise noted by a timezone field in other endpoints; convert for user display.

cURL request (copy/paste)

curl -G "https://api.goflightlabs.com/flights-schedules" \
  --data-urlencode "access_key=YOUR_API_KEY" \
  --data-urlencode "iataCode=TK" \
  --data-urlencode "type=airline"

Parameters used:

• access_key: your API key (get one below).
• iataCode: TK for Turkish Airlines.
• type: airline (indicates you’re querying by airline IATA code).

Handling pagination: if your result set is large, inspect the response and documentation for pagination fields and iterate until you’ve collected all pages. Cache by departure day to avoid re-fetching unchanged schedules.

Parse schedules and filter for SXM in JavaScript

async function fetchTurkishSchedules() {
  const params = new URLSearchParams({
    access_key: "YOUR_API_KEY",
    iataCode: "TK",
    type: "airline"
  });
  const res = await fetch(`https://api.goflightlabs.com/flights-schedules?${params.toString()}`);
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  const json = await res.json();

  // The schedule sample below shows the general structure.
  // Filter for SXM (Princess Juliana International) on either end.
  const schedules = (json.data && json.data.schedules) ? json.data.schedules : [];
  const tkToOrFromSXM = schedules.filter(s => {
    const dep = s.departure && s.departure.airport;
    const arr = s.arrival && s.arrival.airport;
    return dep === "SXM" || arr === "SXM";
  });

  // Normalize core fields you’ll show to users
  return tkToOrFromSXM.map(s => ({
    flightNumber: s.flight_number,
    airlineIata: s.airline && s.airline.iata,
    depAirport: s.departure && s.departure.airport,
    depScheduledUtc: s.departure && s.departure.scheduled,
    depTerminal: s.departure && s.departure.terminal,
    arrAirport: s.arrival && s.arrival.airport,
    arrScheduledUtc: s.arrival && s.arrival.scheduled,
    arrTerminal: s.arrival && s.arrival.terminal,
    aircraft: s.aircraft && s.aircraft.type
  }));
}

// Example consumer
fetchTurkishSchedules()
  .then(list => console.log("TK + SXM schedules:", list))
  .catch(err => console.error(err));

Field mapping highlights:

• flight_number: identify the marketed flight users search for.
• departure.scheduled and arrival.scheduled: plan in UTC; convert for time zone display.
• terminal and gate fields: show where available; if absent, keep the UI flexible.
• airline.iata: confirm the carrier code equals TK.

Official sample responses and the fields that matter

Below are official sample responses you can use to map UI and logic decisions. These samples illustrate structure and field names used across endpoints.

Real-time flight tracking: official sample

{
    "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
            }
        }
    }
}

What to use in your SXM + TK context:

• flight.status: drive UI states—“scheduled”, “en-route”, “landed”, “cancelled”, “diverted” (values can vary by data source but follow typical aviation semantics).
• departure.scheduled vs departure.actual: calculate off-block or push time deltas for delay tiles.
• arrival.scheduled vs arrival.estimated: ETA displays and connection impact flags.
• terminal and gate fields: airport display boards and wayfinding for connections that lead to or from SXM.
• position.*: in-flight map and arrival predictions; when flights are TK-marketed, use this to notify SXM stakeholders as a connecting inbound approaches a hub.

Flight schedules: official sample

{
    "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"
                }
            }
        ]
    }
}

What to use in your SXM + TK context:

• flight_number and airline.iata: identify TK-marketed segments. The same structure applies when iata is TK.
• departure/arrival.scheduled: preload boards and itineraries in UTC, then localize for SXM or intermediate hubs.
• aircraft.type: inform connection minimum times and operational constraints (e.g., boarding times varies by widebody vs narrowbody).

From plan to operations: stitching schedules to live status

Your common workflow will be:

1. Use schedules to pre-populate TK itineraries relevant to SXM (origin “SXM” or destination “SXM”, or via-hub connections).
2. On day-of, hydrate select flights with real-time status and position to update ETAs, terminals, and gates.
3. Persist snapshots for history and analytics.

Practical tips that save time:

• Time zones: Treat all scheduled/actual/estimated timestamps as UTC unless a timezone field is explicitly returned. Convert at the edge (client or API gateway) for SXM’s local time during display only.
• Polling: Poll real-time status more frequently inside a departure/arrival window (e.g., from T-3h to T+1h) and reduce frequency outside. Cache responses for 30–60 seconds to limit redundant network calls.
• Cancelled or diverted: If status indicates “cancelled” or “diverted”, immediately flag itinerary states and avoid continuing to poll at high frequency; resume a low-frequency backoff to catch reinstatements.
• Caching and TTLs: Cache schedules by service day and airline (TK) with a TTL sized to your change tolerance (e.g., 12–24h). Overlay real-time for day-of changes without rewriting the base schedule.
• Error handling: Implement retries with jitter and circuit breaking. On persistent upstream errors, serve last-known-good cached responses with a “data delayed” banner.

Three practical TK + SXM use cases

1) Flight status boards for TK-marketed itineraries touching SXM

• Sourcing: Preload with schedules (departure/arrival.scheduled) and airline.iata=TK; filter to SXM endpoints.
• Operations: Overlay real-time status, departure.actual, arrival.estimated, and gate/terminal fields for precise passenger guidance.
• UI signals: Derive delay as actual - scheduled or estimated - scheduled; color-code thresholds.

2) Delay monitoring and alerting for connecting passengers to SXM

• Sourcing: Track TK inbound flights into hubs that connect to SXM later the same day.
• Fields: flight.status, departure.actual (off-block), arrival.estimated (ETA), and any gate changes.
• Logic: Trigger alerts if delay exceeds your MCT buffer for onward SXM segments.

3) Route and network analysis for TK pathways to SXM

• Sourcing: Combine schedules for TK with routes and, when needed, flight history for seasonality checks.
• Fields: airline.iata, origin/destination airports, scheduled timings, aircraft.type for capacity proxies.
• Outcome: Rank hubs and connection pairs most likely to feed SXM demand under the TK brand.

End-to-end example flow for developers

This is a minimal playbook you can implement today:

1. Discovery: Request TK schedules using the cURL above and store them partitioned by date and airport (SXM).
2. Selection: Keep only flights where departure.airport === "SXM" or arrival.airport === "SXM".
3. Display: Render UTC converted to SXM’s local time for passenger-facing views.
4. Operations overlay: During the operating window, query the real-time endpoint for matching flight numbers and update status, terminals, gates, and ETAs.
5. Backfill: Persist final actual times post-flight for analytics.

Implementation notes specific to TK and SXM

• Codeshares: If you detect multiple marketed numbers for the same physical leg, de-duplicate by aircraft registration where available or by a composite key (date + origin + destination + scheduled time).
• Gate/terminal sparsity: Not all airports expose terminal/gate for schedules; ensure your UI handles nulls and only promotes them to “confirmed” once live status returns them.
• Partial visibility: If TK does not operate a direct SXM leg, expect to glue segments across hubs. Make your logic robust to missing direct TK-to-SXM mappings and instead join by time-adjacent legs.
• Positions: Only show in-flight maps when the real-time response includes position fields; otherwise fall back to status text-only.

How FlightLabs fits your stack

FlightLabs is a single REST layer for flight data, with JSON payloads that are straightforward to parse and transform. You can start quickly with the schedules query above, then add live status when you’re ready. Review the Documentation for endpoint-specific filters, pagination, and response models, or call the API directly from your backend and stream updates to clients.

To explore payloads interactively and test queries, use the MCP console.

Access, pricing, and usage planning

• Access: You authenticate with an API key using access_key=YOUR_API_KEY in the query string.
• Trial: 7 days or 50 requests to validate your integration and data fit.
• Starter plan: $24.99/month—sized for small apps or internal tools tracking focused corridors like TK connections to SXM.
• Scaling: Plan for more generous quotas and concurrency as you move from schedules-only to live polling across many flights.

Operational guardrails you shouldn’t skip

• UTC normalization: Store all timestamps in UTC internally; apply airport-local time zones at the final display boundary.
• Idempotency: When persisting updates, use a deterministic key (flight_number + date + origin + destination) to avoid duplicates.
• Resilience: Implement exponential backoff on 429/5xx and serve cached data with a freshness label.
• Monitoring: Track status distribution by hour to tune your polling intervals (e.g., heavier polling near TK bank times that connect to SXM).

Frequently asked questions

How do I restrict schedule results to Turkish Airlines only?
Send iataCode=TK with type=airline in your schedules request, then filter the results for departure.airport === "SXM" or arrival.airport === "SXM" in your application.

Are times in local time or UTC?
Use the timestamps as UTC unless the payload explicitly includes a timezone indicator. Convert to SXM’s local time or the user’s preference at the UI layer.

How often should I poll real-time data?
Increase frequency inside the operational window for a flight (for example, every 30–60 seconds from T-3h to arrival), and reduce to every few minutes outside of it. Cache responses briefly to avoid redundant loads.

How do I handle cancellations or diversions for TK flights?
Watch the status field. When it is “cancelled” or “diverted,” immediately update the UI and notifications, and back off polling for that flight unless your policy is to detect reinstatements.

Can I analyze historic TK performance for SXM routes?
Yes. Use the Flight History category to gather past instances, then correlate scheduled versus actual times to understand patterns and connection risks.

Get your key and start building

Spin up your Turkish Airlines + SXM integration in minutes: grab an API key, call the schedules endpoint with iataCode=TK, and begin layering in real-time status as you finalize your UI. Create your account now: Register. For endpoint details and payload structures, visit the Documentation, and try queries live in MCP.