Airport Data TS

A comprehensive TypeScript library for retrieving airport information by IATA codes, ICAO codes, and various other criteria. Ships with a custom binary codec for fast, compact data loading (~84% smaller than JSON). Includes LLM tool definitions for AI integration.

Installation

npm install airport-data-ts

Features

• ESM-first with full TypeScript types and declaration files
• Custom binary codec — data ships as compact binary, decoded at runtime (~1.7 MB vs ~10.7 MB JSON)
• Runtime input validation via Zod schemas
• Search by IATA codes, ICAO codes, country, continent, and more
• Geographic proximity search with customizable radius
• External links to Wikipedia, airport websites, and flight tracking services
• Distance calculation between airports (Haversine)
• Filter by airport type (large_airport, medium_airport, small_airport, heliport, seaplane_base)
• Timezone-based airport lookup
• Autocomplete suggestions for search interfaces
• Advanced multi-criteria filtering
• Statistical analysis by country and continent
• Bulk operations for multiple airports
• Code validation utilities
• Airport ranking by runway length and elevation
• LLM tool definitions subpath export for AI integration

Quick Start

import {
  getAirportByIata,
  getAirportByCountryCode,
  findNearbyAirports,
  searchByName,
} from 'airport-data-ts';

// Look up by IATA code (returns array)
const [lhr] = await getAirportByIata('LHR');
console.log(lhr);
// {
//   iata: 'LHR',
//   icao: 'EGLL',
//   airport: 'London Heathrow Airport',
//   country_code: 'GB',
//   continent: 'EU',
//   latitude: 51.4706,
//   longitude: -0.461941,
//   elevation_ft: 83,
//   ...
// }

// Get all airports in a country (ISO 3166-1 alpha-2 code)
const usAirports = await getAirportByCountryCode('US');

// Find nearby airports (positional args: lat, lon, radiusKm)
const nearby = await findNearbyAirports(51.5, -0.1, 50);

// Search by name
const results = await searchByName('Heathrow');

Airport Data Structure

Each airport object contains the following fields:

interface AirportRecord {
  iata: string;                // 3-letter IATA code (e.g., "SIN")
  icao: string;                // 4-letter ICAO code (e.g., "WSSS")
  country_code: string;        // 2-letter ISO country code (e.g., "SG")
  continent: string;           // 2-letter continent code (AS, EU, NA, SA, AF, OC, AN)
  type: string;                // Airport type (large_airport, medium_airport, etc.)
  time: string;                // IANA timezone identifier (e.g., "Asia/Singapore")
  scheduled_service: string;   // "TRUE" or "FALSE"
  utc: number;                 // UTC offset (e.g., 8, -5)
  airport: string;             // Airport name
  latitude: number;            // Latitude in decimal degrees
  longitude: number;           // Longitude in decimal degrees
  elevation_ft: number;        // Elevation in feet
  wikipedia: string;           // Wikipedia URL (empty if none)
  website: string;             // Airport website URL (empty if none)
  runway_length: number;       // Runway length in feet (0 if unknown)
}

API Reference

Lookup Functions

| Function | Description | |---|---| | getAirportByIata(iataCode) | Look up airport by 3-letter IATA code (returns array) | | getAirportByIcao(icaoCode) | Look up airport by 4-character ICAO code | | getAirportByCountryCode(countryCode) | Get all airports in a country (ISO 3166-1 alpha-2) | | getAirportByContinent(continentCode) | Get all airports on a continent | | getAirportsByType(type) | Get airports by type classification | | getAirportsByTimezone(timezone) | Get airports in an IANA timezone |

Search & Discovery

| Function | Description | |---|---| | searchByName(query) | Case-insensitive partial name search | | findNearbyAirports(lat, lon, radiusKm?) | Geographic proximity search | | findNearestAirport(lat, lon, filters?) | Find single closest airport | | getAutocompleteSuggestions(query) | Autocomplete for search UIs | | findAirports(filters) | Advanced multi-criteria filtering |

Distance & Comparison

| Function | Description | |---|---| | calculateDistance(code1, code2) | Haversine distance in km between two airports | | calculateDistanceMatrix(codes) | Pairwise distance matrix for multiple airports | | getMultipleAirports(codes) | Bulk fetch by IATA/ICAO codes |

Statistics & Ranking

| Function | Description | |---|---| | getAirportStatsByCountry(countryCode) | Aggregated stats for a country | | getAirportStatsByContinent(continentCode) | Aggregated stats for a continent | | getLargestAirportsByContinent(continentCode, limit?, sortBy?) | Top airports ranked by runway or elevation | | getAirportCount(filters?) | Count airports matching filters |

Utility

| Function | Description | |---|---| | validateIataCode(code) | Check if IATA code exists in database | | validateIcaoCode(code) | Check if ICAO code exists in database | | isAirportOperational(code) | Check if airport has scheduled service | | getAirportLinks(code) | Get external links (Wikipedia, flight trackers) |

Advanced Usage

Multi-Criteria Filtering

import { findAirports } from 'airport-data-ts';

const results = await findAirports({
  country_code: 'US',
  type: 'large_airport',
  has_scheduled_service: true,
  min_runway_ft: 10000,
});

Distance Matrix

import { calculateDistanceMatrix } from 'airport-data-ts';

const matrix = await calculateDistanceMatrix(['LHR', 'JFK', 'SIN', 'NRT']);
console.log(matrix.distances['LHR']['JFK']); // ~5539 km

LLM Tool Definitions

Import pre-built JSON Schema tool definitions for use with AI frameworks:

import { airportTools } from 'airport-data-ts/tools';

// OpenAI function calling
const response = await openai.chat.completions.create({
  model: 'gpt-4',
  messages: [...],
  tools: airportTools.map(t => ({ type: 'function', function: t })),
});

// Anthropic tool use
const response = await anthropic.messages.create({
  model: 'claude-sonnet-4-20250514',
  messages: [...],
  tools: airportTools.map(t => ({
    name: t.name,
    description: t.description,
    input_schema: t.parameters,
  })),
});

Input Validation

All public functions validate their inputs using Zod schemas and throw descriptive errors for invalid arguments:

import { getAirportByIata } from 'airport-data-ts';

getAirportByIata('XX');  // throws: "Invalid IATA Code format. Please provide a 3-letter uppercase code, e.g., 'LHR'."

Project Structure

airport-data-ts/
├── src/
│   ├── index.ts              # Main library — all public functions
│   ├── codec.ts              # Binary encoder/decoder (pure JS, no Node deps)
│   ├── schemas.ts            # Zod validation schemas + derived types
│   ├── tools.ts              # LLM tool definitions (airport-data-ts/tools)
│   ├── airports.bin          # Binary airport data (~1.7 MB)
│   └── airports.bin.base64   # Base64-encoded binary for webpack inlining
├── data/
│   └── airports.json         # Source data (JSON)
├── scripts/
│   ├── encode_binary.ts      # Encode JSON → binary + base64
│   ├── check_duplicates.ts   # Find duplicate IATA/ICAO codes
│   ├── csv_to_json.ts        # Convert CSV source to JSON
│   ├── benchmark.ts          # Performance benchmarks
│   └── extract_latest_changelog.ts
├── tests/
│   ├── index.test.ts
│   └── __mocks__/airports.bin.base64.cjs
├── webpack.node.ts           # Node ESM build
├── webpack.tools.ts          # Standalone tools bundle
├── jest.config.ts
├── tsconfig.json
└── package.json

Build & Scripts

npm test                          # Run test suite
npm run typecheck                 # TypeScript type checking
npm run build                     # Full build (types + lib + tools)
npm run build:types               # Generate .d.ts declarations
npm run build:lib                 # Build Node ESM bundle
npm run build:tools               # Build standalone tools bundle
npm run encode                    # Re-encode binary data from airports.json
npm run check:duplicates          # Check for duplicate IATA/ICAO codes

Architecture

Binary Codec

Airport data is encoded into a custom binary format at build time (scripts/encode_binary.ts) and decoded at runtime (src/codec.ts). The format uses:

• String tables — Deduplicated, sorted string pools for IATA/ICAO codes, country codes, timezones, airport names, etc.
• IATA index table — Sorted IATA codes map directly to record offsets for O(1) lookup
• Varint encoding — LEB128-style unsigned and zigzag-encoded signed varints for compact integers
• Float32 — Latitude and longitude stored as IEEE 754 float32
• Presence flags — Optional fields (wikipedia, website, runway_length) use bit flags to avoid storing empty values

This achieves ~84% size reduction vs. the original JSON (1.7 MB binary vs. 10.7 MB JSON).

Webpack Embedding

The binary data is base64-encoded at build time (airports.bin.base64). Webpack's asset/source loader inlines it as a string. At runtime, the library decodes the base64 back to binary via atob(), then runs the binary decoder. This avoids UTF-8 corruption that occurs when asset/source handles raw binary bytes > 127.

License

CC BY 4.0