Name: Airport Database API: IATA, ICAO, Distance and METAR
Brand: martindata
SKU: api-martindata-airportsflightdistan-api
Availability: InStock
Author: API Market

# Airport Database API

## Overview

The Airport Database API gives you airport reference data and aviation weather from one endpoint. You send a `POST` request to `/m/airports-flight-distance` and pick a `mode`: `distance` returns the great-circle distance, bearing and an estimated flight time for airport pairs, `lookup` returns full airport details by IATA or ICAO code, `search` finds airports by name, city, country or type, `nearby` lists airports around a latitude and longitude, and `weather` returns the latest METAR and, if asked, the TAF forecast for a station.

It is built for travel and booking app developers, itinerary and trip planning tools, logistics and carbon footprint calculators, flight school and aviation hobby apps, and data teams who need clean airport data without maintaining their own database. Every response is a JSON object with a `count` and an `items` list, where each item carries codes, names, coordinates, elevation, time zone and type, plus the computed distance or the decoded weather report.

## Features

*   **1 endpoint, 5 modes**: distance, lookup, search, nearby and weather through the same `POST` call.
*   **IATA and ICAO codes**: look up any airport by its 3-letter IATA or 4-character ICAO code.
*   **Flight distance**: kilometres, miles, nautical miles, initial bearing and an estimated block time per route.
*   **Search and filters**: search by text, country and airport type, or by radius around a point.
*   **Live weather**: decoded METAR plus raw TAF with validity times and flight category.
*   **Batch requests**: several routes or codes per request, up to 100 results.
*   **Rate limit**: 10 requests per second on every plan.

## Use Cases

*   **Travel and booking apps**: show distance and flight time between two airports.
*   **Airport pickers**: autocomplete airports by name or city and resolve codes to full names.
*   **Carbon and logistics tools**: compute route distances for emission or cost estimates.
*   **Flight planning and hobby apps**: read current METAR and TAF for departure and arrival airports.
*   **Location features**: find the nearest airports with scheduled flights to any point.

## API Documentation

### Base URL

All requests go through the API.market proxy at this base URL:

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

### Authentication

Every request needs your API.market key in the `x-api-market-key` header:

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

Replace `YOUR_API_KEY` with your actual API key.

### Endpoints

#### 1. Flight distance and estimated flight time

Returns the great-circle distance in kilometres, miles and nautical miles, the initial bearing, the time zone difference and an estimated flight time for each airport pair.

**Method:** `POST`

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

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `mode` | body | Set to `distance` | string | Yes | - | - |
| `routes` | body | Airport pairs as IATA or ICAO codes, for example `JFK-LHR`. Separators: dash, `to`, `>` or a space | array of strings | Yes | - | - |
| `maxItems` | body | Maximum number of results to return | integer | No | `20` | 100 |

**Example Request:**

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

**Example Response (200 OK):**

```json
{
  "count": 1,
  "items": [
    {
      "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-03T09:35:22Z",
      "timezoneDifferenceHours": 5,
      "to": {
        "city": "London",
        "countryCode": "GB",
        "iata": "LHR",
        "icao": "EGLL",
        "latitude": 51.470748,
        "longitude": -0.459909,
        "name": "London Heathrow Airport"
      },
      "toTimezone": "Europe/London"
    }
  ]
}
```

#### 2. Airport lookup by IATA or ICAO code

Returns full details for each airport: name, city, region, country, coordinates, elevation, time zone, type, runways, scheduled service and website links.

**Method:** `POST`

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

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `mode` | body | Set to `lookup` | string | Yes | - | - |
| `codes` | body | IATA (3 letters, e.g. `JFK`) or ICAO (4 characters, e.g. `EGLL`) codes | array of strings | Yes | - | - |
| `maxItems` | body | Maximum number of results to return | integer | No | `20` | 100 |

**Example Request:**

```bash
curl -X POST 'https://prod.api.market/api/v1/martindata/airportsflightdistan-api/m/airports-flight-distance' \
  -H 'x-api-market-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "lookup",
  "codes": [
    "JFK",
    "EGLL"
  ],
  "maxItems": 2
}'
```

**Example Response (200 OK):**

```json
{
  "count": 2,
  "items": [
    {
      "city": "New York",
      "continent": "NA",
      "country": "United States",
      "countryCode": "US",
      "elevationFt": 13,
      "homeLink": "https://www.jfkairport.com/",
      "iata": "JFK",
      "icao": "KJFK",
      "ident": "KJFK",
      "latitude": 40.639447,
      "longitude": -73.779317,
      "name": "John F. Kennedy International Airport",
      "region": "New York",
      "regionCode": "US-NY",
      "runways": {
        "count": 4,
        "longestFt": 14511,
        "longestM": 4423,
        "surfaces": ["ASP", "PEM"]
      },
      "scheduledService": true,
      "scrapedAt": "2026-11-03T09:35:29Z",
      "timezone": "America/New_York",
      "type": "large_airport",
      "utcOffsetHours": -5,
      "wikipedia": "https://en.wikipedia.org/wiki/John_F._Kennedy_International_Airport"
    },
    {
      "city": "London",
      "continent": "EU",
      "country": "United Kingdom",
      "countryCode": "GB",
      "elevationFt": 83,
      "homeLink": "http://www.heathrow.com/",
      "iata": "LHR",
      "icao": "EGLL",
      "ident": "EGLL",
      "latitude": 51.470748,
      "longitude": -0.459909,
      "name": "London Heathrow Airport",
      "region": "England",
      "regionCode": "GB-ENG",
      "runways": {
        "count": 2,
        "longestFt": 12799,
        "longestM": 3901,
        "surfaces": ["ASP"]
      },
      "scheduledService": true,
      "scrapedAt": "2026-11-03T09:35:29Z",
      "timezone": "Europe/London",
      "type": "large_airport",
      "utcOffsetHours": 0,
      "wikipedia": "https://en.wikipedia.org/wiki/Heathrow_Airport"
    }
  ]
}
```

#### 3. Airport search

Finds airports by text in the name, city, code or keywords, optionally filtered by country and airport type.

**Method:** `POST`

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

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `mode` | body | Set to `search` | string | Yes | - | - |
| `query` | body | Text to find, for example `heathrow`, `varna` or `international` | string | No | - | - |
| `country` | body | Two-letter ISO country code, for example `US` or `GB`. Empty means all countries | string | No | - | - |
| `types` | body | Airport types: `large_airport`, `medium_airport`, `small_airport`, `heliport`, `seaplane_base`, `balloonport`, `closed`. Empty means all open types | array of strings | No | - | - |
| `maxItems` | body | Maximum number of results to return | integer | No | `20` | 100 |

**Example Request:**

```bash
curl -X POST 'https://prod.api.market/api/v1/martindata/airportsflightdistan-api/m/airports-flight-distance' \
  -H 'x-api-market-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "search",
  "query": "heathrow",
  "maxItems": 2
}'
```

**Example Response (200 OK):**

```json
{
  "count": 2,
  "items": [
    {
      "city": "London",
      "continent": "EU",
      "country": "United Kingdom",
      "countryCode": "GB",
      "elevationFt": 83,
      "homeLink": "http://www.heathrow.com/",
      "iata": "LHR",
      "icao": "EGLL",
      "ident": "EGLL",
      "latitude": 51.470748,
      "longitude": -0.459909,
      "name": "London Heathrow Airport",
      "region": "England",
      "regionCode": "GB-ENG",
      "runways": {
        "count": 2,
        "longestFt": 12799,
        "longestM": 3901,
        "surfaces": ["ASP"]
      },
      "scheduledService": true,
      "scrapedAt": "2026-11-03T09:35:36Z",
      "timezone": "Europe/London",
      "type": "large_airport",
      "utcOffsetHours": 0,
      "wikipedia": "https://en.wikipedia.org/wiki/Heathrow_Airport"
    },
    {
      "city": "Robinson",
      "continent": "NA",
      "country": "United States",
      "countryCode": "US",
      "elevationFt": 525,
      "homeLink": null,
      "iata": null,
      "icao": "TE17",
      "ident": "TE17",
      "latitude": 31.438513,
      "longitude": -97.145842,
      "name": "Heathrow Airport",
      "region": "Texas",
      "regionCode": "US-TX",
      "runways": {
        "count": 1,
        "longestFt": 2200,
        "longestM": 671,
        "surfaces": ["TURF"]
      },
      "scheduledService": false,
      "scrapedAt": "2026-11-03T09:35:36Z",
      "timezone": "America/Chicago",
      "type": "small_airport",
      "utcOffsetHours": -6,
      "wikipedia": null
    }
  ]
}
```

#### 4. Nearby airports

Lists airports around a latitude and longitude, nearest first, with the distance and bearing from the point.

**Method:** `POST`

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

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `mode` | body | Set to `nearby` | string | Yes | - | - |
| `latitude` | body | Latitude of the centre point in decimal degrees | number | Yes | - | - |
| `longitude` | body | Longitude of the centre point in decimal degrees | number | Yes | - | - |
| `radiusKm` | body | Search radius in kilometres | integer | No | - | - |
| `scheduledServiceOnly` | body | Keep only airports with scheduled passenger flights | boolean | No | - | - |
| `types` | body | Airport types to include. Empty means large, medium and small airports | array of strings | No | - | - |
| `maxItems` | body | Maximum number of results to return | integer | No | `20` | 100 |

**Example Request:**

```bash
curl -X POST 'https://prod.api.market/api/v1/martindata/airportsflightdistan-api/m/airports-flight-distance' \
  -H 'x-api-market-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "nearby",
  "latitude": 43.2321,
  "longitude": 27.8251,
  "radiusKm": 150,
  "scheduledServiceOnly": true,
  "maxItems": 3
}'
```

**Example Response (200 OK):**

```json
{
  "count": 3,
  "items": [
    {
      "bearingDeg": 0,
      "city": "Varna",
      "continent": "EU",
      "country": "Bulgaria",
      "countryCode": "BG",
      "distanceKm": 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-03T09:35:43Z",
      "timezone": "Europe/Sofia",
      "type": "large_airport",
      "utcOffsetHours": 2,
      "wikipedia": "https://en.wikipedia.org/wiki/Varna_Airport"
    },
    {
      "bearingDeg": 199,
      "city": "Burgas",
      "continent": "EU",
      "country": "Bulgaria",
      "countryCode": "BG",
      "distanceKm": 77.8,
      "elevationFt": 135,
      "homeLink": null,
      "iata": "BOJ",
      "icao": "LBBG",
      "ident": "LBBG",
      "latitude": 42.569917,
      "longitude": 27.515173,
      "name": "Burgas Airport",
      "region": "Burgas Province",
      "regionCode": "BG-02",
      "runways": {
        "count": 1,
        "longestFt": 10499,
        "longestM": 3200,
        "surfaces": ["CON"]
      },
      "scheduledService": true,
      "scrapedAt": "2026-11-03T09:35:43Z",
      "timezone": "Europe/Sofia",
      "type": "large_airport",
      "utcOffsetHours": 2,
      "wikipedia": "https://en.wikipedia.org/wiki/Burgas_Airport"
    },
    {
      "bearingDeg": 22.7,
      "city": "Constanța",
      "continent": "EU",
      "country": "Romania",
      "countryCode": "RO",
      "distanceKm": 136.5,
      "elevationFt": 353,
      "homeLink": "http://www.mk-airport.ro/",
      "iata": "CND",
      "icao": "LRCK",
      "ident": "LRCK",
      "latitude": 44.362202,
      "longitude": 28.4883,
      "name": "Mihail Kogălniceanu International Airport",
      "region": "Constanţa County",
      "regionCode": "RO-CT",
      "runways": {
        "count": 1,
        "longestFt": 11483,
        "longestM": 3500,
        "surfaces": ["CON"]
      },
      "scheduledService": true,
      "scrapedAt": "2026-11-03T09:35:43Z",
      "timezone": "Europe/Bucharest",
      "type": "large_airport",
      "utcOffsetHours": 2,
      "wikipedia": "https://en.wikipedia.org/wiki/Mihail_Kog%C4%83lniceanu_International_Airport"
    }
  ]
}
```

#### 5. Aviation weather (METAR and TAF)

Returns the latest METAR observation for each station, decoded into wind, visibility, temperature, pressure and flight category, plus the raw TAF forecast when requested.

**Method:** `POST`

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

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `mode` | body | Set to `weather` | string | Yes | - | - |
| `codes` | body | IATA or ICAO codes, for example `EGLL`. ICAO codes of any weather station also work | array of strings | Yes | - | - |
| `includeTaf` | body | Also return the latest TAF forecast as raw text | boolean | No | `false` | - |
| `maxItems` | body | Maximum number of results to return | integer | No | `20` | 100 |

**Example Request:**

```bash
curl -X POST 'https://prod.api.market/api/v1/martindata/airportsflightdistan-api/m/airports-flight-distance' \
  -H 'x-api-market-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "weather",
  "codes": [
    "EGLL"
  ],
  "includeTaf": true,
  "maxItems": 1
}'
```

**Example Response (200 OK):**

```json
{
  "count": 1,
  "items": [
    {
      "altimeterHpa": 1033,
      "altimeterInHg": 30.5,
      "clouds": [],
      "dewpointC": 7,
      "elevationM": 26,
      "flightCategory": "VFR",
      "icao": "EGLL",
      "latitude": 51.477,
      "longitude": -0.461,
      "name": "London/Heathrow Intl, EN, GB",
      "observedAt": "2026-11-03T09:20:00Z",
      "rawMetar": "METAR EGLL 030920Z AUTO 03009KT 350V050 9999 NCD 10/07 Q1033",
      "rawTaf": "TAF EGLL 030455Z 0306/0412 04010KT 9999 SCT025 PROB30 TEMPO 0306/0309 BKN009 PROB40 TEMPO 0311/0323 4500 SHRA BKN012 PROB30 TEMPO 0311/0317 05015G25KT",
      "scrapedAt": "2026-11-03T09:35:47Z",
      "tafIssuedAt": "2026-11-03T04:55:00.000Z",
      "tafValidFrom": "2026-11-03T06:00:00Z",
      "tafValidTo": "2026-11-04T12:00:00Z",
      "temperatureC": 10,
      "type": "METAR",
      "visibilitySm": "6+",
      "weather": null,
      "windDirectionDeg": 30,
      "windGustKt": null,
      "windSpeedKt": 9
    }
  ]
}
```

## Status Codes

| Code | Status | Description |
|---|---|---|
| 200 | OK | The request ran and the results are in `items`, with their number in `count`. An empty `items` list means nothing matched. |
| 400 | Bad Request | The body is not valid JSON, `mode` is not one of the five modes, or a required field for that mode is missing. |
| 401 | Unauthorized | The `x-api-market-key` header is missing or the key is invalid. |
| 403 | Forbidden | Your key has no active subscription to the Airport Database API. Subscribe to a plan on API.market. |
| 404 | Not Found | The endpoint path is wrong. Use the path shown above. |
| 429 | Too Many Requests | You sent more than 10 requests per second, or your plan's quota is used up. |
| 500 | Internal Server Error | The request failed on the server. Retry it after a short wait. |
| 502 | Bad Gateway | The upstream airport or weather source did not answer. Retry the request. |
| 503 | Service Unavailable | The service is temporarily unavailable. Retry later. |

## Rate Limits

Every plan allows 10 requests per second. Requests above that, or after your plan's quota is used up, return 429. Throttle your client, back off and retry, and honour the `Retry-After` header when it is present. Each request runs a live lookup and usually takes 3 to 10 seconds, so send requests in parallel rather than one long loop, and ask for more results per request with `maxItems` instead of making many small calls.

## FAQ

*   **What is the difference between IATA and ICAO codes?**

    IATA codes are the 3-letter codes on boarding passes, such as `JFK`. ICAO codes are 4 characters and cover more airfields and weather stations, such as `KJFK` or `EGLL`. Both work in every mode that takes codes.

*   **Is the flight time a real schedule?**

    No. It is an estimate from the distance at 830 km/h plus 30 minutes for taxi, climb and descent, as the `estimateAssumptions` field states.

*   **Can I send several routes in one request?**

    Yes. Put each pair in the `routes` array; each one becomes an item, up to `maxItems`.

*   **How fresh is the weather?**

    Each request fetches the latest METAR, and TAF when `includeTaf` is true; `observedAt` and `tafIssuedAt` show when they were issued.

*   **Why do small airfields not show up in nearby results?**

    Set `scheduledServiceOnly` to false and add `small_airport` to `types` to include them.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


Look up airports by IATA or ICAO code, find nearby airports, get great-circle flight distance and time, and read live METAR and TAF weather as JSON.

Airport Database API: IATA, ICAO, Distance and METAR