Name: Aviation API: Airport Database, Live Flights, FAA Delays
Brand: martindata
SKU: api-martindata-aviationsuite-api
Availability: InStock
Author: API Market

Martin Petrov

# Aviation API

## Overview

The Aviation API combines three aviation endpoints in one subscription. `/m/airports-flight-distance` is an airport and airline database with six modes: great circle distance, bearing and estimated flight time between airports, full airport details by IATA or ICAO code, text search, airports near a point, current METAR weather, and airline lookup. `/m/live-flights-near-airport` returns live aircraft near any airport, around a point or by callsign from open ADS-B data, with airline, route, altitude, speed and ETA. `/m/airport-delays-weather` returns live and past US airport delays from the FAA with METAR and TAF weather and a delay risk level.

It is built for developers of travel apps, flight trackers, airport displays, aviation tools and analytics dashboards who want airport codes, live flights and delays from one provider. In our tests JFK to LHR came back as 5,540 km and about 7 hours 10 minutes, a search near Varna found Varna and Burgas, the live mode listed arriving aircraft at JFK with routes and ETAs, and the delay summary covered 18 US airports from the FAA archive.

## Features

*   **3 endpoints**: airport and airline database, live flights and US airport delays.
*   **Airport database**: IATA and ICAO codes, distance, bearing, flight time, nearby airports, time zones and METAR.
*   **Live flights**: aircraft near any airport worldwide with route, airline and ETA.
*   **US delays**: FAA ground stops, ground delay programs and closures, with weather and delay risk.
*   **Delay history**: FAA events archived every 5 minutes since November 8, 2026.
*   **Billed per result**: one unit per result returned, shown in the `billed` field. Errors and empty results are free.

## Use Cases

*   **Travel apps**: show flight time, distance and delays for a trip.
*   **Flight trackers**: list the aircraft arriving at an airport.
*   **Airport displays**: combine live arrivals with delay status.
*   **Booking tools**: look up airport and airline codes.
*   **Analytics**: study which US airports are delayed most often.

## API Documentation

### Base URL

All requests use the following base URL.

```
https://prod.api.market/api/v1/martindata/aviationsuite-api
```

### Authentication

All requests are authenticated with the `x-api-market-key` header.

```
x-api-market-key: YOUR_API_KEY
```

Replace `YOUR_API_KEY` with your actual API key.

### Endpoints

#### 1. Look up airports, distances and airlines

Returns airport, route, weather or airline rows, depending on `mode`.

**Method:** `POST`

**Endpoint:** `/m/airports-flight-distance`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `mode` | body | `distance`, `lookup`, `search`, `nearby`, `weather` or `airline` | string | No | - | - |
| `routes` | body | Distance mode: airport pairs such as `JFK-LHR`. Dash, `to`, `>` or a space work as separators. | array of strings | No | - | - |
| `codes` | body | IATA (`JFK`) or ICAO (`EGLL`) codes for lookup and weather modes, or airline codes in airline mode | array of strings | No | - | - |
| `query` | body | Search and airline modes: text to find, for example `heathrow` or `lufthansa` | string | No | - | - |
| `country` | body | Two letter ISO country code filter | string | No | - | - |
| `types` | body | Airport types such as `large_airport` or `medium_airport` | array of strings | No | - | - |
| `latitude` | body | Nearby mode: centre latitude | number | No | - | - |
| `longitude` | body | Nearby mode: centre longitude | number | No | - | - |
| `radiusKm` | body | Nearby mode: search radius in kilometres | integer | No | - | - |
| `scheduledServiceOnly` | body | Keep only airports with scheduled passenger flights | boolean | No | - | - |
| `includeTaf` | body | Also return the latest TAF forecast | boolean | No | - | - |
| `includeFaaDelays` | body | Weather and lookup modes: add the FAA status of US airports | boolean | No | - | - |
| `activeAirlinesOnly` | body | Airline mode: return only active airlines | boolean | No | - | - |
| `maxItems` | body | Maximum rows to return | integer | No | `20` | 100 |

**Example Request:**

```bash
curl -X POST 'https://prod.api.market/api/v1/martindata/aviationsuite-api/m/airports-flight-distance' \
  -H 'x-api-market-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"mode": "distance", "routes": ["JFK-LHR", "SOF-VAR", "LAX-NRT"], "maxItems": 10}'
```

**Example Response (200 OK):**

```json
{
  "billed": 3,
  "count": 3,
  "items": [
    {
      "co2": {
        "defraCategory": "long-haul",
        "factorKgPerPassengerKm": 0.15282,
        "includesRadiativeForcing": true,
        "kgPerPassenger": 846.6,
        "kgPerPassengerByClass": {
          "business": 1880.2,
          "economy": 648.4,
          "first": 2593.4,
          "premiumEconomy": 1037.4
        },
        "kgPerPassengerWithoutRF": 501.0,
        "source": "UK DESNZ/DEFRA GHG conversion factors 2025, Business travel- air (direct flights, 8% distance uplift included)"
      },
      "estimateAssumptions": "Estimate only: block time = distance / 830 km/h + 30 min taxi/climb/descent overhead. Not a schedule.",
      "estimatedFlightMinutes": 430,
      "estimatedFlightTime": "7h 10m",
      "from": {
        "city": "New York",
        "countryCode": "US",
        "iata": "JFK",
        "icao": "KJFK",
        "latitude": 40.639447,
        "longitude": -73.779317,
        "name": "John F. Kennedy International Airport"
      },
      "fromTimezone": "America/New_York",
      "greatCircleKm": 5539.8,
      "initialBearingCompass": "NE",
      "initialBearingDeg": 51.4,
      "miles": 3442.3,
      "nauticalMiles": 2991.3,
      "route": "JFK-LHR",
      "scrapedAt": "2026-11-12T15:38:22Z",
      "timezoneDifferenceHours": 5.0,
      "to": {
        "city": "London",
        "countryCode": "GB",
        "iata": "LHR",
        "icao": "EGLL",
        "latitude": 51.470748,
        "longitude": -0.459909,
        "name": "London Heathrow Airport"
      },
      "toTimezone": "Europe/London"
    }
  ]
}
```

The `items` list above is shortened to one of three routes. A `nearby` call with `"latitude": 43.2321, "longitude": 27.8251, "radiusKm": 150` returns the airports around Varna:

```json
{
  "billed": 3,
  "count": 3,
  "items": [
    {
      "bearingDeg": 0.0,
      "city": "Varna",
      "continent": "EU",
      "country": "Bulgaria",
      "countryCode": "BG",
      "distanceKm": 0.0,
      "elevationFt": 230,
      "homeLink": null,
      "iata": "VAR",
      "icao": "LBWN",
      "ident": "LBWN",
      "latitude": 43.232101,
      "longitude": 27.8251,
      "name": "Varna Airport",
      "region": "Varna Province",
      "regionCode": "BG-03",
      "runways": {
        "count": 1,
        "longestFt": 8258,
        "longestM": 2517,
        "surfaces": [
          "CON"
        ]
      },
      "scheduledService": true,
      "scrapedAt": "2026-11-12T15:38:30Z",
      "timezone": "Europe/Sofia",
      "type": "large_airport",
      "utcOffsetHours": 2.0,
      "wikipedia": "https://en.wikipedia.org/wiki/Varna_Airport"
    }
  ]
}
```

#### 2. Get live flights

Returns one row per aircraft near an airport or point, or by callsign, registration or ICAO hex code.

**Method:** `POST`

**Endpoint:** `/m/live-flights-near-airport`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `mode` | body | `airport`, `area` or `flight` | string | No | - | - |
| `airports` | body | Airport mode: IATA (`JFK`) or ICAO (`KJFK`) codes | array of strings | No | - | 50 |
| `radiusNm` | body | Airport and area modes: radius in nautical miles | integer | No | - | 250 |
| `directions` | body | Airport mode filter: `arrival`, `departure`, `overflight`, `likely arrival`, `likely departure`, `on ground`, `unknown` | array of strings | No | - | - |
| `includeOnGround` | body | Include aircraft taxiing or parked at the airport | boolean | No | - | - |
| `maxAltitudeFt` | body | Skip airborne aircraft above this altitude | integer | No | - | - |
| `maxPerAirport` | body | Maximum rows per airport or point | integer | No | - | 1000 |
| `latitude` | body | Area mode: centre latitude, for example `50.03` | string | No | - | - |
| `longitude` | body | Area mode: centre longitude, for example `8.57` | string | No | - | - |
| `flights` | body | Flight mode: callsigns (`BAW117`), registrations (`N123AB`) or ICAO hex codes | array of strings | No | - | 100 |
| `includeRoutes` | body | Look up the route and airline of each callsign | boolean | No | - | - |
| `maxRouteLookups` | body | Maximum new route lookups per call | integer | No | - | 1000 |

**Example Request:**

```bash
curl -X POST 'https://prod.api.market/api/v1/martindata/aviationsuite-api/m/live-flights-near-airport' \
  -H 'x-api-market-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"mode": "airport", "airports": ["JFK"], "radiusNm": 20, "includeOnGround": false, "maxPerAirport": 5, "includeRoutes": true, "maxRouteLookups": 10}'
```

**Example Response (200 OK):**

```json
{
  "billed": 5,
  "count": 5,
  "items": [
    {
      "aircraftType": "A339",
      "airline": "Delta Air Lines",
      "airlineIata": "DL",
      "airlineIcao": "DAL",
      "airlineSource": "route (adsbdb)",
      "airport": {
        "city": "New York",
        "country": "US",
        "iata": "JFK",
        "icao": "KJFK",
        "name": "John F. Kennedy International Airport"
      },
      "altitudeFt": 2275,
      "attribution": "Positions: ADSB.lol (ODbL 1.0). Routes: adsbdb.com. Airlines: OpenFlights (ODbL 1.0), adsbdb.com.",
      "callsign": "DAL47",
      "category": "A5",
      "checkedAt": "2026-11-12T15:38:39Z",
      "destination": {
        "city": "New York",
        "country": "US",
        "iata": "JFK",
        "icao": "KJFK",
        "name": "John F Kennedy International Airport"
      },
      "direction": "arrival",
      "distanceNm": 10.1,
      "emergency": null,
      "etaMinutes": 3.0,
      "flightIata": "DL47",
      "groundSpeedKt": 200.1,
      "hex": "a544ee",
      "latitude": 40.48555,
      "longitude": -73.869511,
      "military": false,
      "onGround": false,
      "origin": {
        "city": "Amsterdam",
        "country": "NL",
        "iata": "AMS",
        "icao": "EHAM",
        "name": "Amsterdam Airport Schiphol"
      },
      "positionAgeSeconds": 0.317,
      "positionAt": "2026-11-12T15:38:38Z",
      "query": "JFK",
      "registration": "N439DX",
      "routeCheck": "on route",
      "routeFound": true,
      "squawk": "0737",
      "trackDeg": 8.33,
      "verticalRateFpm": 0
    }
  ]
}
```

The `items` list above is shortened to one of five aircraft.

#### 3. Get US airport delays and weather

Returns airport status rows, active delays, past delay events or per airport totals, depending on `mode`.

**Method:** `POST`

**Endpoint:** `/m/airport-delays-weather`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `mode` | body | `status`, `delays`, `history` or `summary` | string | No | - | - |
| `airports` | body | US airport codes, IATA or FAA (`JFK`) or ICAO (`KJFK`) | array of strings | No | - | - |
| `includeWeather` | body | Add current METAR and the TAF outlook. Live modes only. | boolean | No | - | - |
| `forecastHours` | body | Hours of the TAF forecast used for the outlook and delay risk | integer | No | - | 30 |
| `includeClosures` | body | Also show long running partial closures | boolean | No | - | - |
| `days` | body | History and summary modes: days to look back | integer | No | - | 365 |
| `eventTypes` | body | History and summary filter: `ground_stop`, `ground_delay`, `arrival_departure_delay`, `airspace_flow`, `closure`, `deicing` | array of strings | No | - | - |

**Example Request:**

```bash
curl -X POST 'https://prod.api.market/api/v1/martindata/aviationsuite-api/m/airport-delays-weather' \
  -H 'x-api-market-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"mode": "status", "airports": ["ATL", "JFK", "SFO"], "includeWeather": true, "forecastHours": 12}'
```

**Example Response (200 OK):**

```json
{
  "billed": 3,
  "count": 3,
  "items": [
    {
      "airport": "ATL",
      "checkedAt": "2026-11-12T15:38:44Z",
      "country": "US",
      "delayRisk": "low",
      "delayRiskReasons": [],
      "faaEvents": [],
      "faaUpdateTime": "Thu Nov 12 15:38:12 2026 GMT",
      "forecast": {
        "hours": 12,
        "issuedAt": "2026-11-12T13:53:00.000Z",
        "maxWindOrGustKt": 25,
        "raw": "TAF KATL 121353Z 1214/1318 29012G23KT P6SM FEW050 FEW250 FM121800 30015G25KT P6SM FEW200 FM130200 31010KT P6SM FEW080 FEW250 FM131500 32010G20KT P6SM SCT080 SCT250",
        "significantWeather": [],
        "validTo": "2026-11-13T18:00:00Z",
        "worstFlightCategory": "VFR"
      },
      "found": true,
      "groundDelayProgram": false,
      "groundStop": false,
      "iata": "ATL",
      "icao": "KATL",
      "latitude": 33.6367,
      "localTime": "2026-11-12T10:38:44-0500",
      "longitude": -84.4279,
      "maxDelayMinutes": null,
      "name": "ATLANTA/HARTSFIELD/JACKSON ATLANTA INTL",
      "state": "GA",
      "status": "normal",
      "timezone": "America/New_York",
      "weatherNow": {
        "altimeterHpa": 1008.9,
        "ceilingFt": null,
        "dewpointC": 11.1,
        "flightCategory": "VFR",
        "observedAt": "2026-11-12T14:52:00Z",
        "raw": "METAR KATL 121452Z 29011G23KT 10SM SCT024 SCT250 16/11 A2979 RMK AO2 SLP084 T01610111 51008 $",
        "temperatureC": 16.1,
        "visibilityMiles": "10+",
        "weather": null,
        "windDirectionDeg": 290,
        "windGustKt": 23,
        "windSpeedKt": 11,
        "windVariable": false
      }
    }
  ]
}
```

The `items` list above is shortened to one of three airports. A `summary` call with `"days": 3` returns one row per airport with FAA events:

```json
{
  "billed": 18,
  "count": 18,
  "items": [
    {
      "activeNow": 2,
      "airport": "SAN",
      "archiveFrom": "2026-11-08T16:03:24Z",
      "arrivalDepartureDelays": 5,
      "closures": 0,
      "disruptedMinutes": 1874,
      "events": 7,
      "groundDelayPrograms": 2,
      "groundStops": 0,
      "lastEventAt": "2026-11-12T15:23:40Z",
      "longestEventMinutes": 886,
      "mode": "summary",
      "pollEveryMinutes": 5,
      "reasons": {
        "VOL:Compacted Demand": 3,
        "VOL:Volume": 2,
        "airport volume": 2
      },
      "worstMaxDelayMinutes": 83
    }
  ]
}
```

## Status Codes

| Code | Status | Description |
|---|---|---|
| 200 | OK | The request succeeded and the JSON result is in the response body. |
| 400 | Bad Request | The JSON body is invalid or a parameter is out of range. |
| 401 | Unauthorized | The `x-api-market-key` header is missing or the key is not valid. |
| 403 | Forbidden | Your key does not have an active subscription that includes this endpoint. |
| 404 | Not Found | The path does not match an endpoint of this API. Check the Base URL and path. |
| 429 | Too Many Requests | You went over 10 requests per second or used up the units of your plan. |
| 500 | Internal Server Error | The request failed on the server. Retry once, then contact us if it continues. |
| 503 | Service Unavailable | The service is temporarily unavailable. Retry after a short wait. |

## Rate Limits

Every plan allows up to 10 requests per second. The Free trial includes 100 units, Pro includes 10,000 units per month for $19, and PAYG is billed $0.002 per unit. When you go over a limit, the API returns `429 Too Many Requests`. Throttle your requests, back off before retrying, and honour the `Retry-After` header when it is present.

## FAQ

*   **Is the flight time a schedule?**
    No. It is an estimate from the great circle distance at 830 km/h plus 30 minutes, as stated in `estimateAssumptions`.

*   **Which airports have delay data?**
    US airports that the FAA reports on. The airport database and live flights cover airports worldwide.

*   **Where does the live flight data come from?**
    Positions come from ADSB.lol open ADS-B data (ODbL), routes from adsbdb.com and airline names from OpenFlights.

*   **How far back does delay history go?**
    The archive started on November 8, 2026 and grows every 5 minutes.

*   **How many units does a call use?**
    One unit per result returned. The `billed` field shows the count, and rows with an error or no match are free.

## Contact Us

If you have any questions or need support, reach out through the chat embedded on this page or email us at hello@magicapi.com.


Airport and airline codes, flight distance, live aircraft near any airport and US airport delays from the FAA, in one aviation API subscription.

Aviation API: Airport Database, Live Flights, FAA Delays