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