@squawk

TypeScript libraries for building aviation applications - weather and NOTAM parsing, FAA airport, airspace, and navigation data, flight plan routing and E6B math, live ADS-B decoding and feeds, aircraft registry lookup, and an MCP server that exposes it all to LLM clients.

Documentation | Architecture | Conventions | Contributing | Security | Discussions

Quick start

Every package is published independently under the @squawk scope, so install only what you need. Parsing libraries work on their own:

npm install @squawk/weather
Copy

import { parseMetar } from '@squawk/weather';

const metar = parseMetar('METAR KJFK 041853Z 21010KT 10SM FEW250 18/06 A3012');

console.log(metar.stationId); // "KJFK"
console.log(metar.flightCategory); // "VFR"
Copy

Query libraries are pure logic with no bundled data. Each has a companion *-data package holding a pre-processed FAA snapshot - pair them for zero-config use, or supply your own records:

npm install @squawk/airports @squawk/airport-data
Copy

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

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

const jfk = resolver.byIcao('KJFK');
console.log(jfk?.name);

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

To try the whole suite with no code, point an MCP-compatible LLM client at npx @squawk/mcp. See the @squawk/mcp README for client setup.

Packages

Weather and NOTAMs

Package	Description
@squawk/weather	Parse raw aviation weather strings (METAR, SPECI, TAF, SIGMET, AIRMET, PIREP, FD winds aloft), with an opt-in live AWC fetch layer
@squawk/notams	Parse raw ICAO-format and FAA domestic NOTAM strings into structured objects

AI integration

Package	Description
@squawk/mcp	Model Context Protocol server exposing the squawk libraries as tools for LLMs

Aeronautical data

Each query library is listed with its companion data package. The bundled snapshots are built from FAA sources and cover US data only.

Package	Description
@squawk/airports	Airport queries by identifier, location, or fuzzy search
@squawk/airport-data	Pre-processed FAA NASR airport snapshot with runways, frequencies, and ILS data
@squawk/airspace	Airspace queries by position and altitude, identifier, or fuzzy search across Class B/C/D/E, Special Use Airspace, and ARTCC boundaries
@squawk/airspace-data	Pre-processed FAA NASR airspace GeoJSON snapshot for use with @squawk/airspace
@squawk/navaids	Navaid queries by identifier, frequency, type, location, or fuzzy search
@squawk/navaid-data	Pre-processed FAA NASR navaid snapshot for use with @squawk/navaids
@squawk/fixes	Fix/waypoint queries by identifier, location, or fuzzy search
@squawk/fix-data	Pre-processed FAA NASR fix/waypoint snapshot for use with @squawk/fixes
@squawk/airways	Airway lookup, traversal, and expansion by designation, fix, or search
@squawk/airway-data	Pre-processed FAA NASR airway snapshot for use with @squawk/airways
@squawk/procedures	Instrument procedure lookup and expansion for SIDs, STARs, and IAPs (CIFP)
@squawk/procedure-data	Pre-processed FAA CIFP procedure snapshot for use with @squawk/procedures

Flight planning

Package	Description
@squawk/flightplan	Flight plan route string parsing and resolution using composed resolvers
@squawk/flight-math	Aviation flight computer calculations (E6B wind triangle, altitude, airspeed)

ADS-B and surveillance

Package	Description
@squawk/adsb-feed	Live ADS-B aircraft feed from a local dump1090-fa station (JSON, SBS, or Beast)
@squawk/mode-s	Decode raw Mode-S/ADS-B messages: CRC, CPR position, velocity, altitude, identity
@squawk/beast	Parse the Beast binary format into decoded Mode-S messages, with live streaming
@squawk/icao-registry	ICAO hex to N-number and aircraft info lookup with FAA parsing utilities
@squawk/icao-registry-data	Pre-processed FAA ReleasableAircraft snapshot for use with @squawk/icao-registry

Foundations

Package	Description
@squawk/geo	Geospatial utilities: great-circle distance, bearing, midpoint, point-in-polygon
@squawk/units	Aviation-aware unit conversion and formatting utilities
@squawk/search	Domain-agnostic fuzzy string matching and ranked search scoring
@squawk/types	Shared type definitions used across all packages

Apps

App	Description
Atlas	The official Squawk viewer - a chart-first web app for browsing aeronautical data. Not published to npm; run it from this repo.
@squawk/adsbtop	Terminal dashboard for live ADS-B aircraft tracking, built on @squawk/adsb-feed. Published to npm.
@squawk/adsbscope	ATC-style radar scope for live ADS-B traffic, served to your browser by a small CLI built on @squawk/adsb-feed. Published to npm.

npm install -g @squawk/adsbtop
npm install -g @squawk/adsbscope
Copy

Development

Working on the repo requires the Node version in .nvmrc (currently 24) or newer. The published @squawk/* packages support Node 22 and newer.

npm install
npm run build        # build all packages
npm run test         # run all tests
npm run lint         # lint all packages
npm run docs         # generate documentation
npm run build:data   # rebuild the *-data snapshots from FAA source files (see Tools)
Copy

See CONTRIBUTING.md for the full contributor workflow.

Tools

The tools/ directory contains the build pipelines that produce the data packages from raw FAA source files. They are not published to npm but are fully usable if you want to rebuild data from a newer FAA cycle or customize the pipeline. Most tools accept a NASR subscription .zip or extracted directory via --local and write their output to the corresponding data package. The ICAO registry tool parses the FAA ReleasableAircraft database; the procedure tool parses the FAA CIFP (ARINC 424) zip. See npm run build:data -- --help for the orchestrator that runs them all.

Tool	Description
build-airspace-data	Processes FAA NASR shapefiles and AIXM XML into airspace GeoJSON
build-icao-registry-data	Processes FAA ReleasableAircraft into ICAO registry JSON
build-airport-data	Processes FAA NASR airport, runway, frequency, and ILS CSVs into JSON
build-navaid-data	Processes FAA NASR NAV_BASE.csv into navaid JSON
build-fix-data	Processes FAA NASR FIX CSVs into fix/waypoint JSON
build-airway-data	Processes FAA NASR AWY.txt and ATS.txt into airway JSON
build-procedure-data	Processes FAA CIFP into SID / STAR / IAP procedure JSON

The tools share CSV parsing, CLI argument handling, and input resolution helpers through the private build-shared workspace package.

License

MIT