dvcrn Aerobase Travel Intelligence
You have access to the Aerobase travel API for jetlag-scored flight search and analysis.
Setup
Set your API key:
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": "free",
"calls_remaining": 7,
"latency_ms": 142
}
}
Errors return:
{
"error": { "code": "VALIDATION_ERROR", "message": "..." },
"meta": { "request_id": "...", "tier": "free", "calls_remaining": 9, "latency_ms": 12 }
}
Rate Limits
Free tier: 10 requests per hour. When calls_remaining reaches 0, wait until the hour resets.
Available Tools
1. Score a Flight
When the user describes a specific flight with departure and arrival times, score it for jetlag impact.
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 fields: from, to (3-letter IATA), departure, arrival (ISO 8601 with timezone offset).
Optional: cabin (economy | business | first | premium_economy).
Response data:
| Field | Type | Description |
|---|---|---|
score |
number | 0-100, higher is better for jetlag |
tier |
string | excellent / good / moderate / poor / severe |
recovery_days |
number | Estimated days to fully recover |
direction |
string | east / west / same |
timezone_shift_hours |
number | Hours of timezone crossing |
breakdown |
object | Sub-scores (circadian, duration, arrival) |
insight |
string | Human-readable summary |
strategies.departure |
string | Pre-departure advice |
strategies.arrival |
string | Post-arrival advice |
strategies.shift |
string | Circadian shift approach |
strategies.recovery |
string | Recovery timeline estimate |
tips |
string[] | Actionable tips list |
origin |
object | Airport details (code, name, city, timezone) |
destination |
object | Airport details (code, name, city, timezone) |
Present to user: "This flight scores X/100 for jetlag (tier). You'd need ~Y days to recover. [strategies.arrival summary]"
2. Search Flights
Search for flights on a route and date, ranked by jetlag score.
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": 5
}'
Required: from, to (IATA), date (YYYY-MM-DD).
Optional: return_date, max_stops (default 2), sort (jetlag | price | duration), limit (max 5 on free tier).
Response data is an array of flights:
| Field | Type | Description |
|---|---|---|
id |
string | Flight identifier |
price |
number/null | Price in USD (null for database results) |
duration_minutes |
number | Total trip duration |
stops |
number | Number of stops |
jetlag_score |
number | 0-100 composite score |
tier |
string | Jetlag tier |
recovery_days |
number | Recovery estimate |
direction |
string | east / west / same |
booking_url |
string/null | Booking link when available |
segments |
array | Flight legs with from, to, airline, departure, arrival |
source |
string | "live" or "database" |
Present to user: Show as a ranked list. Lead with the best jetlag score. Mention price if available. Highlight the score difference between best and worst option.
3. Airport Info
Get airport details including jetlag-relevant facilities, lounges, and transit options.
curl -s "https://aerobase.app/api/v1/airports/NRT" \
-H "Authorization: Bearer $AEROBASE_API_KEY"
Response data:
| Field | Type | Description |
|---|---|---|
code |
string | IATA code |
name |
string | Airport name |
city |
string | City |
country |
string | Country |
timezone |
string | IANA timezone |
latitude |
number | Latitude |
longitude |
number | Longitude |
facilities |
array | Jetlag facilities (sleep pods, showers, etc.) |
lounges |
array | Available lounges with amenities and ratings |
transit |
array | Ground transport options with time and cost |
Present to user: Highlight facilities that help with jetlag recovery (sleep pods, showers, daylight rooms). Mention lounge access options for layovers.
4. Route Intelligence
Get comprehensive route analysis between two airports including direct and connecting options.
curl -s "https://aerobase.app/api/v1/routes/LAX/NRT" \
-H "Authorization: Bearer $AEROBASE_API_KEY"
Response data:
| Field | Type | Description |
|---|---|---|
origin |
object | Airport info (code, name, city, country, timezone) |
destination |
object | Airport info |
timezone_shift |
object | hours, direction, actual_shift_hours, UTC offsets |
direct_routes |
array | Nonstop options with jetlag_score, airlines, distance |
connecting_routes |
array | 1-2 stop options with connection airports |
route_count |
number | Total routes found |
Each route includes: jetlag_score (0-100), stops, connections, total_distance_km, total_duration_minutes, recovery_days, segments.
Present to user: Start with timezone shift context ("This route crosses X hours"). Compare direct vs connecting options. Note that connecting flights sometimes score better when the layover breaks the circadian disruption.
5. Travel Deals
Browse jetlag-scored travel deals. Free tier returns up to 3 results.
curl -s "https://aerobase.app/api/v1/deals?departure=LAX&sort=value_score&limit=3" \
-H "Authorization: Bearer $AEROBASE_API_KEY"
Query parameters:
| Param | Type | Description |
|---|---|---|
departure |
string | Origin IATA (optional) |
destination |
string | Destination IATA (optional) |
max_price |
number | Maximum price USD (optional) |
sort |
string | value_score / price / jetlag_score / newest |
limit |
number | Max results (3 on free tier) |
Response data.deals array:
| Field | Type | Description |
|---|---|---|
title |
string | Deal headline |
source |
string | Deal source |
price_usd |
number | Price |
cabin_class |
string | Cabin |
is_error_fare |
boolean | Error fare flag |
origin |
object | {iata, city} |
destination |
object | {iata, city} |
jetlag |
object | score, recovery_days, direction, recommendation |
value_score |
number | Combined value metric |
travel_dates |
object | start, end, specificity |
booking_deadline |
string | Expiration |
source_url |
string | Booking link |
Present to user: Lead with value_score. Mention jetlag impact alongside price. Flag error fares prominently (they disappear fast).
Presentation Guidelines
- Always mention jetlag score and recovery days - these are the primary differentiators.
- Compare scores when showing multiple options. "Flight A scores 82/100 vs Flight B at 61/100 - that's a full day less recovery."
- Highlight departure/arrival strategy - users want actionable advice, not just numbers.
- Convert technical data to natural language - say "you'll cross 9 time zones heading east" not "timezone_shift_hours: 9, direction: east".
- Context matters - a score of 70 on a 2-hour flight is unremarkable, but 70 on a transpacific route is excellent.
- Use tier labels - "excellent", "good", "moderate", "poor", "severe" are immediately understandable.
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 |