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-aerodirectly) - 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,HNDfor 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: Uselowest_mileageto get cheapest first.take: Set to1000to 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:
- Freshness warning: "Data from seats.aero cached search. Last seen times vary. Verify before transferring points."
- Transfer advice: "Don't transfer until you've confirmed the specific flight exists on the airline's website."
- Cash comparison: If a cash price was fetched (from Duffel/Ignav), show the CPP for context.
- Booking links: For the top 3 dates, mention how to book (e.g., "Book via Virgin Atlantic website, call to hold").
- 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:
- Widening the airport search (add nearby airports)
- Checking a different month
- Looking at different cabins
- 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
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.
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.
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.
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.
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.
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.