Lightweight, self-hosted API for FAA aircraft registration lookup by N-number.

Database baked into image—just pull and run.

docker run -d -p 8182:8080 ryakel/tail-lookup:latest

Open http://localhost:8182 for the web UI, or use the API directly:

curl http://localhost:8182/api/v1/aircraft/N172SP

• 🔍 Single and bulk lookups (up to 50 at once)
• 🌐 Simple web UI for testing
• 📦 ~25MB SQLite database with ~300k aircraft
• 🔄 Nightly automated updates via GitHub Actions
• 🐳 Zero-config Docker deployment

curl http://localhost:8182/api/v1/aircraft/N172SP

{
  "tail_number": "N172SP",
  "manufacturer": "CESSNA",
  "model": "172S",
  "series": "SKYHAWK SP",
  "aircraft_type": "Fixed Wing Single-Engine",
  "engine_type": "Reciprocating",
  "num_engines": 1,
  "num_seats": 4,
  "year_mfr": 2001
}

All formats accepted: N172SP, 172SP, N-172SP, n172sp

curl -X POST http://localhost:8182/api/v1/aircraft/bulk \
  -H "Content-Type: application/json" \
  -d '{"tail_numbers": ["N172SP", "N12345", "N99999"]}'

{
  "total": 3,
  "found": 2,
  "results": [
    {
      "tail_number": "N172SP",
      "manufacturer": "CESSNA",
      "model": "172S",
      ...
    },
    {
      "tail_number": "N12345",
      "manufacturer": "PIPER",
      ...
    },
    {
      "tail_number": "N99999",
      "error": "Not found"
    }
  ]
}

New images built daily at 6 AM UTC with fresh FAA data.

version: "3.8"

services:
  flight-budget:
    image: ryakel/flight-budget:latest
    ports:
      - "8181:80"

  tail-lookup:
    image: ryakel/tail-lookup:latest
    ports:
      - "8182:8080"

For comprehensive documentation, see the GitHub Wiki:

• Architecture Overview - System design and data flow
• Database Design - Schema, FAA data format, optimization
• API Documentation - Complete API reference with examples
• Deployment Guide - Docker, Kubernetes, cloud platforms
• CI/CD Pipeline - Workflow documentation and secrets
• Development Guide - Local setup and contribution guidelines
• Troubleshooting - Common issues and solutions

# Clone
git clone https://github.com/ryakel/tail-lookup.git
cd tail-lookup

# Build database locally
python scripts/update_faa_data.py data/aircraft.db

# Run
pip install -r requirements.txt
DB_PATH=data/aircraft.db uvicorn app.main:app --reload --port 8080

See the Development Guide for complete setup instructions.

Aircraft data from FAA Releasable Aircraft Database, updated daily at 11:30 PM CT.

This project is licensed under the MIT License - see the LICENSE file for details.

• Inspired by Aircraft-Registration-Lookup-API
• Data: FAA Aircraft Registry