aviationstack-flight-tracker

---
name: flight-tracker
version: 1.0.0
description: Track flights in real-time with detailed status, gate info, delays, and live position. Use when user asks to track a flight, check flight status, look up flight information by flight number (e.g., "track AA100", "what's the status of United 2402", "check my flight BA123"), or wants to display flight data in a formatted view similar to Flighty app.
---

# Flight Tracker

Track any flight worldwide using AviationStack API and display in a clean, Flighty-style format.

## Quick Start

Track a flight by its IATA code:

```bash
scripts/track_flight.py AA100
scripts/track_flight.py UA2402
scripts/track_flight.py BA123
```

## First-Time Setup

Before using this skill, you need an API key (one-time setup):

1. **Get a free API key** at https://aviationstack.com/signup/free (100 requests/month)
2. **Set environment variable:**
   ```bash
   export AVIATIONSTACK_API_KEY='your-key-here'
   ```
3. **Install dependencies:**
   ```bash
   pip3 install requests
   ```

For detailed setup instructions, see [api-setup.md](references/api-setup.md).

## Output Format

The skill displays flight information in a clean, readable format with:

- ✈️ Airline and flight number
- 🛩️ Aircraft type and registration
- 🛫 Departure airport, terminal, gate, times
- 🛬 Arrival airport, terminal, gate, times
- 📊 Flight status with visual indicators
- ⏱️ Delay calculations (if applicable)
- 🌐 Live position, altitude, speed (when airborne)

Status indicators:
- 🟢 Active/Airborne/En-route
- ✅ Landed/Arrived
- 🟡 Scheduled
- 🟠 Delayed
- 🔴 Cancelled

## Advanced Usage

**Get raw JSON data:**
```bash
scripts/track_flight.py AA100 --json
```

**Check help:**
```bash
scripts/track_flight.py --help
```

## Workflow

When a user asks to track a flight:

1. Extract the flight number from the request
2. Run the tracking script with the flight number
3. Present the formatted output to the user
4. If data is needed for further processing, use `--json` fl