API Documentation

MLB Flights API

Access real-time MLB team flight data, today's matchups with travel context, and historical flight records. Public endpoints require no authentication. Data export endpoints require an API key.

Authentication

Protected endpoints require an API key passed via header or query parameter:

# Header (recommended)
curl -H "x-api-key: YOUR_KEY" https://mlbflights.com/api/data/flights

# Query parameter
curl "https://mlbflights.com/api/data/flights?key=YOUR_KEY"

To get an API key, contact us with your use case. Keys are issued within 24 hours.

Endpoints

GET/api/flights/livePublic

Returns all currently in-air and recently scheduled MLB team flights with real-time position data. Supports demo mode for off-season testing.

Parameters

demobooleanReturn mock flights for UI testing

Example

curl https://mlbflights.com/api/flights/live

Response

{
  "flights": [
    {
      "id": 42,
      "teamId": 1,
      "teamName": "Atlanta Braves",
      "teamAbbr": "ATL",
      "teamColor": "#CE1141",
      "originAirport": "LAX",
      "destinationAirport": "ATL",
      "status": "in_air",
      "currentLatitude": 35.2,
      "currentLongitude": -106.5,
      "currentAltitude": 38000,
      "currentSpeed": 480,
      "restHoursBeforeGame": 18.5,
      "fatigueScore": 2,
      "source": "flightaware"
    }
  ],
  "lastUpdated": "2026-04-15T02:30:00Z"
}

GET/api/matchupsPublic

Returns today's MLB games with away team travel context — most recent flight, rest hours, fatigue score. Supports demo mode with 5 mock matchups.

Parameters

demobooleanReturn mock matchups for pre-season demos

Example

curl https://mlbflights.com/api/matchups

Response

{
  "matchups": [
    {
      "gameId": 101,
      "gameTime": "2026-04-15T23:10:00Z",
      "venue": "Fenway Park",
      "gameStatus": "scheduled",
      "awayTeam": {
        "id": 2, "name": "New York Yankees",
        "abbr": "NYY", "color": "#003087"
      },
      "homeTeam": {
        "id": 3, "name": "Boston Red Sox",
        "abbr": "BOS", "color": "#BD3039"
      },
      "travelContext": {
        "flightId": 55,
        "origin": "SEA",
        "destination": "BOS",
        "restHours": 11.2,
        "fatigueScore": 4,
        "flightStatus": "landed",
        "source": "flightaware"
      }
    }
  ],
  "date": "2026-04-15",
  "travelImpact": {
    "lowRestWinPct": 0.420,
    "highRestWinPct": 0.530,
    "sampleSize": 84
  }
}

GET/api/data/flightsRequires API key

Export historical flight data. Filter by team, date range, and season. Returns detailed flight records for analysis.

Parameters

teamstringTeam abbreviation (e.g., NYY, LAD)

fromdateStart date (YYYY-MM-DD)

todateEnd date (YYYY-MM-DD)

seasonintegerSeason year (default: current)

limitintegerMax rows (default: 100, max: 1000)

offsetintegerPagination offset

Example

curl -H "x-api-key: YOUR_KEY" \
  "https://mlbflights.com/api/data/flights?team=NYY&from=2026-04-01&to=2026-04-15"

Response

{
  "flights": [
    {
      "id": 55,
      "team": "NYY",
      "origin": "SEA",
      "destination": "EWR",
      "departedAt": "2026-04-14T06:30:00Z",
      "landedAt": "2026-04-14T12:00:00Z",
      "distanceMiles": 2402,
      "durationMinutes": 330,
      "restHoursBeforeGame": 11.2,
      "fatigueScore": 4,
      "source": "flightaware"
    }
  ],
  "total": 12,
  "limit": 100,
  "offset": 0
}

Rate Limits

Tier	Rate Limit	Max Rows	Price
Free	100 req/hour	100 per request	Free
Basic	500 req/hour	500 per request	$29/mo
Pro	2,000 req/hour	1,000 per request	$99/mo

Public endpoints (/api/flights/live, /api/matchups) are not rate-limited but may be cached.

Error Codes

401

Unauthorized

Missing or invalid API key. Include x-api-key header or ?key= parameter.

403

Forbidden

API key is inactive or expired. Contact support to reactivate.

429

Too Many Requests

Rate limit exceeded. Back off and retry after the Retry-After header value.

Response Format

All responses are JSON. Successful responses return data directly. Errors include a message field:

{
  "error": "Rate limit exceeded",
  "retryAfter": 3600
}

Timestamps are ISO 8601 UTC. Distances are in miles. Speeds are in knots. Altitudes are in feet.

MLB Flights API v1.0 — Questions? Contact us