@squawk/airports

Pure logic library for querying US airport data. Look up airports by FAA ID, ICAO code, geographic proximity, or name/city search. Contains no bundled data - accepts an array of Airport records at initialization. For zero-config use, pair with @squawk/airport-data.

Part of the @squawk aviation library suite. See all packages on npm.

Usage

import { usBundledAirports } from '@squawk/airport-data';
import { createAirportResolver } from '@squawk/airports';

const resolver = createAirportResolver({ data: usBundledAirports.records });

// Look up by FAA ID
const jfk = resolver.byFaaId('JFK');

// Look up by ICAO code
const ord = resolver.byIcao('KORD');

// Find nearest airports to a position
const nearby = resolver.nearest({ lat: 40.6413, lon: -73.7781 });
for (const result of nearby) {
  console.log(result.airport.name, result.distanceNm, 'nm');
}

// Search by name or city
const results = resolver.search({ text: 'chicago' });
Copy

Consumers who have their own airport data can use this package standalone:

import { createAirportResolver } from '@squawk/airports';

const resolver = createAirportResolver({ data: myAirports });
Copy

API

createAirportResolver(options)

Creates a resolver object from an array of Airport records.

Parameters:

• options.data - an array of Airport objects (from @squawk/types)

Returns: AirportResolver - an object with the lookup methods described below.

resolver.byFaaId(faaId)

Looks up an airport by its FAA location identifier (e.g. "JFK", "LAX", "3N6"). Case-insensitive. Returns Airport | undefined.

resolver.byIcao(icao)

Looks up an airport by its ICAO code (e.g. "KJFK", "KLAX"). Case-insensitive. Returns Airport | undefined.

resolver.nearest(query)

Finds airports nearest to a geographic position, sorted by distance ascending.

Returns NearestAirportResult[], each containing:

• airport - the matched Airport record
• distanceNm - great-circle distance in nautical miles (rounded to 2 decimal places)

// Find the 5 nearest airports within 50 nm
const nearby = resolver.nearest({
  lat: 40.6413,
  lon: -73.7781,
  maxDistanceNm: 50,
  limit: 5,
});

// Find only nearby heliports
const heliports = resolver.nearest({
  lat: 40.6413,
  lon: -73.7781,
  types: new Set(['HELIPORT']),
});
Copy

resolver.search(query)

Searches airports by name or city using case-insensitive substring matching. Results are returned in alphabetical order by name.

Returns Airport[].

const results = resolver.search({ text: 'san francisco', limit: 10 });
Copy