← Back to Transportation
Transportation by @jarrodjs

seats-aero

Search award flight availability via seats.aero API

0
Source Code

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:
  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.