Documentation

Base URL https://api.openflightapi.com/v3. JSON over HTTPS. API version 3.4.0, published 2026-02-18.

Quickstart

Grab a key from the dashboard, then fetch your first flight. Both examples below return the same data:

// JavaScript (Node 20+)
const res = await fetch(
  "https://api.openflightapi.com/v3/flights/OF1502",
  { headers: { Authorization: `Bearer ${process.env.OPENFLIGHT_KEY}` } }
);
const flight = await res.json();
console.log(flight.status, flight.departure.gate);
# Python (pip install openflight)
import os, openflight

client = openflight.Client(api_key=os.environ["OPENFLIGHT_KEY"])
flight = client.flights.get("OF1502")
print(flight.status, flight.departure.gate)
# → enroute 12

Authentication

Send your key as a bearer token in the Authorization header. Keys are environment-scoped (sandbox / production); sandbox keys return recorded fixture data and never count against your quota.

Keep keys server-side. If you need browser access, mint short-lived tokens via POST /tokens (15-minute TTL, scoped to specific flights).

Rate limits

PlanRequests / minuteWebhook events
Hobby601 endpoint
Pro60010 endpoints
Business6,000Unlimited

Every response includes X-RateLimit-Remaining and X-RateLimit-Reset. Exceeding the limit returns 429 with a Retry-After header.

REST endpoints

MethodPathDescription
GET/flights/{id}Live status of one flight
GET/flights?origin=&date=Search flights by airport, route or status
GET/airports/{icao}Airport metadata, delays index, weather
GET/schedules/{carrier}Published schedules for a carrier
GET/routes?carrier=Route network & frequencies
POST/predictions/delayPredicted delay (minutes + confidence)

Example response for GET /flights/OF1502:

{
  "id": "OF1502",
  "carrier": { "code": "AE", "name": "Aether Airlines" },
  "status": "enroute",
  "departure": {
    "airport": "KAUS", "scheduled": "2026-02-18T08:35-06:00",
    "actual": "2026-02-18T08:47-06:00", "gate": "12",
    "delay_minutes": 12
  },
  "arrival": {
    "airport": "KDEN", "scheduled": "2026-02-18T10:20-07:00",
    "estimated": "2026-02-18T10:31-07:00", "terminal": "B"
  },
  "aircraft": { "type": "A320neo", "registration": "N284AE" },
  "position": { "lat": 35.412, "lon": -102.337, "alt_ft": 34000, "speed_kts": 447 },
  "updated_at": "2026-02-18T09:41:22Z"
}

GraphQL

For dashboards that need exactly the right fields in one round trip, use the GraphQL endpoint at https://api.openflightapi.com/v3/graphql:

query FlightBoard($origin: String!) {
  airport(icao: $origin) {
    departures(status: DELAYED) {
      id
      carrier { name }
      departure { gate delay_minutes }
      predicted_delay { minutes confidence }
    }
  }
}

Webhooks

Register HTTPS endpoints to receive push events instead of polling. Events fire on status changes (flight.departed, flight.arrived, flight.diverted, gate.changed) and prediction updates. Payloads are signed with HMAC-SHA256 (X-OpenFlight-Signature); failed deliveries retry for 12 hours with backoff. Maximum 10 webhook endpoints on Pro, unlimited on Business.

SDKs

First-party SDKs: openflight (Python, pip), @openflight/sdk (TypeScript, npm), openflight-go and OpenFlightSwift. All are generated from the OpenAPI 3.1 spec, so every example in these docs type-checks. Install commands, code samples and community clients (PHP, Ruby, .NET, Rust, Elixir) are on the SDK page.

Error codes

HTTPCodeWhen
401invalid_keyBad or revoked API key
404flight_not_foundUnknown flight id
422bad_queryInvalid ICAO/date combination
429rate_limitedPlan limit exceeded
451carrier_restrictedCarrier excluded in your region/plan
503degraded_feedPosition data temporarily partial

Status & SLA

Live status and incident history on our status page. Business plans include a 99.95% uptime SLA with service credits; current trailing-12-month uptime is 99.99%. Scheduled maintenance windows are published at least 7 days in advance and never count against the SLA if under 60 minutes per quarter.

Questions? support@openflightapi.com — we answer in about 4 hours on business days.