Aerobase Flight Deals 💰

Deal Search

GET /api/v1/deals — Query parameters:

Param	Type	Description
origin	string	Departure IATA code (e.g., "JFK")
destination	string	Destination IATA code (e.g., "CDG")
max_price	number	Maximum price in USD
min_score	number	Minimum jetlag score (0-100)
max_recovery_days	number	Maximum recovery days
date_from	string	Travel date from (YYYY-MM-DD)
date_to	string	Travel date to (YYYY-MM-DD)
cabin	string	cabin class (economy, premium_economy, business, first)
sort	string	Sort by: value_score, price, jetlag_score, newest
limit	number	Max results (up to 50, free tier: 3)

Example: /api/v1/deals?origin=JFK&destination=CDG&max_price=500&min_score=60&sort=jetlag_score

Returns up to 50 results (3 for free tier).

Price Monitoring (cron: every 6 hours)

For each saved route in user's watchlist:

1. Search current price via POST /api/flights/search/agent
2. Compare against baseline (stored in trip metadata)
3. Price dropped >10%: alert immediately with jetlag context
4. Price increased >20%: alert (lock in now?)
5. Screenshot price via browser for proof (optional)

"YVR to Lisbon dropped to $480 roundtrip. Jetlag score 4.1 — moderate, 2-3 days recovery. Your calendar shows nothing critical the week of March 15. Want me to hold this?"

Google Flights Comparison (browser fallback)

Only when user explicitly asks. Open google.com/travel/flights, snapshot results, extract prices. Present alongside API results — recommend booking through our API for tracking benefits.

Max 1 price alert per route per day. Screenshot proof for every browser price.

Rate Limits

• Deal search: max 30/hr. Price monitoring cron: every 6 hours (do not increase).
• Browser price checks: max 10/day total (shared with aerobase-browser).

Data Sources — Flight Deals

Primary: Aerobase Deals API (FREE, always query first)

• Internal deals API with curated flight deals
• Query by origin, destination, price range, dates
• Returns structured data: route, price, airline, dates, booking link
• Always the first source — fastest, most reliable, no bot detection
• Includes deals from: SecretFlying, TheFlightDeal, TravelPirates, Going.com
• These sources are scraped periodically and stored in our database

Secondary: Browser (verification & discovery)

Use browser ONLY for:

• Verifying a deal is still live ("Is that $299 JFK-NRT deal still available?")
• Finding deals not yet in our API (new posts on deal sites)
• Cross-referencing deal prices against Google Flights actual availability
• User specifically asks "check SecretFlying" or "what's on TravelPirates"

Workflow

1. User asks "Any deals from NYC to Tokyo?"
2. IMMEDIATELY query Aerobase Deals API
3. Show results: "I found 3 deals from our database..."
4. If user wants more: "Let me also check Google Flights for current pricing..."
5. Browser → Google Flights to verify deal prices are real and bookable
6. Combine: "The $349 deal from our database is confirmed — Google Flights shows $352 for the same dates"

Scrapling — Deal Discovery & Verification (Reference: Scrapling Docs)

Use Scrapling /search for structured deal extraction (no browser snapshot needed):

SecretFlying deals:

POST {SCRAPLING_URL}/search
{"site":"secretflying"}

Returns: {"results": [{"title":"..","url":".."}], "count": 16}

TheFlightDeal deals:

POST {SCRAPLING_URL}/search
{"site":"theflightdeal"}

Returns: {"results": [{"title":"..","url":".."}], "count": 18}

Google Flights price verification:

POST {SCRAPLING_URL}/search
{"site":"google-flights","origin":"JFK","destination":"NRT","departure":"2026-03-15","return":"2026-03-22"}

TravelPirates (JS-rendered, use /fetch with screenshot):

web_fetch {SCRAPLING_URL}/fetch?url=https://www.travelpirates.com/&json=1&screenshot=1

Page loads (741KB HTML) but deals are JS-rendered — screenshot required for visual extraction.

Going.com deals (scrapling tier, no proxy):

web_fetch {SCRAPLING_URL}/fetch?url=https://www.going.com/deals&json=1&extract=css&selector=article

Returns deal articles. Going (formerly Scott's Cheap Flights) publishes curated deals.

Workflow with Scrapling

1. Query Aerobase Deals API immediately
2. Fire Scrapling /search for SecretFlying + TheFlightDeal in parallel
3. Show API results first
4. Merge: "I also found 16 deals on SecretFlying..."
5. For price verification: Scrapling Google Flights search

When to SKIP browser entirely

• User asks "any deals to Europe?" → Deals API only, plenty of data
• User asks about a deal they saw in our app → API lookup by ID
• General deal browsing → API is comprehensive enough
• Only use browser for verification, freshness check, or explicit user request

UI Rendering

When displaying deal results, use the DealCard json-render component:

{
  "root": "deal-1",
  "elements": {
    "deal-1": {
      "type": "DealCard",
      "props": {
        "title": "Paris in March - $450 roundtrip",
        "price": "450",
        "currency": "$",
        "origin": "JFK",
        "originCity": "New York",
        "destination": "CDG",
        "destinationCity": "Paris",
        "travelDates": "Mar 15 - Mar 22",
        "cabin": "economy",
        "jetlagScore": 65,
        "recoveryDays": 3,
        "jetlagRecommendation": "good",
        "valueScore": 85,
        "sourceUrl": "https://...",
        "slug": "paris-march-450",
        "dealId": "uuid-here"
      }
    }
  }
}

The DealCard shows:

• Title, price, cabin class
• Origin → Destination with city names
• Travel dates
• Jetlag score with tier badge
• Recovery days
• Value score
• "View Details" button → opens full deal sheet

Filter Examples

"Show me business class deals under $1000 with good jetlag scores":

GET /api/v1/deals?cabin=business&max_price=1000&min_score=60&sort=jetlag_score

"Deals to Europe in March from NYC":

GET /api/v1/deals?origin=JFK&destination=CDG&date_from=2026-03-01&date_to=2026-03-31&sort=value_score

For UI rendering of all card types (HotelCard, TourCard, AttractionCard, LayoverGuideCard, etc.), see aerobase-ui SKILL for component specs and json-render format.