AGENT SKILL

award-calendar

Find the cheapest award dates for a route over a date range. Searches seats.aero across all programs, groups by date, and shows a calendar grid of the best deals. Use when dates are flexible and you want to find the sweet spot.

License 许可
MIT
最近更新
2026-11-09
Stars
★ 978
Forks
120

01 前言 Front Matter

name
award-calendar
api_key
Seats.aero Pro
summary
Cheapest award dates for a route across a date range. Calendar grid view.
category
orchestration
description
Find the cheapest award dates for a route over a date range. Searches seats.aero across all programs, groups by date, and shows a calendar grid of the best deals. Use when dates are flexible and you want to find the sweet spot.

03 SKILL.md 正文

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

Step 3: Apply Transfer Partner Optimization

For each cheapest-per-date result, calculate the effective cost in transferable currencies using data/transfer-partners.json:

For date 2026-09-05, cheapest business = 55,000 via Flying Blue:
  Chase UR: 55,000 / 1.0 = 55,000 UR
  Amex MR: 55,000 / 1.0 = 55,000 MR
  Bilt: 55,000 / 1.0 = 55,000 Bilt

Step 4: Present Calendar Grid

Always use markdown tables. One table per cabin class requested.

Business Class: SFO → NRT, September 2026

Date Program Miles Best Currency Points CPP* Seats Direct
Sep 3 ⭐ Virgin Atlantic 52,500 Chase UR 52,500 8.0 2 ✅ ANA
Sep 5 Flying Blue 55,000 Any 1:1 55,000 7.6 4 ✅ AF
Sep 7 Aeroplan 70,000 Chase UR 70,000 6.0 1 ✅ ANA
Sep 8 United 88,000 Chase UR 88,000 4.8 3 ✅ UA
Sep 10 — — — — — — ❌ No availability
Sep 12 Aeroplan 75,000 Amex MR 75,000 5.6 2 ❌ 1-stop
... ... ... ... ... ... ... ...

*CPP calculated against cheapest cash fare from Duffel/Ignav if available, otherwise estimated.

⭐ = Best deal of the month

Summary:

  • Best date: Sep 3 via Virgin Atlantic → ANA at 52,500 miles (8.0 cpp)
  • Runner-up: Sep 5 via Flying Blue at 55,000 miles
  • Worst week: Sep 10-14 (no business availability most days)
  • Cheapest economy: Sep 12 at 25,000 United miles

Step 5: Additional Context

After the grid, include:

  1. Freshness warning: "Data from seats.aero cached search. Last seen times vary. Verify before transferring points."
  2. Transfer advice: "Don't transfer until you've confirmed the specific flight exists on the airline's website."
  3. Cash comparison: If a cash price was fetched (from Duffel/Ignav), show the CPP for context.
  4. Booking links: For the top 3 dates, mention how to book (e.g., "Book via Virgin Atlantic website, call to hold").
  5. Release date note: If searching far out, mention which airlines may not have released space yet (use seats.aero release date tool).

Error Handling

NEVER fail silently.

- ❌ Seats.aero: API error (rate limit). Try again in a few minutes.
- ⚠️ Seats.aero: Only 12 results for 30-day range. Some dates may have uncached availability. Try live search for specific dates of interest.
- ℹ️ No business availability found for any date. Showing economy and premium economy instead.

If zero results come back for the entire range, say so explicitly and suggest:

  1. Widening the airport search (add nearby airports)
  2. Checking a different month
  3. Looking at different cabins
  4. Using the seats.aero live search for specific dates (local Patchright only)

Limitations

  • Cached data only. Results may be 1-48 hours old. Live search (via seats-aero-web) is more current but Bobby-local only.
  • 60-day query limit. Split longer ranges into multiple queries.
  • No round-trip optimization. Shows one-way availability. For round-trip, run two calendar searches (outbound and return).
  • No cash price calendar. This is award-only. For cash date flexibility, use Google Flights "Date grid" view.
  • Phantom availability. Some results may not actually be bookable. Always verify.

04 同仓库更多 Skills

borski
borski/travel-hacking-toolkit

wikipedia-airports

Discover destinations served from any airport via Wikipedia. Sanity-check whether an airline flies a specific route, find regional service that fare tools miss, identify late-split-return airport options.

★ 978
borski
borski/travel-hacking-toolkit

wheretocredit

Mileage earning rates by airline and booking class via wheretocredit.com. Redeemable and qualifying miles across 50+ programs. Use when deciding where to credit a flight or comparing earning rates.

★ 978
borski
borski/travel-hacking-toolkit

vrbo

Search VRBO (Vrbo / Expedia Group) vacation rentals including entire homes, condos, and cabins via Patchright browser automation. VRBO sits behind Akamai Bot Manager so plain HTTP and standard Playwright get a 429 bot wall. Use for whole-home or group stays, multi-bedroom rentals, and Airbnb-vs-VRBO comparisons. Trigger phrases include search VRBO, Vrbo rentals, vacation rental, cabin rental, whole house, condo for the group.

★ 978
borski
borski/travel-hacking-toolkit

tripadvisor

TripAdvisor Content API for hotel ratings, restaurant search, attraction reviews, rankings, and nearby locations. Use when evaluating hotels or researching destinations. 5K calls/month.

★ 978
borski
borski/travel-hacking-toolkit

trip-planner

Full trip planning orchestration. Combines flight search, hotel search, and points optimization into one cost analysis. Use when the user says "plan a trip" or wants the complete picture for a destination.

★ 978
borski
borski/travel-hacking-toolkit

trip-log

Save flight searches, itineraries, and booked trips to the trips/logs/ directory for future reference. OPT-IN — use when the user asks to log a trip or look up past searches, or on every search only if the user has said they want automatic logging. Also use to update status when a trip is booked or completed.

★ 978