seats-aero

# Seats.aero Award Flight Search

Search award flight availability across 24 mileage programs using the seats.aero partner API.

## Setup

Before searching, you need a seats.aero API key:

1. If the user hasn't provided an API key, prompt them:
   - "Please provide your seats.aero API key. You can get one at https://seats.aero/partner"
2. Store the key in conversation context for subsequent requests
3. All requests require the header: `Partner-Authorization: Bearer {api_key}`

## Core Capabilities

### 1. Search Routes (`/search`)
Search cached availability across all mileage programs for a specific origin-destination pair.

### 2. Bulk Availability (`/availability`)
Explore all availability from a single mileage program, optionally filtered by region.

### 3. Route Discovery (`/routes`)
Get all routes monitored for a specific mileage program.

### 4. Trip Details (`/trips/{id}`)
Get detailed flight segments and booking links for a specific availability.

## Quick Reference

| Item | Value |
|------|-------|
| Base URL | `https://seats.aero/partnerapi/` |
| Auth Header | `Partner-Authorization: Bearer {key}` |
| Date Format | `YYYY-MM-DD` |

### Cabin Codes
- `Y` = Economy
- `W` = Premium Economy
- `J` = Business
- `F` = First

### Regions
North America, South America, Europe, Africa, Middle East, Asia, Oceania

## Supported Programs

```
aeroplan, alaska, american, aeromexico, azul, copa, delta, emirates,
ethiopian, etihad, finnair, flyingblue, gol, jetblue, lufthansa,
qantas, qatar, sas, saudia, singapore, turkish, united,
virginatlantic, virginaustralia
```

## Common Workflows

### Find availability on a specific route
**User**: "Find business class SFO to Tokyo next month"

1. Use `/search` endpoint with:
   - `origin_airport=SFO`
   - `destination_airport=NRT,HND` (both Tokyo airports)
   - `cabin=J`
   - `start_date` and `end_date` for the date range

### Explore program availability
**User**: "What United awards are available from Europe?"

1. Use `/availability` endpoint with:
   - `source=united`
   - `origin_region=Europe`

### Get booking details
**User**: "Show me details for that flight"

1. Use `/trips/{id}` with the availability ID from previous search
2. Response includes flight segments, times, and booking links

### Check what routes a program covers
**User**: "What routes does Aeroplan monitor?"

1. Use `/routes` endpoint with `source=aeroplan`

## API Parameters Quick Guide

### /search
| Parameter | Required | Description |
|-----------|----------|-------------|
| origin_airport | Yes | 3-letter IATA code |
| destination_airport | Yes | 3-letter IATA code(s), comma-separated |
| cabin | No | Y, W, J, or F (comma-separated for multiple) |
| start_date | No | YYYY-MM-DD |
| end_date | No | YYYY-MM-DD |
| sources | No | Program name(s), comma-separated |
| only_direct | No | true/false |
| take | No | Results per page (default 100) |
| cursor | No | Pagination cursor |

### /availability
| Parameter | Required | Description |
|-----------|----------|-------------|
| source | Yes | Single program name |
| cabin | No | Single cabin code |
| origin_region | No | Filter by origin region |
| destination_region | No | Filter by destination region |
| start_date | No | YYYY-MM-DD |
| end_date | No | YYYY-MM-DD |
| take | No | Results per page |

## Script Usage

For complex or repeated searches, use the Python helper:

```python
from scripts.seats_api import search_availability, format_results

results = search_availability(
    api_key="your_key",
    origin="SFO",
    destination="NRT",
    start_date="2024-03-01",
    end_date="2024-03-31",
    cabins="J,F"
)
print(format_results(results["data"], cabin="J"))
```

See `scripts/seats_api.py` for full API client implementation.

## Response Handling

### Availability Object Fields
- `ID` - Use for `/trips/{id}` lookup
- `Route` - Origin-Destination pair
- `Date` - Flight date
- `YAvailable`, `WAvailable`, `JAvailable`, `FAvailable` - Boolean availability
- `YMileageCost`, etc. - Points required per cabin
- `YDirects`, etc. - Number of direct flights available
- `Source` - Program name
- `ComputedLastSeen` - Data freshness timestamp

### Error Handling
- 401: Invalid or missing API key
- 429: Rate limited, wait and retry
- 404: No results or invalid availability ID

## Tips

1. **Date ranges**: Keep to 30-60 days for faster results
2. **Multiple cabins**: Search J,F together for premium options
3. **Direct flights**: Use `only_direct=true` to filter connections
4. **Pagination**: Use `cursor` from response for more results
5. **Data freshness**: Check `ComputedLastSeen` - older data may be stale

## Reference Documentation

For complete API specification including all fields and response schemas, see `references/api-spec.md`.