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

CODEBLOCK0

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

Response Envelope

Every response wraps data in a standard envelope:

CODEBLOCK1

Errors return:

CODEBLOCK2

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.

CODEBLOCK3

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.

CODEBLOCK4

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.

CODEBLOCK5

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

---

4. Route Intelligence

Comprehensive route analysis with direct and connecting options.

CODEBLOCK6

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.

CODEBLOCK7

Params: departure, destination, max_price, sort (valuescore | price | jetlagscore | 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.

CODEBLOCK8

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
INLINECODE82	string	Origin IATA
INLINECODE83

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 jetlagscorek2. 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.

CODEBLOCK9

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

Response data:

Field	Type	Description
INLINECODE99	array	Scored flights with full breakdown and per-flight strategies
INLINECODE100

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, recoverydays, direction, breakdown), explanation (summary, departurestrategy, arrivalstrategy, shiftapproach, 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.

CODEBLOCK10

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

Response data:

Field	Type	Description
INLINECODE114	object	Composite score, tier, recovery_days, breakdown
INLINECODE115

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.

CODEBLOCK11

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

Response data:

Field	Type	Description
INLINECODE134	array	Per-leg analysis with adjusted scores
INLINECODE135

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.

CODEBLOCK12

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
INLINECODE153	string	Full flight designator (e.g., "NH7")
INLINECODE154

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, recoverydays, direction, timezoneshift |

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.

CODEBLOCK13

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. 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 "timezoneshifthours: 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 |