Aerobase Flights Skill

Search and analyze flights with jetlag scoring for healthier travel.

Authentication

Set AEROBASE_API_KEY as an environment variable:

export AEROBASE_API_KEY="ak_xxxxxxxx"

Get your API key from https://aerobase.app/connect

API Base URL

https://aerobase.app/api

Tools

---

1. Search Flights

Find flights between destinations with jetlag scoring.

Command:

curl -X POST https://aerobase.app/api/v1/flights/search \
  -H "Authorization: Bearer $AEROBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "LAX",
    "to": "NRT",
    "date": "2026-04-15",
    "cabin": "economy",
    "sort": "jetlag",
    "limit": 10
  }'

Parameters:

Parameter	Type	Description
from	string	Origin IATA code (e.g., LAX)
to	string	Destination IATA code (e.g., NRT)
date	string	Departure date (YYYY-MM-DD)
returnDate	string	Optional return date
cabin	string	economy, premium_economy, business, first
sort	string	jetlag, price, duration
limit	number	Results to return (free=5, pro=50)

Response includes: flight details + jetlag_score, recovery_days, direction

---

2. Score a Flight

Get detailed jetlag analysis for a specific flight.

Command:

curl -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-15T08:00:00-07:00",
    "arrival": "2026-04-16T14:30:00+09:00",
    "cabin": "business"
  }'

Parameters:

Parameter	Type	Description
from	string	Origin IATA code
to	string	Destination IATA code
departure	string	ISO 8601 with offset
arrival	string	ISO 8601 with offset
cabin	string	economy, premium_economy, business, first
chronotype	string	early_bird, night_owl, normal

Response includes:

• score (0-100, higher is better)
• tier: excellent|good|moderate|poor|severe
• recovery_days
• direction: east|west
• timezone_shift_hours
• breakdown (timezoneShift, departureTime, arrivalTime, duration, cabinComfort)
• strategies (departure, arrival, shift, recovery)
• tips

---

3. Compare Flights

Compare 2-10 flights side by side.

Command:

curl -X POST https://aerobase.app/api/v1/flights/compare \
  -H "Authorization: Bearer $AEROBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "flights": [
      {"from": "JFK", "to": "LHR", "departure": "2026-04-15T18:00:00-04:00", "arrival": "2026-04-16T07:00:00+01:00", "label": "Evening departure"},
      {"from": "JFK", "to": "LHR", "departure": "2026-04-15T22:00:00-04:00", "arrival": "2026-04-16T11:00:00+01:00", "label": "Red-eye"}
    ]
  }'

---

4. Recovery Plan

Generate personalized jetlag recovery plan.

Command:

curl -X POST https://aerobase.app/api/v1/recovery/plan \
  -H "Authorization: Bearer $AEROBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "LAX",
    "to": "NRT",
    "departure": "2026-04-15T08:00:00-07:00",
    "arrival": "2026-04-16T14:30:00+09:00",
    "arrival_commitments": [
      {"event": "Board Meeting", "time": "2026-04-17T09:00:00+09:00"}
    ]
  }'

Response includes:

• pre_flight_schedule (days before departure)
• during_flight recommendations
• post_arrival_schedule
• commitment_risks (if meetings provided)

---

5. Get Travel Deals

Find jetlag-scored travel deals.

Command:

curl "https://aerobase.app/api/v1/deals?departure=LAX&max_price=600&sort=jetlag_score&limit=10" \
  -H "Authorization: Bearer $AEROBASE_API_KEY"

Parameters:

Parameter	Type	Description
departure	string	Origin IATA code
destination	string	Destination IATA code
max_price	number	Maximum price in USD
sort	string	value_score, price, jetlag_score, newest
limit	number	Results (free=3, pro=50)

---

6. Airport Info

Get airport details with facilities.

Command:

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

---

7. Hotel Search

Find jetlag-friendly hotels near airport.

Command:

curl "https://aerobase.app/api/v1/hotels?airport=NRT&jetlagFriendly=true" \
  -H "Authorization: Bearer $AEROBASE_API_KEY"

---

8. Lounge Search

Find airport lounges.

Command:

curl "https://aerobase.app/api/v1/lounges?airport=LHR" \
  -H "Authorization: Bearer $AEROBASE_API_KEY"

---

9. Itinerary Analysis

Analyze multi-leg trips for cumulative jetlag.

Command:

curl -X POST https://aerobase.app/api/v1/itinerary/analyze \
  -H "Authorization: Bearer $AEROBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "legs": [
      {"from": "LAX", "to": "NRT", "departure": "...", "arrival": "..."},
      {"from": "NRT", "to": "SIN", "departure": "...", "arrival": "..."}
    ]
  }'

---

Jetlag Score Guide

Score	Tier	Recovery
80-100	Excellent	0-2 days
60-79	Good	2-3 days
40-59	Moderate	3-5 days
20-39	Poor	5-7 days
0-19	Severe	7+ days

Response Format

All responses:

{
  "data": { ... },
  "meta": {
    "request_id": "uuid",
    "tier": "free|pro|concierge|api",
    "calls_remaining": 95,
    "latency_ms": 234
  }
}

Error Handling

Common error codes:

• INVALID_API_KEY - Check your API key
• VALIDATION_ERROR - Invalid parameters
• RATE_LIMIT_EXCEEDED - Upgrade tier
• TIER_REQUIRED - Endpoint needs higher tier

Rate Limits

Tier	Daily Calls
Free	100
Pro	1,000
Concierge	10,000
API	Unlimited

Presenting Results

Show the jetlag score prominently:

✈️ UA870 LAX → NRT
   Score: 72/100 (Good) | Recovery: 3 days
   Dep: 11:00 AM | Arr: 2:30 PM (+1 day)
   💡 Red-eye aligns with natural sleep

Tips

• Always lead with the jetlag score
• Recommend flights with scores 60+ for business travel
• For important meetings, flag if score < 50
• Sort searches by "jetlag" for healthiest options