{"id":37077747,"url":"https://github.com/stiles/hangarbay","last_synced_at":"2026-01-14T09:01:14.068Z","repository":{"id":323247484,"uuid":"1092574690","full_name":"stiles/hangarbay","owner":"stiles","description":"A reproducible workflow for the FAA aircraft registry. Download raw data, normalize it into typed tables and query with SQL. Fast lookups for individual aircraft, powerful queries for fleet analysis.","archived":false,"fork":false,"pushed_at":"2025-11-09T02:10:39.000Z","size":292,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-09T02:33:47.302Z","etag":null,"topics":["aviation","data-pipeline","duck","faa","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stiles.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-08T22:02:04.000Z","updated_at":"2025-11-09T02:13:03.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/stiles/hangarbay","commit_stats":null,"previous_names":["stiles/hangarbay"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/stiles/hangarbay","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stiles%2Fhangarbay","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stiles%2Fhangarbay/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stiles%2Fhangarbay/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stiles%2Fhangarbay/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stiles","download_url":"https://codeload.github.com/stiles/hangarbay/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stiles%2Fhangarbay/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28414732,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T08:38:59.149Z","status":"ssl_error","status_checked_at":"2026-01-14T08:38:43.588Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aviation","data-pipeline","duck","faa","python"],"created_at":"2026-01-14T09:01:13.272Z","updated_at":"2026-01-14T09:01:14.063Z","avatar_url":"https://github.com/stiles.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Hangarbay\n\n**Stop struggling with FAA registration data.** Get clean, queryable aircraft registry tables in seconds.\n\nHangarbay downloads, normalizes and indexes the complete [FAA aircraft registry](https://www.faa.gov/licenses_certificates/aircraft_certification/aircraft_registry/releasable_aircraft_download) so you can skip straight to analysis. No more hunting for files to download, or joining fragmented tables, or decoding cryptic lookup relationships. One command gets you 307,000+ aircraft registrations, owners and specifications ready to query with SQL or pandas.\n\nThis is a tool built for researchers, data journalists and aviation analysts who need fast, reliable and repeatable workflows. \n\n## Quick start\n\n**Requirements:** Python 3.9+\n\n### Python API (notebooks \u0026 scripts)\n\n```python\n# Install\npip install hangarbay\n\n# One-time setup\nimport hangarbay as hb\nhb.load_data()  # Downloads \u0026 processes FAA data to ~/.hangarbay/data/\n\n# Look up aircraft\ndf = hb.search(\"N221LA\")\n\n# Find fleets\nfleet = hb.fleet(\"United Airlines\")\nfleet = hb.fleet(\"LAPD|Los Angeles Police\", state=\"CA\")\n\n# Custom SQL\ndf = hb.query(\"\"\"\n    SELECT maker, COUNT(*) as count\n    FROM aircraft_decoded\n    WHERE year_mfr \u003e 2020\n    GROUP BY maker\n    ORDER BY count DESC\n\"\"\")\n\n# Check data age\ninfo = hb.status()\nprint(f\"Data is {info['age_days']} days old\")\n```\n\n### Command-line interface\n\n```bash\n# Install\npip install hangarbay\n\n# Run the full pipeline (\u003c 1 minute, depending on your connection)\nhangar update     # Download, normalize and publish (in one step)\n\n# Or run steps individually\nhangar fetch      # Download FAA data\nhangar normalize  # Parse to typed Parquet tables\nhangar publish    # Build DuckDB + SQLite FTS indexes\n\n# Check data status and age\nhangar status\n\n# Start querying!\nhangar search N757AF\nhangar sql \"SELECT COUNT(*) FROM aircraft\"\n```\n\n## What this does\n\nHangarbay downloads FAA aircraft registration data, normalizes it into typed tables and provides fast SQL querying:\n\n- **307K+ aircraft registrations** with owner and address information\n- **93K+ make/model references** (Cessna, Piper, Boeing, etc.)\n- **4,700+ engine specifications** (horsepower, type, manufacturer)\n- **DuckDB** for analytical SQL queries (sub-second on 300K+ rows)\n- **SQLite FTS5** for full-text search by owner name or address\n- **Parquet** files for efficient columnar storage\n- **Data lineage tracking** with SHA256 checksums and version metadata\n- **Shared data directory** at `~/.hangarbay/data/` - works from any project or notebook\n\n## Features\n\n### N-Number lookup\nLook up any aircraft registration with decoded status codes and human-readable output:\n\n```bash\nhangar search N221LA\n```\n\n```\nAircraft Registration: N221LA\n\nOwner: LAPD AIR SUPPORT DIVISION\nAddress: 555 RAMIREZ ST SPC 475\nLocation: LOS ANGELES, CA 90012\n\n  Make \u0026 Model:           AIRBUS HELICOPTERS INC AS350B3\n  Year Manufactured:      2014\n  Serial Number:          7900\n  Registration Status:    Valid\n  Certificate Type:       Standard Airworthiness - Normal\n  Certificate Issue:      Jun 15, 2015\n  Status Date:            May 19, 2023\n  Expiration:             Jun 30, 2028\n  Mode S Code:            A1E5B3\n```\n\n### Fleet search\nFind all aircraft owned by a person or company:\n\n```bash\n# Search by owner name (case-insensitive)\nhangar fleet \"United Airlines\"\nhangar fleet \"LAPD\"\nhangar fleet \"NetJets\"\n\n# OR logic with pipe separator (great for finding multiple airlines)\nhangar fleet \"LAPD|Los Angeles Police\"     # Either pattern matches\nhangar fleet \"Delta|American|United\"       # Any of the three\n\n# Filter by state\nhangar fleet \"Delta\" --state GA\n\n# Export to CSV\nhangar fleet \"Boeing\" --export boeing_fleet.csv\n\n# Limit results\nhangar fleet \"Cessna\" --limit 20\n```\n\n### SQL queries\nExecute analytical queries with pretty output:\n\n```bash\n# Total aircraft\nhangar sql \"SELECT COUNT(*) FROM aircraft\"\n\n# Use decoded views for readable output\nhangar sql \"SELECT * FROM aircraft_decoded WHERE year_mfr \u003e 2020 LIMIT 10\"\nhangar sql \"SELECT * FROM owners_clean WHERE owner_name LIKE '%boeing%'\" -i\n\n# Top manufacturers\nhangar sql \"SELECT maker, COUNT(*) as count FROM aircraft \n  JOIN aircraft_make_model USING(mfr_mdl_code) \n  WHERE maker != '' GROUP BY 1 ORDER BY 2 DESC LIMIT 10\"\n\n# Lookup status codes\nhangar sql \"SELECT * FROM status_codes\"\n\n# Top states by registrations\nhangar sql \"SELECT state_std, COUNT(*) as count FROM owners \n  WHERE state_std != '' GROUP BY 1 ORDER BY 2 DESC LIMIT 10\"\n```\n\n**Output Formats:**\n\n```bash\n# Pretty table (default)\nhangar sql \"SELECT * FROM status_codes LIMIT 3\"\n\n# JSON output (for APIs/scripts)\nhangar sql \"SELECT * FROM status_codes LIMIT 3\" --output-format json\n\n# CSV output (for Excel/spreadsheets)\nhangar sql \"SELECT * FROM status_codes LIMIT 3\" --output-format csv\n```\n\n### Available tables\n\n**Core Tables:**\n- **aircraft** - Current registration facts (N-number, serial, make/model, year, status)\n- **registrations** - Canonical registration state (type, status, dates)\n- **owners** - Owner records with raw and standardized addresses\n- **owners_summary** - Aggregated ownership (co-owners, counts)\n- **aircraft_make_model** - Make/model reference (Cessna 172, Boeing 737, etc.)\n- **engines** - Engine specifications (manufacturer, horsepower, type)\n\n**Decoded Views (Recommended):**\n- **aircraft_decoded** - Aircraft with decoded status codes and joined make/model\n- **owners_clean** - Simplified owner table (standardized fields only, decoded owner type)\n\n**Reference Tables:**\n- **status_codes** - Registration status code lookups\n- **airworthiness_classes** - Airworthiness certificate class lookups  \n- **owner_types** - Owner type code lookups\n\n## Data quality\n\n- **Type safety**: PyArrow schemas enforce correct data types (dates, integers, strings)\n- **Address standardization**: Uppercase, state/ZIP normalization, whitespace cleanup\n- **Deterministic IDs**: xxhash64 ensures consistent owner IDs across pipeline runs\n- **File verification**: SHA256 checksums validate all downloads\n- **Version tracking**: Manifest records schema versions and row counts for each snapshot\n\n## Architecture\n\n```\nFAA Data (MASTER, ACFTREF, ENGINE)\n    ↓ fetch (with SHA256 verification)\nRaw Text Files (275 MB)\n    ↓ normalize (PyArrow type casting)\nTyped Parquet Tables (36 MB)\n    ↓ publish (indexing)\nDuckDB (106 MB) + SQLite FTS (55 MB)\n    ↓ query\nCLI / Python API\n```\n\n## Development\n\nTo contribute or modify the code:\n\n```bash\n# Clone and install for development\ngit clone https://github.com/stiles/hangarbay.git\ncd hangarbay\npip install -e \".[dev]\"\n\n# Run tests\nmake test\n\n# Update data\nmake update       # or: hangar update\n\n# Check data status\nmake status       # or: hangar status\n\n# Full pipeline (individual steps)\nmake all          # fetch, normalize, publish, verify\n\n# Individual steps\nmake fetch\nmake normalize\nmake publish\n\n# Clean intermediate files\nmake clean\n```\n\n## License\n\nMIT\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstiles%2Fhangarbay","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstiles%2Fhangarbay","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstiles%2Fhangarbay/lists"}