# Airport & Airline Reference Dataset (`apt_marble/airport-airline-reference-dataset`) Actor

Resolve any place name, IATA or ICAO code into clean airport, city and airline reference records: official names, codes, coordinates, time zones, currency, city-wide groupings and cross-platform place identifiers. Ambiguous names are flagged, never guessed. No account or login needed.

- **URL**: https://apify.com/apt\_marble/airport-airline-reference-dataset.md
- **Developed by:** [Hamza](https://apify.com/apt_marble) (community)
- **Categories:** Travel
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.50 / 1,000 reference record collecteds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Airport & Airline Reference Dataset

Turn the messy place names your users, spreadsheets and partners actually type — `JFK`, `EGLL`, `NYC`, `London Heathrow`, `sao paulo`, `Zurch` — into clean, trustworthy reference records: official name, IATA and ICAO codes, city, country, coordinates, time zone, local currency, the city-wide code that covers a whole metropolitan area, and the place identifiers that major flight-search platforms use. Leave the search list empty and you get the entire catalogue of the world's airports with scheduled service instead. Built for the one job every travel dataset needs first and nobody wants to build: knowing exactly which airport somebody meant, and refusing to guess when the answer is genuinely ambiguous.

### What you can do with it

- **Validate place input before it costs you.** Check every code in your booking flow, your feed or your partner file against a real list of airports with scheduled service — instead of discovering downstream that someone sent a closed airfield or a code that does not exist.
- **Resolve free text to codes.** Map "London Heathrow", "sao paulo" or a typo like "Zurch" to the right airport, with a confidence grade on every match so you know what to trust and what to review.
- **Stop the London-Ontario class of error.** "London" matches six London-area airports *and* a Canadian one. This actor returns all of them, ranked, and flags the name as ambiguous rather than silently picking one.
- **Join travel datasets that use different identifiers.** Every record can carry the place identifiers used by the big flight-search platforms alongside IATA and ICAO, so your data lines up instead of nearly lining up.
- **Build a city-level view.** Get the city-wide code (NYC, LON, PAR, TYO…) with the exact list of airports it covers, so "flights to London" means all six and not just Heathrow.
- **Seed a database or a dropdown.** Download the whole catalogue — over four thousand airports plus city groupings — in one run, filtered to the countries you care about.
- **Convert local times correctly.** Each airport carries its time zone and an honest note about how firmly that zone is established.

### What you get

One record per airport, city grouping or airline. A real record, abridged:

```json
{
  "entityType": "airport",
  "iata": "LGW",
  "icao": "EGKK",
  "name": "London Gatwick Airport",
  "city": "London",
  "metroCode": "LON",
  "countryCode": "GB",
  "countryName": "United Kingdom",
  "currency": "GBP",
  "lat": 51.1487,
  "lon": -0.1857,
  "timeZone": "Europe/London",
  "timeZoneConfidence": "country",
  "isSchengen": false,
  "hasScheduledService": true,
  "airportType": "large",
  "carrierNetworks": ["FR", "W6"],
  "isCarrierBase": false,
  "placeId": "LGW",
  "geoId": "95565051",
  "altPlaceId": "Station:airport:LGW",
  "coverageNote": null,
  "query": "London Gatwick",
  "matchedOn": "name",
  "matchConfidence": "medium",
  "resolvedFrom": "bundled+online",
  "dataSnapshot": "2026-08-16",
  "collectedAt": "2026-08-16T19:33:56.817Z"
}
```

A city grouping looks the same, with `entityType: "metro"`, `metroMembers: ["JFK", "EWR", "LGA", "SWF"]`, and no time zone or runway size of its own — because a city that spans four airports has neither.

### Input reference

| Field | Type | Default | What it does |
| --- | --- | --- | --- |
| `queries` | list of text | *(empty)* | Airport codes, city codes or plain place names. **Leave empty to download the whole catalogue.** Up to 500 per run. |
| `entityTypes` | list | `["airport","metro"]` | Which record types to produce: `airport`, `metro` (city-wide groupings) and `airline`. |
| `countryFilter` | list of text | *(empty)* | Two-letter country codes such as `GB`, `US`, `DE`. Empty means every country. Up to 50. |
| `market` | select | `US` | The market whose place naming and ranking you want when a name has to be looked up online. |
| `onlineResolution` | select | `ambiguous` | `off` — answer everything locally, no extra charge. `ambiguous` — spend an online lookup only on names that stay unclear. `always` — spend one on every name, which attaches the cross-platform identifiers to every record and is charged for every name that comes back with an answer, including names the built-in catalogue had already settled. |
| `includeMetroGroupings` | boolean | `true` | Return the city-wide code alongside the individual airports, with its member list. |
| `includeTimezones` | boolean | `true` | Add each airport's time zone and how firmly it is established. |
| `includeNonAirports` | boolean | `true` | Keep scheduled heliports and water aerodromes — real ticketable places in Greenland, Norway, Alaska and the Caribbean. |
| `refreshCarrierNetworks` | boolean | `false` | Check both carriers' current station lists before building records instead of using the built-in edition. Each airline record says which edition its own list came from. |
| `maxMatchesPerQuery` | integer | `5` | How many candidate places one ambiguous name may return (max 25). |
| `maxOnlineLookups` | integer | `50` | Hard ceiling on online lookups in a run (max 500). This is the only thing that can add a charge beyond the records themselves. |
| `maxRows` | integer | `5000` | Hard ceiling on records produced (max 50,000). |
| `parallelLookups` | integer | `2` | How many names may be looked up online at once (max 8). |

### Output fields

| Field | Type | Description |
| --- | --- | --- |
| `entityType` | text | `airport`, `metro` (a city-wide code) or `airline`. |
| `iata` | text | Three-letter IATA code — the airport, the city code, or the two-character carrier code on airline records. |
| `icao` | text | null | Four-letter ICAO code. `null` where none is published and on city groupings. |
| `name` | text | Official name of the airport, city grouping or carrier. |
| `city` | text | null | Settlement the airport serves. |
| `metroCode` | text | null | The city-wide code this airport belongs to, if any. |
| `metroMembers` | list | On a city record, the airports it covers. Empty on airport records. |
| `countryCode` / `countryName` | text | ISO two-letter country code and its name. |
| `currency` | text | null | The country's own official currency, as an ISO 4217 code. `null` for the few countries whose currency arrangement is in transition — never guessed, and never an airline's selling currency. |
| `lat` / `lon` | number | null | Coordinates. On a city grouping, the centre point of its member airports. |
| `timeZone` | text | null | Time zone identifier, for example `Europe/London`. `null` on city groupings. |
| `timeZoneConfidence` | text | null | How firmly the zone is established for that airport. |
| `isSchengen` | boolean | null | Whether the country is in the Schengen area. The area is a closed list of member states, so this is answered for every country in the catalogue; `null` only on a place found by an online lookup whose country could not be established. |
| `hasScheduledService` | boolean | null | `true` for everything in the built-in catalogue. `null` for a place found only by an online lookup. |
| `airportType` | text | null | `large`, `medium`, `small`, `heliport` or `seaplane`. |
| `carrierNetworks` | list | Codes of the reference carriers that serve this airport. Joins to the `airline` records. |
| `isCarrierBase` | boolean | null | Whether a reference carrier bases aircraft here, where that is published. |
| `networkAirports` / `networkSize` | list / number | On an airline record, every airport that carrier serves and how many. On a city record, the size of the grouping. |
| `networkSource` | text | null | On an airline record, whether that carrier's own station list was `refreshed` this run or came from the `built-in` edition. `null` on airport and city records. |
| `placeId` | text | null | The place identifier the major flight-search platforms address this place by. Without an online lookup this is the built-in identifier, which for an airport is its IATA code and for a city grouping is the platform's own city identifier. |
| `geoId` | text | null | Numeric geographic identifier. Present when an online lookup ran for that name. |
| `altPlaceId` | text | null | A second widely used place identifier. Present when an online lookup ran for that name. |
| `coverageNote` | text | null | A plain warning when a code does not mean what it looks like — for example that `BKK` covers Suvarnabhumi only and not Don Mueang. |
| `query` | text | null | The search that produced this record. `null` in catalogue mode. |
| `matchedOn` | text | How the match was made: `iata`, `icao`, `metro`, `city`, `name`, `tokens`, `fuzzy`, `online` or `catalog`. |
| `matchConfidence` | text | `exact`, `high`, `medium` or `low`. A near-miss is never sold as an exact match. |
| `resolvedFrom` | text | `bundled`, `bundled+online` or `online`. |
| `dataSnapshot` | text | The edition of the built-in reference catalogue this record came from. |
| `collectedAt` | text | When the record was produced (ISO 8601, UTC). |

### Pricing

You pay per record produced, plus a small amount for each name that needed an online lookup.

| What you pay for | Price |
| --- | --- |
| Reference record collected | **$0.50 per 1,000 records** |
| Place resolved online | **$0.020 each** |

The second charge follows the `onlineResolution` setting, and it is worth reading before you pick one:

- `off` — no online lookup ever happens, so this charge cannot occur. Records only.
- `ambiguous` *(default)* — a lookup is spent only on a name that matched nothing, matched several places, or matched only one place partially. A name the built-in catalogue settled cleanly is never looked up and never charged.
- `always` — a lookup is spent on **every** name, including names the built-in catalogue already settled, because that is what attaches the cross-platform identifiers to every record. Every one of those that comes back with an answer is charged. Ten clean airport codes in `always` mode cost ten charges; the same ten in `ambiguous` mode cost none.

In every mode you are charged only when the lookup comes back with an answer that reaches your results: a lookup that does not complete, or that finds nothing, is not charged. `maxOnlineLookups` is a hard ceiling on how many can happen in one run, whatever the mode.

**Worked example.** You look up 200 place names. 180 of them are codes or unambiguous names and are answered locally. 20 are ambiguous free text and need an online lookup. The run produces 340 records in total.

- 340 records × $0.50 / 1,000 = **$0.17**
- 20 online lookups × $0.020 = **$0.40**
- **Total: $0.57**

Downloading the entire catalogue — every airport with scheduled service plus every city grouping, about 4,200 records — costs roughly **$2.10** and spends nothing on online lookups. A catalogue run answers everything from the built-in reference data, so `geoId` and `altPlaceId` are `null` on those records and `placeId` is the IATA code itself; the cross-platform identifiers come from an online lookup, which only a search run performs.

### Limits & what this actor cannot do

- **It is reference data, not availability data.** It tells you an airport exists, where it is and how it is addressed. It does not tell you whether anyone flies there today, what a flight costs, or whether a seat is available.
- **Ambiguity is reported, not resolved.** "London" matches several places on two continents. The actor returns the candidates ranked and marks the name ambiguous. It will not pick one for you, because picking one is how a booking ends up on the wrong continent.
- **Closed airfields and unscheduled strips are deliberately excluded.** The catalogue covers airports with scheduled service. If you search a disused code, the honest answer is "no match", and that is what you get.
- **Currency and Schengen status are country facts, held here as country facts.** The currency is the country's own official ISO 4217 currency, and a handful of countries whose arrangement is in transition are deliberately `null` rather than guessed. Schengen membership is the closed list of member states as of the reference edition, Bulgaria and Romania included since 1 January 2025. Neither field is ever taken from an airline, whose selling currency and border flags describe that airline's own business and not the country.
- **Airline records are narrow on purpose.** They cover only carriers that publish their complete airport list — today Ryanair and Wizz Air. A carrier whose full network cannot be established is absent rather than half-present, because a partial network read as a complete one is worse than no record at all.
- **Carrier network membership goes out of date.** Airlines open and close airports continuously. Treat it as a strong hint, not a guarantee, and switch on `refreshCarrierNetworks` when it matters: it re-reads **both** carriers' current station lists, and each airline record's `networkSource` says which edition that carrier's own list came from — `refreshed` if it was re-read this run, `built-in` if that check did not complete. A carrier whose list comes back suspiciously short is refused rather than published as a shrunken network, and its built-in edition is used instead.
- **A city name does not always reach every airport in that city.** Some airports are officially listed under their own town rather than the metropolis. That is exactly why the city-wide record exists: it carries the full member list.
- **A lookup the source refuses is reported as a failed lookup, never as "no such place".** The run summary counts names that matched nothing separately from names that could not be checked, and a run in which nothing could be checked ends as a failed run rather than a green run with an empty result.
- **Time zones carry a confidence grade, and you should read it.** Most are firmly established; a few are inferred from the country. The field tells you which is which instead of pretending they are all equal.
- **Coordinates are for orientation, not navigation.** They locate the airport well enough for maps and distance estimates. They are not survey-grade and must not be used for anything operational.
- **Speed depends on the size of the job.** A local run is effectively instant; a run with many online lookups takes as long as the sources take to answer. No fixed throughput is promised.
- **Lawful use is yours to manage.** The sources' terms govern automated collection. You are responsible for using the data lawfully and in line with those terms.

### FAQ

**Do I need an account on any travel site?**
No. Nothing is signed into and nothing is bought.

**Does it need my login or password?**
No. There is nothing to configure beyond the settings on this page.

**Can I run it without any online lookup at all?**
Yes. Set `onlineResolution` to `off`. Every code, every city code and every unambiguous name is still answered, instantly, from the built-in catalogue — and the only charge is the records themselves.

**Can I schedule it?**
Yes. A weekly or monthly schedule is the usual pattern for keeping a reference table current. Nothing here changes by the minute.

**How current is the data?**
Every record carries `dataSnapshot`, the edition of the built-in catalogue it came from, and `collectedAt`, the moment the record was produced. Airport reference data moves slowly; carrier networks move faster, which is what `refreshCarrierNetworks` is for.

**Why did my search return several records?**
Because the name genuinely matches several places. Look at `matchConfidence` and `matchedOn`: the top record is the best match, and the rest are the alternatives you would otherwise never have seen. Narrow it with `countryFilter` or search the exact code.

**Are the city codes safe to send to a flight search?**
The `metro` records are the codes that address a whole city. Where a code looks like a city but only reaches one airport, `coverageNote` says so in plain words — that warning exists because the mistake is invisible otherwise.

# Actor input Schema

## `queries` (type: `array`):

Airport codes, city codes or plain place names — for example JFK, EGLL, NYC, "London Heathrow" or "sao paulo". Leave this empty to download the whole reference catalogue instead.

## `entityTypes` (type: `array`):

Airports are single airports. Cities are the city-wide codes that cover several airports at once, such as NYC or LON. Airlines are carrier records with the full list of airports each carrier serves.

## `countryFilter` (type: `array`):

Two-letter country codes such as GB, US or DE. Only places in these countries are returned. Leave empty for every country.

## `market` (type: `string`):

The market whose spelling and place naming you want when a name has to be looked up online. This does not change which places exist — only how they are named and ranked.

## `onlineResolution` (type: `string`):

Off keeps every answer local and free of extra charges. Only when needed spends a lookup on names that stay ambiguous or unknown, so a name the built-in catalogue settles is never charged. Always spends one on every name — including names already settled locally — which attaches the cross-platform place identifiers to every record and is charged for every name that comes back with an answer.

## `includeMetroGroupings` (type: `boolean`):

Return the city code that covers all of a city's airports (NYC for JFK, EWR, LGA and SWF) alongside the individual airports, and list its members on the record.

## `includeTimezones` (type: `boolean`):

Add each airport's time zone and a note on how firmly it is established. Switch off for a smaller record.

## `includeNonAirports` (type: `boolean`):

Keep scheduled heliports and water aerodromes, which are real ticketable places in Greenland, Norway, Alaska and the Caribbean. Switch off for runway airports only.

## `refreshCarrierNetworks` (type: `boolean`):

Check both carriers' current station lists before building records, instead of using the built-in edition. Slightly slower; each carrier that could not be checked keeps its built-in edition, and every airline record says which edition its own list came from.

## `maxMatchesPerQuery` (type: `integer`):

How many candidate places a single ambiguous name may return. "London" legitimately matches six London-area airports plus London, Ontario.

## `maxOnlineLookups` (type: `integer`):

A hard ceiling on how many names may be looked up online in one run. This is the only part of the run that can add a charge beyond the records themselves.

## `maxRows` (type: `integer`):

A hard ceiling on how many records this run may produce. The full catalogue is a little over four thousand.

## `parallelLookups` (type: `integer`):

How many names may be looked up online at the same time. Leave at the default unless you have a reason to change it.

## Actor input object example

```json
{
  "queries": [
    "JFK",
    "London",
    "CDG",
    "Tokyo",
    "BKK"
  ],
  "entityTypes": [
    "airport",
    "metro"
  ],
  "countryFilter": [],
  "market": "US",
  "onlineResolution": "ambiguous",
  "includeMetroGroupings": true,
  "includeTimezones": true,
  "includeNonAirports": true,
  "refreshCarrierNetworks": false,
  "maxMatchesPerQuery": 5,
  "maxOnlineLookups": 50,
  "maxRows": 5000,
  "parallelLookups": 2
}
```

# Actor output Schema

## `records` (type: `string`):

Every airport, city grouping and airline record produced by this run.

## `table` (type: `string`):

The same records as a CSV file.

## `summary` (type: `string`):

Counts for this run: records produced, names read, names with no match, names that could not be checked, and duplicates skipped.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "queries": [
        "JFK",
        "London",
        "CDG",
        "Tokyo",
        "BKK"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("apt_marble/airport-airline-reference-dataset").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "queries": [
        "JFK",
        "London",
        "CDG",
        "Tokyo",
        "BKK",
    ] }

# Run the Actor and wait for it to finish
run = client.actor("apt_marble/airport-airline-reference-dataset").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "queries": [
    "JFK",
    "London",
    "CDG",
    "Tokyo",
    "BKK"
  ]
}' |
apify call apt_marble/airport-airline-reference-dataset --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,apt_marble/airport-airline-reference-dataset"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/5boqQY3Ysc7vHFxh8/builds/C0R90jac4RpnVWTqH/openapi.json