Aerobase Travel Intelligence
You have access to the Aerobase travel API for jetlag-scored flight search and analysis.
Setup
Set your API key:
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
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.
CODEBLOCK3
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 |
|---|
| INLINECODE7 | number | 0-100, higher is better for jetlag |
| INLINECODE8 |
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.
CODEBLOCK4
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 |
|---|
| INLINECODE28 | string | Flight identifier |
| INLINECODE29 |
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.
CODEBLOCK5
Response data:
| Field | Type | Description |
|---|
| INLINECODE39 | string | IATA code |
| INLINECODE40 |
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.
CODEBLOCK6
Response data:
| Field | Type | Description |
|---|
| INLINECODE49 | object | Airport info (code, name, city, country, timezone) |
| INLINECODE50 |
object | Airport info |
|
timezone_shift | object | hours, direction, actual
shifthours, 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.
CODEBLOCK7
Query parameters:
| Param | Type | Description |
|---|
| INLINECODE62 | string | Origin IATA (optional) |
| INLINECODE63 |
string | Destination IATA (optional) |
|
max_price | number | Maximum price USD (optional) |
|
sort | string | value
score / price / jetlagscore / newest |
|
limit | number | Max results (3 on free tier) |
Response data.deals array:
| Field | Type | Description |
|---|
| INLINECODE67 | string | Deal headline |
| INLINECODE68 |
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
- 1. 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 "timezoneshifthours: 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 |
Aerobase 旅行智能
您已获得 Aerobase 旅行 API 的访问权限，可用于基于时差评分的航班搜索与分析。
设置
设置您的 API 密钥：
bash
export AEROBASEAPIKEY=ak_...
所有请求均使用 https://aerobase.app/api 作为基础 URL。
响应封装
每个响应都将数据包裹在标准封装结构中：
json
{
data: { ... },
meta: {
requestid: reqabc123,
tier: free,
calls_remaining: 7,
latency_ms: 142
}
}
错误返回：
json
{
error: { code: VALIDATION_ERROR, message: ... },
meta: { requestid: ..., tier: free, callsremaining: 9, latency_ms: 12 }
}
速率限制
免费套餐：每小时 10 次请求。当 calls_remaining 降至 0 时，请等待至下一小时重置。
可用工具
1. 评分航班
当用户描述一个包含出发和到达时间的特定航班时，为其时差影响进行评分。
bash
curl -s -X POST https://aerobase.app/api/v1/flights/score \
-H Authorization: Bearer $AEROBASEAPIKEY \
-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
}
必填字段： from、to（3 字母 IATA 代码）、departure、arrival（ISO 8601 格式，含时区偏移）。
可选字段： cabin（economy | business | first | premium_economy）。
响应数据：
| 字段 | 类型 | 描述 |
|---|
| score | number | 0-100，越高越有利于缓解时差 |
| tier |
string | excellent / good / moderate / poor / severe |
| recovery_days | number | 预计完全恢复所需天数 |
| direction | string | east / west / same |
| timezone
shifthours | number | 跨越的时区小时数 |
| breakdown | object | 子评分（昼夜节律、时长、到达时间） |
| insight | string | 人类可读的摘要 |
| strategies.departure | string | 出发前建议 |
| strategies.arrival | string | 到达后建议 |
| strategies.shift | string | 昼夜节律调整方法 |
| strategies.recovery | string | 恢复时间线预估 |
| tips | string[] | 可操作的建议列表 |
| origin | object | 机场详情（代码、名称、城市、时区） |
| destination | object | 机场详情（代码、名称、城市、时区） |
向用户展示： 该航班时差评分为 X/100（等级）。您需要约 Y 天恢复。[strategies.arrival 摘要]
2. 搜索航班
按航线和日期搜索航班，并按时差评分排序。
bash
curl -s -X POST https://aerobase.app/api/v1/flights/search \
-H Authorization: Bearer $AEROBASEAPIKEY \
-H Content-Type: application/json \
-d {
from: SFO,
to: LHR,
date: 2026-05-20,
max_stops: 1,
sort: jetlag,
limit: 5
}
必填： from、to（IATA 代码）、date（YYYY-MM-DD）。
可选： returndate、maxstops（默认 2）、sort（jetlag | price | duration）、limit（免费套餐最多 5 个）。
响应数据 是一个航班数组：
number/null | 美元价格（数据库结果可能为 null） |
| duration_minutes | number | 总行程时长 |
| stops | number | 经停次数 |
| jetlag_score | number | 0-100 综合评分 |
| tier | string | 时差等级 |
| recovery_days | number | 恢复预估天数 |
| direction | string | east / west / same |
| booking_url | string/null | 预订链接（如有） |
| segments | array | 航段信息，含出发地、目的地、航空公司、出发时间、到达时间 |
| source | string | live 或 database |
向用户展示： 以排名列表形式展示。优先展示时差评分最高的选项。如有价格信息则提及。突出最佳与最差选项之间的评分差异。
3. 机场信息
获取机场详情，包括时差相关设施、休息室及中转选项。
bash
curl -s https://aerobase.app/api/v1/airports/NRT \
-H Authorization: Bearer $AEROBASEAPIKEY
响应数据：
| 字段 | 类型 | 描述 |
|---|
| code | string | IATA 代码 |
| name |
string | 机场名称 |
| city | string | 城市 |
| country | string | 国家 |
| timezone | string | IANA 时区 |
| latitude | number | 纬度 |
| longitude | number | 经度 |
| facilities | array | 时差缓解设施（睡眠舱、淋浴间等） |
| lounges | array | 可用休息室，含设施及评分 |
| transit | array | 地面交通选项，含时间及费用 |
向用户展示： 突出有助于时差恢复的设施（睡眠舱、淋浴间、日光室）。提及中转期间的休息室使用选项。
4. 航线智能分析
获取两个机场之间的全面航线分析，包括直飞和中转选项。
bash
curl -s https://aerobase.app/api/v1/routes/LAX/NRT \
-H Authorization: Bearer $AEROBASEAPIKEY
响应数据：
| 字段 | 类型 | 描述 |
|---|
| origin | object | 机场信息（代码、名称、城市、国家、时区） |
| destination |
object | 机场信息 |
| timezone_shift | object | 小时数、方向、实际偏移小时数、UTC 偏移量 |
| direct_routes | array | 直飞选项，含时差评分、航空公司、距离 |
| connecting_routes | array | 1-2 次经停选项，含中转机场 |
| route_count | number | 找到的总航线数 |
每条航线包含：jetlagscore（0-100）、stops、connections、totaldistancekm、totaldurationminutes、recoverydays、segments。
向用户展示： 从时区偏移背景信息开始（该航线跨越 X 小时）。比较直飞与中转选项。注意当经停点打破昼夜节律干扰时，中转航班有时评分更高。
5. 旅行优惠
浏览带时差评分的旅行优惠。免费套餐最多返回 3 个结果。
bash
curl -s https://aerobase.app/api/v1/deals?departure=LAX&sort=value_score&limit=3 \
-H Authorization: Bearer $AEROBASEAPIKEY
查询参数：
| 参数 | 类型 | 描述 |
|---|
| departure | string | 出发地 IATA 代码（可选） |
| destination |
string | 目的地 IATA 代码（可选） |
| max_price | number | 最高价格美元（可选） |
| sort | string | value
score / price / jetlagscore / newest |
| limit | number | 最大结果数（免费套餐为 3） |
响应数据.deals 数组：
|
