Flight Schedules API for São Paulo–Guarulhos International Airport (GRU)

You need dependable, structured schedules for São Paulo–Guarulhos International Airport (GRU) that your app can poll, cache, and display without guesswork. By the end of this guide you’ll call the FlightLabs schedules endpoint for GRU, parse the results you care about (times, terminals, gates, aircraft, airline), and know how to combine schedules with real-time status for live boards, alerts, and synchronization jobs.

Why focus on GRU schedules

São Paulo–Guarulhos International Airport (IATA: GRU, ICAO: SBGR) serves the São Paulo metro area and is a major hub for domestic and international connections across South America, North America, Europe, Africa, and Asia. Because of its breadth of routes and banks of departures, developers often track GRU schedules for arrival boards, connection planning, and operation dashboards that depend on accurate scheduled times and terminals.

Illustration: Flight Schedules API for São Paulo–Guarulhos International Airport (GRU)

Endpoint to use: FlightLabs schedules for GRU

FlightLabs exposes flight schedules via a simple REST endpoint that returns JSON. For airport-level schedules, query by the airport’s IATA code with a type that indicates arrival or departure.

Base: https://api.goflightlabs.com
Endpoint: /flights-schedules
Query parameters: iataCode, type

You authenticate with an API key. If you don’t have one, you can start with a trial (7 days or 50 requests) or the Starter plan ($24.99/month). See the links below to register and explore the docs.

Register for an API key
Read the Documentation
Use the MCP to test queries interactively

GRU arrivals (copy-pasteable curl)

curl -G "https://api.goflightlabs.com/flights-schedules" \
  --data-urlencode "iataCode=GRU" \
  --data-urlencode "type=arrival" \
  --data-urlencode "api_key=YOUR_API_KEY"

GRU departures (JavaScript example)

async function fetchGruDepartures() {
  const params = new URLSearchParams({
    iataCode: "GRU",
    type: "departure",
    api_key: "YOUR_API_KEY"
  });

  const url = `https://api.goflightlabs.com/flights-schedules?${params.toString()}`;
  const res = await fetch(url);
  if (!res.ok) {
    throw new Error(`HTTP ${res.status} - ${res.statusText}`);
  }
  const json = await res.json();

  // Expect schedules array in json.data.schedules
  const records = (json && json.data && json.data.schedules) ? json.data.schedules : [];

  // Minimal normalization: keep fields your UI needs for boards and syncing
  return records.map((s) => ({
    flightNumber: s.flight_number || null,
    airlineIata: s.airline && s.airline.iata ? s.airline.iata : null,
    airlineName: s.airline && s.airline.name ? s.airline.name : null,
    aircraftType: s.aircraft && s.aircraft.type ? s.aircraft.type : null,
    registration: s.aircraft && s.aircraft.registration ? s.aircraft.registration : null,
    depAirport: s.departure && s.departure.airport ? s.departure.airport : null,
    depScheduledUtc: s.departure && s.departure.scheduled ? s.departure.scheduled : null,
    depTerminal: s.departure && s.departure.terminal ? s.departure.terminal : null,
    depGate: s.departure && s.departure.gate ? s.departure.gate : null,
    arrAirport: s.arrival && s.arrival.airport ? s.arrival.airport : null,
    arrScheduledUtc: s.arrival && s.arrival.scheduled ? s.arrival.scheduled : null,
    arrTerminal: s.arrival && s.arrival.terminal ? s.arrival.terminal : null,
    arrGate: s.arrival && s.arrival.gate ? s.arrival.gate : null
  }));
}

// Example usage: populate a table for departures
fetchGruDepartures()
  .then(rows => {
    console.log("Normalized GRU departures:", rows.slice(0, 5));
  })
  .catch(err => {
    console.error("Failed to load GRU departures:", err);
  });

Official schedule response example and field mapping

The example below shows the structure returned by the schedules endpoint. Use it to confirm field names and nesting before wiring your GRU parsing logic.


{
    "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 you will typically use for GRU boards and sync:

data.schedules: array of scheduled flights.
flight_number: your primary display ID (pair with airline.iata for uniqueness where needed).
departure.airport and arrival.airport: IATA codes, e.g., GRU, MAD, JFK.
departure.scheduled and arrival.scheduled: ISO 8601 timestamps in UTC (Z). Convert to America/Sao_Paulo for local display.
departure.terminal/arrival.terminal and gate (if present): render on airport screens and connection helpers.
airline.name and airline.iata: for carrier display and logo mapping.
aircraft.type and registration: optional but useful for enthusiast apps and equipment-specific operations.

How schedules compare with other FlightLabs endpoints for GRU

Schedules tell you what’s planned. For live operations at GRU—banks of long-hauls, regional shuttles, and late-night arrivals—you’ll often combine schedules with specific endpoints for status, history, or planning tasks. The table below compares common endpoints you might pair with schedules for GRU-focused apps.

Endpoint	Primary purpose	Key fields you’ll use	Typical polling	Common GRU use cases
/flights-schedules	Published timetable for arrivals or departures	flight_number, airline.iata, departure/arrival.airport, scheduled, terminal, gate, aircraft	Low (every 15–60 min) for day-of boards; cache results	Board layouts, roster sync, gate plan previews
Real-time	Live status and position	status, departure.actual, arrival.estimated, terminal, gate, position	Higher for active flights (30–120 sec), back off when inactive	Delay alerts, “now boarding” tiles, en‑route maps
Future flights	Forward-looking planning and predictions	Future schedule blocks and planning fields as documented	On-demand or hourly, then cache	Seasonal planning, forward price/availability models
Flight history	Historical operations	Past status/times for analytics	Batch or nightly jobs	Post‑ops analytics, reliability studies, SLA checks
Delay predictions	Probabilistic delay insights	Prediction outputs as documented	On-demand around day-of departure	Risk scoring for alerts and rebooking logic

Use cases at GRU: wiring schedules to real features

1) Arrivals board for GRU

Schedules endpoint provides arrival.airport = GRU, arrival.scheduled (UTC), and arrival.terminal/gate.
Convert arrival.scheduled from UTC to America/Sao_Paulo for on-site screens.
Enhance with Real-time: arrival.estimated and status to show “On time,” “Delayed,” or “Landed” equivalents based on status and time deltas.

2) Delay and gate-change alerts

Poll schedules at a low cadence to seed your day-of slate (flight_number, airline.iata, departure/arrival pairs).
Poll Real-time more frequently for those flights while they’re active. Use:
- status changes to trigger push/email/SMS.
- departure.actual and arrival.estimated vs. scheduled to compute deltas.
- terminal/gate changes to alert passengers already at GRU.

3) Nightly schedule sync for operations

Run a nightly job that queries /flights-schedules for GRU arrivals and departures for the next operating window; cache the JSON in your DB.
Join to reference tables for airlines and routes for reporting.
Use aircraft.type to forecast stand requirements or equipment-specific constraints.

Understanding fields that matter for GRU operations

flight_number and airline.iata: Together, these uniquely identify a marketed flight in many UIs. Store both.
scheduled vs. actual/estimated:
- Schedules: departure.scheduled and arrival.scheduled are UTC ISO 8601 (Z-suffixed). Treat them as the baseline.
- Real-time: departure.actual and arrival.estimated help you compute live delays without a dedicated delay field.
terminal and gate: Present in both schedule and real-time responses when available. Update your cache when these change to avoid conflicting displays at GRU’s terminals.
aircraft.type and registration: Useful for ops dashboards, fleet analytics, and FIDS customizations that include aircraft info.

Time zones, polling, and caching for GRU

Time zones: All sample timestamps are in UTC (Z). Convert to America/Sao_Paulo for local boards and traveler messaging. Store UTC internally to avoid DST edge cases.
Polling cadence:
- /flights-schedules: Low frequency (e.g., every 15–60 minutes) is usually enough on day-of operations. Cache by “airport+type+date” to reduce calls.
- Real-time: Increase frequency for flights within a departure/arrival window (e.g., from T–3h to arrival). Use exponential backoff when a flight is inactive.
Caching keys: Consider a hash of airline.iata + flight_number + departure.scheduled to detect updates to terminals and gates.

Handling cancellations and diversions gracefully

Schedules reflect intended operations; real-world changes surface through the Real-time endpoint’s status and time fields. Your logic should:

Treat status as the source of truth for operational state, especially when terminal/gate are missing or re-assigned.
Fallback to schedule times when actual/estimated are not yet populated, and mark the record as “scheduled.”
Hide or de-emphasize canceled operations once the status indicates a cancellation, even if the schedule entry exists.
For diversions, rely on arrival fields and status to update the destination and suppress GRU arrival tiles if the diverted flight will not arrive at GRU.

Error handling, pagination, and rate usage

Implementation notes to save time in production:

HTTP and schema handling: Validate that json.success is true before assuming data.schedules exists. Guard against empty or partial arrays.
Pagination: If the schedule response paginates for busy windows, iterate through pages until exhausted. If page/limit parameters are available for your account, apply them consistently and cache page cursors for retries. Refer to the Documentation for your plan’s pagination details.
Idempotency: For batch syncs, write upserts by a composite key (airline.iata + flight_number + departure.scheduled) to avoid duplicates across pages or retries.
Quota hygiene: Seed daily schedules with a few calls, then switch to targeted Real-time polling for only the flights relevant to your user or display.

Joining schedules with live status: field-level example

Below is the official Real-time response structure. Use it to enrich GRU schedules with live state, terminals, gates, and timing deltas.


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

Use status plus scheduled/actual/estimated to compute live delay and ETAs for GRU flights.
Terminal/gate from real-time can supersede schedule values when present.
Position is optional but useful for en‑route maps and “X minutes to arrival” displays.

Implementation blueprint for a GRU board

Nightly or hourly: Fetch /flights-schedules for GRU arrivals and departures; cache records keyed by airline.iata + flight_number + departure.scheduled.
At runtime:
- Filter to the next N hours for your display.
- For each candidate, query Real-time by callsign or flight number to obtain status, actual, estimated, and gate updates.
- Merge into the cache; update your UI only when a field changes to reduce screen flicker.
Alerts: Watch for changes to status, terminal, gate, and large shifts between scheduled and actual/estimated timestamps.

Testing and tooling

Run sample queries in the MCP console to confirm payload shapes and field availability for GRU.
Use endpoint references such as Flight Schedules and Real-time Flight Tracking while you test transforms.

Business and access considerations

Trial access: 7 days or 50 requests to validate your GRU workflow end-to-end.
Starter plan: $24.99/month—good for prototypes, small displays, or targeted alerting around GRU.
Scaling: As your polling cadence and coverage expand beyond GRU to multiple airports, review your usage and adjust plan tiers accordingly.

FAQ

How do I get only arrivals to GRU?
Call /flights-schedules with iataCode=GRU and type=arrival. Cache the result to avoid redundant requests.

Are timestamps in local time or UTC?
Samples show ISO 8601 UTC (Z). Convert to America/Sao_Paulo for GRU screens and traveler messaging, while storing UTC internally.

How should I detect delays if there’s no explicit delay field?
Compare scheduled vs actual (departure) and scheduled vs estimated (arrival) from the Real-time endpoint, and set your own delay thresholds for alerts.

What if a flight is canceled or diverted?
Treat Real-time status as the operational source of truth. Hide or mark canceled flights in your UI and suppress GRU arrivals for diversions when the destination changes.

Does the schedules endpoint paginate?
For large windows, pagination may apply. Iterate through pages as documented and use stable upsert keys. See the Documentation for parameter details.

Ready to build a dependable GRU board or alerting workflow? Start with the trial, then move to the Starter plan when you’re ready to ship. Get your key now: Register. For endpoint specifics and payloads, keep the Documentation open as you integrate.

Ready to use FlightLabs API?

Try it now!