# StableTravel API

> Pay-per-request access to flights, hotels, activities, transfers (Amadeus), and real-time flight tracking, airport info, history, and predictions (FlightAware AeroAPI). No auth, no API keys, no subscriptions. Powered by x402/MPP micropayments (USDC on Base, Solana, or Tempo).

## Choosing the Right Data Source

StableTravel has three data providers. Pick the right one for the job:

| Need | Use | Why |
|------|-----|-----|
| **Cheapest flight price** | Google Flights (`/api/google-flights/search`) | Aggregates prices across all airlines, OTAs, and booking sites. Same results as google.com/flights. |
| **Book a flight via API** | Amadeus (`/api/flights/search` → `/api/flights/book`) | Direct GDS inventory with real-time availability. Only way to programmatically book, price-confirm, or manage orders. |
| **Complex itineraries** | Amadeus (`/api/flights/search` POST) | Multi-city, cabin class mixing, fare rules, upsells, seat maps. GDS has the deepest data. |
| **Track a live flight** | FlightAware (`/api/flightaware/flights/`) | Real-time position, track, delays, ATC routing. |
| **Airport info & delays** | FlightAware (`/api/flightaware/airports/`) | Weather, delay stats, scheduled flights, disruptions. |
| **Flight history** | FlightAware (`/api/flightaware/history/`) | Historical tracks, routes, operator flight logs. |
| **Hotels, activities, transfers** | Amadeus | Only provider for these categories. |

**Rule of thumb:** Start with Google Flights for price discovery, switch to Amadeus for booking. Use FlightAware for operational/tracking data.

## How It Works

Send a standard HTTP request to any endpoint. Payment is handled automatically via x402/MPP protocol headers. No signup, no tokens, no OAuth.

## Quick Start

```bash
# Search flights from NYC to LA (GET — simple search)
npx agentcash fetch "https://stabletravel.dev/api/flights/search?originLocationCode=JFK&destinationLocationCode=LAX&departureDate=2025-06-15&adults=1&max=5"

# Search flights (POST — advanced multi-city)
npx agentcash fetch -X POST -H "Content-Type: application/json" \
  -d '{"originDestinations":[{"id":"1","originLocationCode":"JFK","destinationLocationCode":"LAX","departureDateTimeRange":{"date":"2025-06-15"}}],"travelers":[{"id":"1","travelerType":"ADULT"}],"sources":["GDS"],"searchCriteria":{"maxFlightOffers":5}}' \
  "https://stabletravel.dev/api/flights/search"
```

## Endpoints

### Flights

| Endpoint | Method | Price | Description |
|---|---|---|---|
| /api/flights/search | GET, POST | $0.05 | Search flight offers (GET for simple, POST for advanced multi-city) |
| /api/flights/price | POST | $0.03 | Confirm pricing for a flight offer |
| /api/flights/book | POST | $0.09 | Book a flight (create flight order) |
| /api/flights/orders | GET | $0.005 | Retrieve a flight order by ID |
| /api/flights/orders/cancel | POST | $0.005 | Cancel a flight order |
| /api/flights/seatmap | GET, POST | $0.03 | Get seat maps for a flight |
| /api/flights/upsell | POST | $0.03 | Get upsell offers for a flight |
| /api/flights/availability | POST | $0.03 | Check flight availability |
| /api/flights/status | GET | $0.005 | Get flight status by carrier, number, and date |
| /api/flights/checkin-links | GET | $0.005 | Get airline check-in page URLs |

### Hotels

| Endpoint | Method | Price | Description |
|---|---|---|---|
| /api/hotels/list | GET | $0.03 | List hotels by city code (default max 100) |
| /api/hotels/list/by-geocode | GET | $0.03 | List hotels by latitude/longitude (default max 100) |
| /api/hotels/search | GET | $0.03 | Search hotel offers by hotel IDs (use /hotels/list first to get IDs) |
| /api/hotels/search/by-hotel | GET | $0.03 | Search offers for a specific hotel ID |
| /api/hotels/offer | GET | $0.03 | Get details for a specific hotel offer |
| /api/hotels/book | POST | $0.002 | Book a hotel offer |
| /api/hotels/autocomplete | GET | $0.005 | Autocomplete hotel names |
| /api/hotels/ratings | GET | $0.05 | Get hotel sentiment ratings and reviews |

### Activities

| Endpoint | Method | Price | Description |
|---|---|---|---|
| /api/activities/search | GET | $0.05 | Search tours & activities by lat/lng (default max 50) |
| /api/activities/by-square | GET | $0.05 | Search activities within a geographic square (default max 50) |
| /api/activities/details | GET | $0.05 | Get activity details by ID |

### Transfers

| Endpoint | Method | Price | Description |
|---|---|---|---|
| /api/transfers/search | POST | $0.003 | Search airport transfer options |
| /api/transfers/book | POST | $0.002 | Book a transfer |
| /api/transfers/cancel | POST | $0.002 | Cancel a transfer booking |

### Reference Data

| Endpoint | Method | Price | Description |
|---|---|---|---|
| /api/reference/locations | GET | $0.005 | Search locations (airports, cities) by keyword |
| /api/reference/airports | GET | $0.005 | Find nearby airports by latitude/longitude |
| /api/reference/airlines | GET | $0.005 | Look up airline by IATA code |
| /api/reference/airline-routes | GET | $0.005 | Get routes for an airline from an airport (default max 50) |
| /api/reference/airport-routes | GET | $0.005 | Get direct destinations from an airport (default max 50) |
| /api/reference/cities | GET | $0.005 | Search cities by keyword |

## Common Parameters

### Flight Search (GET)
- **originLocationCode** (required): IATA origin airport code (e.g. JFK)
- **destinationLocationCode** (required): IATA destination airport code (e.g. LAX)
- **departureDate** (required): Departure date (YYYY-MM-DD)
- **adults** (required): Number of adult travelers (1-9)
- **returnDate**: Return date for round-trip (YYYY-MM-DD)
- **travelClass**: ECONOMY, PREMIUM_ECONOMY, BUSINESS, or FIRST
- **nonStop**: Filter non-stop flights only (true/false)
- **currencyCode**: Currency code (e.g. USD)
- **maxPrice**: Maximum price filter
- **max**: Maximum number of results

### Flight Search (POST)
The POST body requires `originDestinations` and `travelers` arrays:
```json
{
  "originDestinations": [{ "id": "1", "originLocationCode": "JFK", "destinationLocationCode": "LAX", "departureDateTimeRange": { "date": "2025-06-15" } }],
  "travelers": [{ "id": "1", "travelerType": "ADULT" }],
  "sources": ["GDS"],
  "searchCriteria": { "maxFlightOffers": 5 }
}
```

### Flight Price (POST)
Pass the full flight offer from a search result. Body must use `type: "flight-offers-pricing"`:
```json
{ "data": { "type": "flight-offers-pricing", "flightOffers": [ <flight-offer-object> ] } }
```

### Flight Upsell (POST)
Body must use `type: "flight-offers-upselling"`:
```json
{ "data": { "type": "flight-offers-upselling", "flightOffers": [ <flight-offer-object> ] } }
```

### Flight Seatmap (POST)
Body wraps flight offers in a `data` array:
```json
{ "data": [ <flight-offer-object> ] }
```

### Flight Status
- **carrierCode** (required): Airline IATA code (e.g. AA)
- **flightNumber** (required): Flight number (e.g. 100)
- **scheduledDepartureDate** (required): Date (YYYY-MM-DD)

### Hotel List
- **cityCode** (required): IATA city code (e.g. PAR, LON, NYC)
- **max**: Maximum results (default 100)
- **radius**: Search radius
- **ratings**: Comma-separated star ratings (1-5)

### Hotel List by Geocode
- **latitude** (required): Latitude coordinate
- **longitude** (required): Longitude coordinate
- **max**: Maximum results (default 100)

### Hotel Search
- **hotelIds** (required): Comma-separated Amadeus hotel IDs (get these from /hotels/list)
- **checkInDate**: Check-in date (YYYY-MM-DD)
- **checkOutDate**: Check-out date (YYYY-MM-DD)
- **adults**: Number of adults (default 1)

### Activities Search
- **latitude** (required): Latitude coordinate
- **longitude** (required): Longitude coordinate
- **radius**: Search radius in km (default 1)
- **max**: Maximum results (default 50)

### Activities by Square
- **north** (required): Northern latitude boundary
- **south** (required): Southern latitude boundary
- **east** (required): Eastern longitude boundary
- **west** (required): Western longitude boundary
- **max**: Maximum results (default 50)

### Transfers Search (POST)
```json
{
  "startLocationCode": "CDG",
  "endAddressLine": "Avenue des Champs-Elysees 1",
  "endCityName": "Paris",
  "endZipCode": "75008",
  "endCountryCode": "FR",
  "endGeoCode": "48.8566,2.3522",
  "transferType": "PRIVATE",
  "startDateTime": "2025-06-15T10:00:00",
  "passengers": 2
}
```
Note: Drop-off requires either full address fields (endAddressLine + endCityName + endCountryCode) or endGeoCode, or both.

### Reference Locations
- **keyword** (required): Search keyword (city or airport name)
- **subType** (required): AIRPORT, CITY, or AIRPORT,CITY

### Airline / Airport Routes
- **airlineCode** or **departureAirportCode** (required): IATA code
- **max**: Maximum results (default 50)

### FlightAware — Real-Time Flights

| Endpoint | Method | Price | Description |
|---|---|---|---|
| /api/flightaware/flights/search | GET | $0.10 | Search flights by query string (idents, latlong, airline) |
| /api/flightaware/flights/search/positions | GET | $0.10 | Search flights with position data |
| /api/flightaware/flights/search/count | GET | $0.04 | Get count of flights matching a search |
| /api/flightaware/flights/search/advanced | GET | $0.10 | Advanced flight search with complex query syntax |
| /api/flightaware/flights/{ident} | GET | $0.01 | Get flights by ident (flight number, registration, etc.) |
| /api/flightaware/flights/{ident}/canonical | GET | $0.002 | Get canonical ident for a flight |
| /api/flightaware/flights/{ident}/intents | POST | $0.001 | Set flight intent for push notifications |
| /api/flightaware/flights/{id}/position | GET | $0.02 | Get latest position for a flight |
| /api/flightaware/flights/{id}/track | GET | $0.024 | Get full track/positions for a flight |
| /api/flightaware/flights/{id}/route-info | GET | $0.02 | Get route info (fixes, waypoints) for a flight |
| /api/flightaware/flights/{id}/map | GET | $0.06 | Get flight track map payload (proxied from FlightAware) |

### FlightAware — Airports

| Endpoint | Method | Price | Description |
|---|---|---|---|
| /api/flightaware/airports | GET | $0.01 | List all airports |
| /api/flightaware/airports/nearby | GET | $0.008 | Find airports near a lat/lng |
| /api/flightaware/airports/delays | GET | $0.10 | Get all airport delay information |
| /api/flightaware/airports/{id} | GET | $0.03 | Get airport info by code |
| /api/flightaware/airports/{id}/canonical | GET | $0.002 | Get canonical airport code |
| /api/flightaware/airports/{id}/nearby | GET | $0.008 | Find airports near a specific airport |
| /api/flightaware/airports/{id}/delays | GET | $0.02 | Get delays for a specific airport |
| /api/flightaware/airports/{id}/flights | GET | $0.04 | Get all flights at an airport |
| /api/flightaware/airports/{id}/flights/arrivals | GET | $0.01 | Get arrivals at an airport |
| /api/flightaware/airports/{id}/flights/departures | GET | $0.01 | Get departures from an airport |
| /api/flightaware/airports/{id}/flights/scheduled-departures | GET | $0.01 | Get scheduled departures |
| /api/flightaware/airports/{id}/flights/scheduled-arrivals | GET | $0.01 | Get scheduled arrivals |
| /api/flightaware/airports/{id}/flights/to/{dest_id} | GET | $0.10 | Get flights between two airports |
| /api/flightaware/airports/{id}/flights/counts | GET | $0.20 | Get flight count statistics |
| /api/flightaware/airports/{id}/weather/observations | GET | $0.004 | Get METAR weather observations |
| /api/flightaware/airports/{id}/weather/forecast | GET | $0.004 | Get TAF weather forecast |
| /api/flightaware/airports/{id}/routes/{dest_id} | GET | $0.04 | Get route info between airports |

### FlightAware — Flight History

| Endpoint | Method | Price | Description |
|---|---|---|---|
| /api/flightaware/history/flights/{ident} | GET | $0.04 | Get historical flights by ident |
| /api/flightaware/history/flights/{id}/track | GET | $0.12 | Get historical flight track |
| /api/flightaware/history/flights/{id}/map | GET | $0.28 | Get historical flight map payload (proxied from FlightAware) |
| /api/flightaware/history/flights/{id}/route-info | GET | $0.08 | Get historical flight route info |
| /api/flightaware/history/airports/{id}/flights/arrivals | GET | $0.04 | Get historical arrivals at airport |
| /api/flightaware/history/airports/{id}/flights/departures | GET | $0.04 | Get historical departures from airport |
| /api/flightaware/history/airports/{id}/flights/to/{dest_id} | GET | $0.24 | Get historical flights between airports |
| /api/flightaware/history/aircraft/{registration}/last-flight | GET | $0.40 | Get last flight for an aircraft |
| /api/flightaware/history/operators/{id}/flights | GET | $0.04 | Get historical flights by operator |

### FlightAware — Disruption Counts

| Endpoint | Method | Price | Description |
|---|---|---|---|
| /api/flightaware/disruption-counts/{entity_type} | GET | $0.01 | Get disruption stats by entity type (airline, origin, destination) |
| /api/flightaware/disruption-counts/{entity_type}/{id} | GET | $0.01 | Get disruption stats for a specific entity |

## FlightAware Common Parameters

### Flight Search
- **query** (required): Search string using FlightAware query syntax
  - Ident search: `-idents "UAL*"`
  - Lat/long box: `-latlong "36 -104 30 -86"`
  - Airline: `-airline "UAL"`

### Flight by Ident
- **ident** (path): Flight ident (e.g. UAL123, N12345, SWA100)
- **ident_type**: fa_flight_id, designator, or registration
- **start/end**: ISO 8601 time range filter
- **cursor**: Pagination cursor

### Airport Operations
- **id** (path): ICAO or IATA airport code (e.g. KJFK, JFK)
- **airline**: Filter by airline IATA code
- **type**: arrivals, departures, enroute, scheduled_arrivals, scheduled_departures

### Weather
- **temperature_units**: fahrenheit or celsius
- **return_nearby_weather**: true to include nearby station data

### Disruption Counts
- **entity_type** (path): airline, origin, or destination
- **time_period**: today, yesterday, last3days, last7days, last14days, last30days

## Google Flights (via SerpAPI)

Real-time Google Flights data — prices, schedules, and booking links aggregated across all airlines and booking sites.

### Search Flights
- **GET /api/google-flights/search** ($0.02) — Search Google Flights
  - departure_id: Airport IATA code, city, or kgmid (e.g. "JFK", "CDG")
  - arrival_id: Airport IATA code, city, or kgmid
  - outbound_date: YYYY-MM-DD
  - return_date: YYYY-MM-DD (required for round trip)
  - type: 1 = Round trip (default), 2 = One way, 3 = Multi-city
  - travel_class: 1 = Economy, 2 = Premium economy, 3 = Business, 4 = First
  - adults, children, infants_in_seat, infants_on_lap: Passenger counts
  - stops: 0 = Any, 1 = Nonstop, 2 = Up to 1 stop, 3 = Up to 2 stops
  - max_price: Maximum price filter
  - include_airlines / exclude_airlines: Comma-separated airline codes
  - currency: 3-letter code (default USD)
  - Returns: best_flights, other_flights, price_insights (lowest price, typical range, price history)

### Get Booking Options
- **GET /api/google-flights/booking** ($0.02) — Get booking links and prices for a specific flight
  - Same params as search, plus departure_token (from search result)
  - Returns: selected_flights, booking_options (airline sites, OTAs, prices, URLs)

## Typical Workflows

1. **Book a flight**: search → price → book
2. **Compare flight prices**: /google-flights/search for price comparison, then /flights/search + /flights/book for booking
3. **Book a hotel**: list (get hotel IDs) → search (get offer IDs) → offer (confirm details) → book
4. **Find activities**: search by lat/lng or by-square → details (by activity ID)
5. **Book a transfer**: search → book
6. **Track a live flight**: /flightaware/flights/{ident} → get fa_flight_id → /flightaware/flights/{id}/track
7. **Check airport status**: /flightaware/airports/{id} → /flightaware/airports/{id}/delays + /flightaware/airports/{id}/weather/observations
8. **Research flight history**: /flightaware/history/flights/{ident} → /flightaware/history/flights/{id}/track

## Authentication

No API keys needed. Payment via USDC on Base, Solana, or Tempo (x402/MPP protocol) serves as authentication. Use `npx agentcash fetch` for automatic payment handling.

## OpenAPI Spec

Full schema available at `/openapi.json`