award-calendar

Award Calendar

"When should I fly SFO to NRT on points?" answered with a calendar view.

Searches seats.aero across a date range and presents a grid showing the cheapest award per day, per cabin. Highlights the best dates to fly.

This is an orchestration skill. It tells the agent how to query seats.aero and format the results. No standalone script.

When to Use

• "When's the cheapest time to fly SFO to NRT in business on points?"
• "Show me award availability for SFO-CDG in September"
• "I'm flexible on dates. When should I fly?"
• Any award search where dates are flexible

When NOT to Use

• Specific date search (use seats-aero directly)
• Cash price calendar (use Google Flights "Date grid" or Skiplagged)
• Hotel date flexibility (not supported here)

Workflow

Step 1: Search the Date Range

Use the seats.aero cached search API with a date range. The API supports up to ~60 days per query.

curl -s -H "Partner-Authorization: $SEATS_AERO_API_KEY" \
  "https://seats.aero/partnerapi/search?origin_airport={ORIGIN}&destination_airport={DEST}&start_date={START}&end_date={END}&cabin={CABIN}"

Parameters:

• origin_airport: Can be comma-delimited for nearby airports (e.g., SFO,SJC,OAK)
• destination_airport: Same. Use multiple for metro areas (e.g., NRT,HND for Tokyo)
• start_date, end_date: YYYY-MM-DD. Keep range under 60 days for best results.
• cabin: Optional filter. economy, premium, business, first. Omit for all cabins.
• order_by: Use lowest_mileage to get cheapest first.
• take: Set to 1000 to get all results in one page.

For ranges over 60 days, split into two queries and combine results.

Step 2: Group by Date

Process the API response:

For each availability object:
  date = result.Date
  cabin = which cabin(s) are available (Y/W/J/F)
  For each available cabin:
    cost = result.{cabin}MileageCost
    program = result.Source
    Track: cheapest cost per date per cabin across all programs