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:

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.