---

name: aerobase-travel-pro description: Full jetlag intelligence suite with award search, comparison, recovery plans, and itinerary analysis version: 1.0.0 author: Aerobase tier: pro api_base: https://aerobase.app/api

Aerobase Travel Intelligence Pro

You have access to the full Aerobase travel API. This includes everything in the free tier plus award flight search, side-by-side comparison, personalized recovery plans, itinerary analysis, and flight lookup.

Setup

export AEROBASE_API_KEY="ak_..."

All requests use https://aerobase.app/api as the base URL.

Response Envelope

Every response wraps data in a standard envelope:

{
  "data": { ... },
  "meta": {
    "request_id": "req_abc123",
    "tier": "pro",
    "calls_remaining": 38,
    "latency_ms": 142
  }
}

Errors return:

{
  "error": { "code": "VALIDATION_ERROR", "message": "..." },
  "meta": { "request_id": "...", "tier": "pro", "calls_remaining": 41, "latency_ms": 12 }
}

Rate Limits

Pro tier: 42 requests per hour. Monitor calls_remaining in response meta.

---

Tools 1-5: Core (Free Tier)

1. Score a Flight

Score a specific flight for jetlag impact given exact departure and arrival times.

curl -s -X POST "https://aerobase.app/api/v1/flights/score" \
  -H "Authorization: Bearer $AEROBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "LAX",
    "to": "NRT",
    "departure": "2026-04-15T13:25:00-07:00",
    "arrival": "2026-04-16T15:40:00+09:00",
    "cabin": "economy"
  }'

Required: from, to (3-letter IATA), departure, arrival (ISO 8601 with tz offset). Optional: cabin (economy | business | first | premium_economy).

Response data: score (0-100), tier, recovery_days, direction, timezone_shift_hours, breakdown, insight, strategies (departure, arrival, shift, recovery), tips[], origin, destination.

Present: "This flight scores X/100 (tier). ~Y days recovery. [strategy summary]"

---

2. Search Flights

Search flights on a route ranked by jetlag score. Pro tier returns up to 50 results.

curl -s -X POST "https://aerobase.app/api/v1/flights/search" \
  -H "Authorization: Bearer $AEROBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "SFO",
    "to": "LHR",
    "date": "2026-05-20",
    "max_stops": 1,
    "sort": "jetlag",
    "limit": 10
  }'

Required: from, to, date (YYYY-MM-DD). Optional: return_date, max_stops (default 2), sort (jetlag | price | duration), limit (max 50).

Response: Array of flights with id, price, duration_minutes, stops, jetlag_score (0-100), tier, recovery_days, direction, booking_url, segments[], source.

---

3. Airport Info

Airport details with jetlag facilities, lounges, and ground transit.

curl -s "https://aerobase.app/api/v1/airports/NRT" \
  -H "Authorization: Bearer $AEROBASE_API_KEY"

Response: code, name, city, country, timezone, latitude, longitude, facilities[], lounges[], transit[].

---

4. Route Intelligence

Comprehensive route analysis with direct and connecting options.

curl -s "https://aerobase.app/api/v1/routes/LAX/NRT" \
  -H "Authorization: Bearer $AEROBASE_API_KEY"

Response: origin, destination, timezone_shift (hours, direction, offsets), direct_routes[], connecting_routes[], route_count. Each route has jetlag_score, stops, connections, total_distance_km, recovery_days, segments[].

---

5. Travel Deals

Jetlag-scored travel deals. Pro tier returns up to 50 results.

curl -s "https://aerobase.app/api/v1/deals?departure=LAX&sort=value_score&limit=20" \
  -H "Authorization: Bearer $AEROBASE_API_KEY"

Params: departure, destination, max_price, sort (value_score | price | jetlag_score | newest), limit.

Response: deals[] with title, price_usd, cabin_class, is_error_fare, origin, destination, jetlag (score, recovery_days, direction, recommendation), value_score, travel_dates, booking_deadline, source_url.

---

Tools 6-10: Pro Exclusive

6. Award Search

Search award flight availability across 24 loyalty programs with jetlag scoring.

curl -s -X POST "https://aerobase.app/api/v1/awards/search" \
  -H "Authorization: Bearer $AEROBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "SFO",
    "to": "NRT",
    "cabin": "business",
    "date_from": "2026-06-01",
    "date_to": "2026-06-15",
    "limit": 20
  }'

Required: from, to (IATA). Optional: cabin (economy | business | premium | first), date (single date), date_from/date_to (range), limit (max 100).

Response data is an array:

Field	Type	Description
origin	string	Origin IATA
destination	string	Destination IATA
date	string	Travel date
cabin	string	Cabin class
miles	number	Miles/points cost
seats_remaining	number/null	Seats available
program	string	Loyalty program (e.g., "united", "aeroplan")
jetlag_score_k2	number/null	K2 score 0-100 (higher = better)
departure_time	string/null	Local departure time
arrival_time	string/null	Local arrival time

Present to user: Rank by jetlag_score_k2. Mention miles cost, program, and available seats. "ANA business via United MileagePlus: 88,000 miles, scores 76/100 for jetlag with 2 seats left."

---

7. Flight Compare

Compare 2-10 flights side by side with a recommendation.

curl -s -X POST "https://aerobase.app/api/v1/flights/compare" \
  -H "Authorization: Bearer $AEROBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "flights": [
      {
        "from": "SFO",
        "to": "LHR",
        "departure": "2026-05-20T16:30:00-07:00",
        "arrival": "2026-05-21T10:45:00+01:00",
        "cabin": "economy",
        "label": "United afternoon"
      },
      {
        "from": "SFO",
        "to": "LHR",
        "departure": "2026-05-20T21:15:00-07:00",
        "arrival": "2026-05-21T15:10:00+01:00",
        "cabin": "economy",
        "label": "BA red-eye"
      }
    ]
  }'

Required: flights array (2-10 items). Each flight needs from, to, departure, arrival. Optional per flight: cabin, label.

Response data:

Field	Type	Description
flights	array	Scored flights with full breakdown and per-flight strategies
recommendation.pick	number	Index of best option
recommendation.label	string	Label of recommended flight
recommendation.reason	string	Explanation of why it wins
deltas.score_range	number	Score spread across options
deltas.recovery_range	number	Recovery days spread
deltas.duration_range	number	Duration spread in minutes

Each flight in the array includes: score (composite, tier, recovery_days, direction, breakdown), explanation (summary, departure_strategy, arrival_strategy, shift_approach, recovery_estimate, tips[]).

Present to user: Lead with the recommendation. Show a comparison table. Highlight the key differentiator (arrival time, duration, recovery). "I recommend [label] - it scores X vs Y, saving you ~Z days of recovery because [reason]."

---

8. Recovery Plan

Generate a personalized jetlag recovery plan with pre-flight, in-flight, and post-arrival schedules. Optionally assess risk against arrival commitments.

curl -s -X POST "https://aerobase.app/api/v1/recovery/plan" \
  -H "Authorization: Bearer $AEROBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "SFO",
    "to": "TYO",
    "departure": "2026-06-10T11:00:00-07:00",
    "arrival": "2026-06-11T14:30:00+09:00",
    "cabin": "business",
    "arrival_commitments": [
      { "event": "Client meeting", "time": "2026-06-12T09:00:00+09:00" },
      { "event": "Team dinner", "time": "2026-06-12T19:00:00+09:00" }
    ]
  }'

Required: from, to, departure, arrival. Optional: cabin, arrival_commitments[] (event name + time).

Response data:

Field	Type	Description
score	object	Composite score, tier, recovery_days, breakdown
recovery_plan.pre_flight_schedule	array	Days before departure - light exposure, sleep timing
recovery_plan.during_flight	object	In-flight strategy - when to sleep, eat, hydrate
recovery_plan.post_arrival_schedule	array	Day-by-day recovery schedule
recovery_plan.recovery_timeline	array	Hourly adaptation milestones
recovery_plan.personalized_insights	array	Tailored advice
commitment_risks	array	Per-commitment risk assessment
timezone_shift	object	Hours, direction

Each commitment risk includes: event, scheduled_time, body_clock_time (what your body thinks the time is), misalignment_hours, risk_level (low | moderate | high), warning.

Present to user: Start with the score. Walk through the plan chronologically: "3 days before: Start shifting sleep 30 min earlier each night. On the flight: Sleep from [time] to [time]. Day 1: Get morning sunlight before 10am..." If commitments exist, flag any high-risk ones prominently.

---

9. Itinerary Analyze

Analyze a multi-leg itinerary for cumulative jetlag fatigue, compounding effects, and recovery gaps.

curl -s -X POST "https://aerobase.app/api/v1/itinerary/analyze" \
  -H "Authorization: Bearer $AEROBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "legs": [
      {
        "from": "SFO",
        "to": "LHR",
        "departure": "2026-06-01T17:00:00-07:00",
        "arrival": "2026-06-02T11:00:00+01:00",
        "cabin": "business"
      },
      {
        "from": "LHR",
        "to": "DXB",
        "departure": "2026-06-05T09:00:00+01:00",
        "arrival": "2026-06-05T19:30:00+04:00"
      },
      {
        "from": "DXB",
        "to": "SIN",
        "departure": "2026-06-08T02:00:00+04:00",
        "arrival": "2026-06-08T14:00:00+08:00"
      },
      {
        "from": "SIN",
        "to": "SFO",
        "departure": "2026-06-12T23:30:00+08:00",
        "arrival": "2026-06-12T20:00:00-07:00"
      }
    ]
  }'

Required: legs array (2-20 legs). Each leg needs from, to, departure, arrival. Optional per leg: cabin.

Response data:

Field	Type	Description
legs	array	Per-leg analysis with adjusted scores
summary.total_legs	number	Number of legs
summary.total_timezone_shifts	number	Cumulative hours shifted
summary.net_offset	number	Net timezone offset at end
summary.worst_leg	object	Leg with lowest adjusted score
summary.cumulative_recovery_days	number	Total recovery days needed
summary.average_adjusted_score	number	Average score accounting for fatigue
summary.fatigue_risk	string	low / moderate / high / severe
summary.incomplete_recoveries	number	Legs where recovery was insufficient
recommendation	string	Actionable advice

Each leg includes: score, adjusted_score (fatigue-weighted), cumulative_offset, days_since_previous, recovery_factor (0-1, how recovered you were), fatigue_multiplier, carryover_benefit (same-direction bonus).

Present to user: Give the overall fatigue risk first. Walk through each leg noting whether recovery time was adequate. Highlight the worst leg. "Your DXB-SIN leg is the weak point - only 3 days after your LHR-DXB flight, your body clock is still catching up. Consider adding 1-2 days in Dubai."

---

10. Flight Lookup

Look up a specific flight by carrier and number. Includes jetlag scoring when schedule data is available.

curl -s "https://aerobase.app/api/v1/flights/lookup/NH/7/\?date=2026-06-10" \
  -H "Authorization: Bearer $AEROBASE_API_KEY"

Path: /v1/flights/lookup/{carrier}/{number} where carrier is the 2-letter IATA airline code and number is the flight number. Optional query: date (YYYY-MM-DD) for date-specific schedule lookup.

Response data:

Field	Type	Description
flight_number	string	Full flight designator (e.g., "NH7")
airline	string	Carrier code
origin	string	Departure IATA
destination	string	Arrival IATA
departure_time	string	Departure time
arrival_time	string	Arrival time
duration_minutes	number/null	Flight duration
stops	number	Number of stops
segments	array/null	Multi-segment details (codeshares)
jetlag	object/null	score (0-100), tier, recovery_days, direction, timezone_shift

Present to user: "NH7 (ANA) SFO-NRT departs 11:00, arrives 14:30+1. Duration: 11h30m. Jetlag score: X/100 (tier), ~Y days recovery heading [direction]."

---

Heartbeat: Deal Monitoring

Periodically check deals for the user's home airport. Run this every few hours or at the start of each session.

curl -s "https://aerobase.app/api/v1/deals?departure=SFO&sort=value_score&limit=5" \
  -H "Authorization: Bearer $AEROBASE_API_KEY"

If a deal has value_score > 80 or is_error_fare: true, proactively mention it:

"New deal alert: $312 SFO-Barcelona in economy, scores 71/100 for jetlag. Error fare - may disappear soon. [source_url]"

Only surface deals that score above 50 for jetlag - a cheap flight that wrecks your sleep for a week is not a good deal.

---

Presentation Guidelines

1. Always mention jetlag score and recovery days - the primary differentiators.
2. Compare scores when showing multiple options. Quantify the difference: "that's a full day less recovery."
3. Highlight strategies - users want actionable advice, not just numbers.
4. Convert data to language - "9 time zones heading east" not "timezone_shift_hours: 9".
5. Context matters - a 70 on a 2-hour domestic flight is unremarkable; 70 on transpacific is excellent.
6. Use tier labels - excellent, good, moderate, poor, severe.
7. For awards - always mention the program, miles cost, and seats remaining together.
8. For itineraries - focus on the weakest link and what to do about it.

Score Interpretation

Score	Tier	Recovery	Meaning
80-100	Excellent	0-1 days	Minimal jetlag, well-timed flight
65-79	Good	1-2 days	Manageable with basic strategies
50-64	Moderate	2-3 days	Noticeable jetlag, follow recovery plan
35-49	Poor	3-5 days	Significant disruption expected
0-34	Severe	5+ days	Consider alternative flight times