Name: Airport Data API: IATA and ICAO Airport Lookup
Brand: tidydata
SKU: api-tidydata-airport-data
Availability: InStock
Author: API Market

TidyData

# Airport Data API

## Overview

The Airport Data API covers about 9,500 airports and answers four kinds of question through four GET endpoints. Fetch one airport by its IATA code (MAD) or ICAO code (LEMD), search airports by name, city or code with an optional country filter, list the airports nearest to a latitude and longitude within a radius, or get the great-circle distance and a rough flight time between two airports. Every endpoint returns the same airport record, so the data you get from a search, a nearby lookup or a distance call can be stored and reused the same way.

Each airport record includes the IATA and ICAO codes, the airport name, latitude and longitude, elevation in feet, a size class (large, medium or small), the ISO country code, the ISO region code (for example ES-MD), the city and whether the airport has scheduled passenger service. The API is built for developers of travel and booking apps, flight trackers, logistics tools and carbon or distance calculators who need airport pickers, code validation or nearest airport logic without maintaining their own airport table. The data comes from OurAirports (public domain), and the service runs on a global edge network.

## Features

*   **Four endpoints**: Lookup by code, search by name or city, nearest airports to coordinates, and distance between two airports.
*   **IATA or ICAO input**: The code lookup and the distance endpoint both accept either a 3 letter IATA code or a 4 letter ICAO code.
*   **Search with filters**: Search by name, city or code, filter by ISO country code and return 1 to 100 results.
*   **Nearby by radius and size**: Pass coordinates, a radius in km and an optional size filter (large, medium or small); each result includes its distance in km, nearest first.
*   **Distance in three units**: The distance endpoint returns kilometres, miles and nautical miles plus an estimated flight time and the full record of both airports.
*   **Rich airport records**: Coordinates, elevation, size class, country, ISO region, city and a scheduled service flag on every result.
*   **10 requests per second**: All plans allow up to 10 requests per second, enough to drive a type ahead airport picker.

## Use Cases

*   **Airport pickers in booking forms**: Power a type ahead field with the search endpoint and store the IATA code, name and city the user picks.
*   **Flight trackers and travel apps**: Turn the codes in a flight record into full airport names, cities and coordinates for display and maps.
*   **Carbon and distance calculators**: Get the great-circle distance between two airports in km, miles or nautical miles as the input for emission estimates.
*   **Ground transport and logistics**: Find the airports nearest to a warehouse, hotel or customer address and rank them by distance.
*   **Data cleaning and enrichment**: Validate IATA and ICAO codes in a dataset and add country, region and coordinates to each row.

## API Documentation

### Base URL

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

```
https://prod.api.market/api/v1/tidydata/airport-data
```

### 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. Get an airport by code

Returns the full record for one airport identified by IATA code (MAD) or ICAO code (LEMD). Use it to validate a code or show an airport's name, city and coordinates.

**Method:** `GET`

**Endpoint:** `/v1/airports/{code}`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `code` | path | IATA (MAD) or ICAO (LEMD) | string | Yes | - | - |

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/tidydata/airport-data/v1/airports/MAD" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK):**

```json
{
  "iata": "MAD",
  "icao": "LEMD",
  "name": "Adolfo Suárez Madrid–Barajas Airport",
  "lat": 40.49341,
  "lon": -3.57225,
  "elevationFt": 1998,
  "size": "large",
  "country": "ES",
  "region": "ES-MD",
  "city": "Madrid",
  "scheduledService": true
}
```

#### 2. Search airports

Finds airports whose name, city or code matches q, with an optional ISO country filter and a limit of 1 to 100. Returns the query, a count and a list of airport records.

**Method:** `GET`

**Endpoint:** `/v1/airports/search`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `q` | query | Name, city or code | string | Yes | - | - |
| `country` | query | ISO country filter | string | No | - | - |
| `limit` | query | 1-100 | string | No | - | - |

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/tidydata/airport-data/v1/airports/search?q=london&country=&limit=10" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK, abridged):**

```json
{
  "query": "london",
  "count": 10,
  "airports": [
    {
      "iata": "LTN",
      "icao": "EGGW",
      "name": "London Luton Airport",
      "lat": 51.8747,
      "lon": -0.36833,
      "elevationFt": 526,
      "size": "large",
      "country": "GB",
      "region": "GB-ENG",
      "city": "Luton, Luton",
      "scheduledService": true
    },
    {
      "iata": "LGW",
      "icao": "EGKK",
      "name": "London Gatwick Airport",
      "lat": 51.14874,
      "lon": -0.18574,
      "elevationFt": 202,
      "size": "large",
      "country": "GB",
      "region": "GB-ENG",
      "city": "London",
      "scheduledService": true
    },
    {
      "iata": "LHR",
      "icao": "EGLL",
      "name": "London Heathrow Airport",
      "lat": 51.47075,
      "lon": -0.45991,
      "elevationFt": 83,
      "size": "large",
      "country": "GB",
      "region": "GB-ENG",
      "city": "London",
      "scheduledService": true
    }
  ]
}
```

#### 3. Find nearest airports

Lists airports within a radius in km of a latitude and longitude, nearest first, each with distanceKm. Filter by size (large, medium or small) and cap the list with limit.

**Method:** `GET`

**Endpoint:** `/v1/airports/nearby`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `lat` | query | Latitude | string | Yes | - | - |
| `lon` | query | Longitude | string | Yes | - | - |
| `radius` | query | Radius km | string | No | - | - |
| `type` | query | large, medium or small | string | No | - | - |
| `limit` | query | 1-100 | string | No | - | - |

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/tidydata/airport-data/v1/airports/nearby?lat=40.96&lon=-5.66&radius=200&type=&limit=10" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK, abridged):**

```json
{
  "lat": 40.96,
  "lon": -5.66,
  "radiusKm": 200,
  "count": 10,
  "airports": [
    {
      "iata": "SLM",
      "icao": "LESA",
      "name": "Salamanca Airport",
      "lat": 40.9521,
      "lon": -5.50199,
      "elevationFt": 2595,
      "size": "medium",
      "country": "ES",
      "region": "ES-CL",
      "city": "Salamanca",
      "scheduledService": true,
      "distanceKm": 13.3
    },
    {
      "iata": "VLL",
      "icao": "LEVD",
      "name": "Valladolid Airport",
      "lat": 41.7061,
      "lon": -4.85194,
      "elevationFt": 2776,
      "size": "medium",
      "country": "ES",
      "region": "ES-CL",
      "city": "Valladolid",
      "scheduledService": true,
      "distanceKm": 106.9
    },
    {
      "iata": "BGC",
      "icao": "LPBG",
      "name": "Bragança Airport",
      "lat": 41.8578,
      "lon": -6.70713,
      "elevationFt": 2241,
      "size": "medium",
      "country": "PT",
      "region": "PT-04",
      "city": "Bragança",
      "scheduledService": true,
      "distanceKm": 132.6
    }
  ]
}
```

#### 4. Distance between two airports

Returns both airport records plus the great-circle distance in km, miles and nautical miles and a rough estimated flight time.

**Method:** `GET`

**Endpoint:** `/v1/airports/distance`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `from` | query | IATA/ICAO | string | Yes | - | - |
| `to` | query | IATA/ICAO | string | Yes | - | - |

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/tidydata/airport-data/v1/airports/distance?from=MAD&to=JFK" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK):**

```json
{
  "from": {
    "iata": "MAD",
    "icao": "LEMD",
    "name": "Adolfo Suárez Madrid–Barajas Airport",
    "lat": 40.49341,
    "lon": -3.57225,
    "elevationFt": 1998,
    "size": "large",
    "country": "ES",
    "region": "ES-MD",
    "city": "Madrid",
    "scheduledService": true
  },
  "to": {
    "iata": "JFK",
    "icao": "KJFK",
    "name": "John F. Kennedy International Airport",
    "lat": 40.63945,
    "lon": -73.77932,
    "elevationFt": 13,
    "size": "large",
    "country": "US",
    "region": "US-NY",
    "city": "New York",
    "scheduledService": true
  },
  "distanceKm": 5760.5,
  "distanceMiles": 3579.4,
  "distanceNauticalMiles": 3110.4,
  "estimatedFlightTime": "7h 26m",
  "note": "Great-circle distance; flight time is a rough estimate (830 km/h + 30 min)."
}
```

## Status Codes

| Code | Status | Description |
|---|---|---|
| 200 | OK | The request succeeded and the result is in the response body. |
| 400 | Bad Request | A required parameter is missing or a value is invalid. The body explains the problem. |
| 401 | Unauthorized | The `x-api-market-key` header is missing, invalid or expired. |
| 403 | Forbidden | Your subscription does not include this endpoint. |
| 404 | Not Found | The requested item or path does not exist. |
| 429 | Too Many Requests | You went over 10 requests per second or used up your plan quota. |
| 500 | Internal Server Error | Something failed while processing the request. Retry after a short delay. |

## Rate Limits

Every plan allows 10 requests per second. The Pro plan includes 25,000 calls a month and the Ultra plan 150,000; when a monthly quota is used up, further calls return `429 Too Many Requests` until the next billing period. The pay-as-you-go plan has no quota and bills US$0.0005 per successful call. If you receive a `429`, back off before retrying and honour any `Retry-After` header.

## FAQ

**Can I look up an airport by ICAO code instead of IATA?**

Yes. The code lookup and the distance endpoint accept either format, so /v1/airports/LEMD and /v1/airports/MAD return the same Madrid airport.

**Why do some airports have a null IATA code?**

Not every airport has an IATA code. Smaller or non commercial airfields can have only an ICAO code, so the iata field is null for them. The nearby endpoint returned several such airports in our tests, for example Madrid Cuatro Vientos (LECU).

**How is the flight time calculated?**

It is a rough estimate based on the great-circle distance at 830 km/h plus 30 minutes, as stated in the response note. It does not use real schedules, routes or winds.

**Is the distance a road or flight path distance?**

Neither. It is the straight line great-circle distance between the two airports' coordinates, returned in kilometres, miles and nautical miles.

**What does the size field mean and how do I filter by it?**

Each airport is classed as large, medium or small. Pass type=large, medium or small on the nearby endpoint to return only that class, for example only large airports with scheduled service near a city.

**Where does the airport data come from?**

From OurAirports, a public domain dataset, covering about 9,500 airports with coordinates, elevation, country, region and city.

**How much does the Airport Data API cost?**

There is no free plan. Pay as you go costs US$0.0005 per call with no monthly fee. Pro is US$4.99 per month for 25,000 calls and Ultra is US$14.99 per month for 150,000 calls. All plans allow 10 requests per second.

## 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.


Airport lookup API for 9,500 airports: IATA and ICAO codes, name and city search, nearest airports to any point, and distance plus flight time between two.