flight-tracker

实时跟踪航班的详细状态、登机口信息、延误和实时位置。当用户要求跟踪航班、检查航班状态、按航班号查找航班信息（例如，“跟踪 AA100”、“United 2402 的状态如何”、“检查我的航班 BA123”）或想要以类似于 Flighty 应用程序的格式化视图显示航班数据时使用。

# 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` flag

## Flight Number Formats

Accept IATA flight codes:
- AA100 (American Airlines)
- UA2402 (United)
- BA123 (British Airways)
- DL456 (Delta)

The script automatically converts to uppercase and handles the lookup.

## Error Handling

The script handles common errors:
- Missing API key → Shows setup instructions
- Flight not found → Suggests verification
- API errors → Displays error message
- Rate limit exceeded → Indicates limit reached

## API Limits

Free tier: 100 requests/month. Track usage to stay within limits. For heavy usage, consider upgrading or alternative APIs (see references/api-setup.md).

## Notes

- Uses AviationStack free tier (no HTTPS on free plan)
- Real-time data updated frequently
- Historical flight data available
- Worldwide coverage (250+ countries, 13,000+ airlines)

---

## 中文说明

# 航班追踪器

使用 AviationStack API 追踪全球任意航班，并以简洁的 Flighty 风格格式显示。

## 快速开始

通过 IATA 代码追踪航班：

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

## 首次设置

在使用此技能之前，你需要一个 API 密钥（一次性设置）：

1. **获取免费 API 密钥**，地址为 https://aviationstack.com/signup/free（每月 100 次请求）
2. **设置环境变量：**
   ```bash
   export AVIATIONSTACK_API_KEY='your-key-here'
   ```
3. **安装依赖：**
   ```bash
   pip3 install requests
   ```

有关详细的设置说明，请参阅 [api-setup.md](references/api-setup.md)。

## 输出格式

此技能以简洁、易读的格式显示航班信息，包括：

- ✈️ 航空公司和航班号
- 🛩️ 机型和注册号
- 🛫 出发机场、航站楼、登机口、时间
- 🛬 到达机场、航站楼、登机口、时间
- 📊 带可视化指示器的航班状态
- ⏱️ 延误计算（如适用）
- 🌐 实时位置、高度、速度（飞行中时）

状态指示器：
- 🟢 进行中／飞行中／航行途中
- ✅ 已降落／已到达
- 🟡 已排定
- 🟠 已延误
- 🔴 已取消

## 高级用法

**获取原始 JSON 数据：**
```bash
scripts/track_flight.py AA100 --json
```

**查看帮助：**
```bash
scripts/track_flight.py --help
```

## 工作流程

当用户要求追踪航班时：

1. 从请求中提取航班号
2. 使用航班号运行追踪脚本
3. 向用户呈现格式化的输出
4. 如果需要数据进行进一步处理，请使用 `--json` 标志

## 航班号格式

接受 IATA 航班代码：
- AA100（美国航空）
- UA2402（联合航空）
- BA123（英国航空）
- DL456（达美航空）

脚本会自动转换为大写并处理查询。

## 错误处理

脚本处理常见错误：
- 缺少 API 密钥 → 显示设置说明
- 未找到航班 → 建议核实
- API 错误 → 显示错误消息
- 超出速率限制 → 提示已达到限制

## API 限制

免费套餐：每月 100 次请求。追踪使用量以保持在限制范围内。对于大量使用，请考虑升级或使用替代 API（参见 references/api-setup.md）。

## 备注

- 使用 AviationStack 免费套餐（免费计划不支持 HTTPS）
- 实时数据频繁更新
- 提供历史航班数据
- 覆盖全球（250+ 个国家，13,000+ 家航空公司）