# Flights API — flight search, cheapest-day price graph, airport/IATA lookup & seat specs (worldwide, live prices, booking links)

> Search flights from origin to destination for a given date. Returns ranked itineraries with price, all flight segments (carrier, flight number, departure/arrival times), total journey duration and a direct booking link. Supports one-way and return trips.
> ReefAPI engine `flights` · 5 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/flights/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed or blocked calls are free.
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http, `Authorization: Bearer <key>`) and your assistant can call these actions directly.

## Endpoints

### POST /flights/v1/search_flights — 2 credits
Search flights from origin to destination for a given date. Returns ranked itineraries with price, all flight segments (carrier, flight number, departure/arrival times), total journey duration and a direct booking link. Supports one-way and return trips.

**Parameters:**
- `origin` (string, required) — Departure: IATA code (LON/JFK), city name, or Kiwi location id.
- `destination` (string, required) — Arrival: IATA code, city name, or Kiwi location id.
- `depart_date` (string, required) — Outbound date, YYYY-MM-DD (must be a future date).
- `return_date` (string, optional) — Return date, YYYY-MM-DD. Omit for a one-way search.
- `depart_date_end` (string, optional) — End of an outbound date RANGE (YYYY-MM-DD); search any departure between depart_date and this.
- `return_date_end` (string, optional) — End of a return date RANGE (YYYY-MM-DD).
- `adults` (integer, optional, default 1) — Number of adult passengers.
- `children` (integer, optional, default 0) — Number of child passengers (2-11).
- `infants` (integer, optional, default 0) — Number of infant passengers (<2).
- `cabin_class` (enum, optional, default "economy") — Cabin class (unknown values fall back to economy). [one of: economy, premium_economy, business, first]
- `currency` (string, optional, default "USD") — ISO-4217 currency for prices (e.g. USD, EUR, GBP). Default USD.
- `max_stops` (integer, optional) — Max number of stops (0 = direct only). Omit for any.
- `sort` (enum, optional, default "price") — Result ordering (unknown values fall back to price). [one of: price, duration, quality, date, popularity]
- `limit` (integer, optional, default 20) — Max itineraries to return (default 20).

**Returns:** flights[]{price{amount,currency}, segments[]{carrier,carrier_code,flight_no,departure,arrival}, duration_seconds, booking_url, origin, destination} (return trips have outbound/inbound legs), count, trip_type, total_available

**Example request body:**
```json
{
  "origin": "London",
  "destination": "New York",
  "depart_date": "2026-08-19",
  "limit": 5
}
```

### POST /flights/v1/search_places — 1 credit
Resolve a city or airport name to location IDs used in flight search — useful when you want to pin an exact airport rather than a city (e.g. 'Heathrow' → LHR).

**Parameters:**
- `query` (string, required) — City or airport name / IATA code to resolve to Kiwi place ids.
- `limit` (integer, optional, default 8) — Max place matches to return (default 8).

**Returns:** places[]{id, name, type}, count

**Example request body:**
```json
{
  "query": "London"
}
```

### POST /flights/v1/airport_info — 1 credit
Look up airports and cities by name or IATA code. Returns full reference data: IATA + ICAO codes, GPS coordinates, timezone, country, and — for a city — the list of all its airports. Useful to validate a code, geolocate an airport, or map a city to its airports.

**Parameters:**
- `query` (string, required) — Airport or city name / IATA code (e.g. 'Heathrow', 'LHR', 'Istanbul').
- `limit` (integer, optional, default 5) — Max matches to return (default 5).

**Returns:** places[]{id, name, type (Station/City/Country), iata, icao, timezone, gps{lat,lng}, country, country_code, airports_count, airports[]{iata,icao,name,gps}}, count

**Example request body:**
```json
{
  "query": "Heathrow"
}
```

### POST /flights/v1/price_graph — 2 credits
Find the cheapest day to fly. Returns the lowest price for each departure date across a date range, each tagged CHEAP / AVERAGE / EXPENSIVE, plus the single cheapest option. Set nights_min/nights_max for a return trip; omit them for one-way. One fast call.

**Parameters:**
- `origin` (string, required) — Departure: IATA code (LON/JFK), city name, or Kiwi location id.
- `destination` (string, required) — Arrival: IATA code, city name, or Kiwi location id.
- `depart_date` (string, required) — Start of the departure date range, YYYY-MM-DD (future).
- `depart_date_end` (string, optional) — End of the departure date range, YYYY-MM-DD. Defaults to ~30 days after depart_date if omitted.
- `nights_min` (integer, optional) — Minimum number of nights at the destination — turns the price graph into a return-trip search (omit both for one-way).
- `nights_max` (integer, optional) — Maximum number of nights at the destination — turns the price graph into a return-trip search (omit both for one-way).
- `adults` (integer, optional, default 1) — Number of adult passengers.
- `children` (integer, optional, default 0) — Number of child passengers (2-11).
- `infants` (integer, optional, default 0) — Number of infant passengers (<2).
- `cabin_class` (enum, optional, default "economy") — Cabin class (unknown values fall back to economy). [one of: economy, premium_economy, business, first]
- `currency` (string, optional, default "USD") — ISO-4217 currency for prices (e.g. USD, EUR, GBP). Default USD.

**Returns:** prices[]{date, return_date, price, currency, rating}, cheapest{date,price}, count, currency, trip_type, origin, destination

**Example request body:**
```json
{
  "origin": "London",
  "destination": "New York",
  "depart_date": "2026-08-19",
  "depart_date_end": "2026-08-26"
}
```

### POST /flights/v1/seat_info — 1 credit
Get the seat specs and amenities for a specific flight: seat pitch, width and recline (legroom/comfort), plus power, Wi-Fi and in-flight entertainment availability. Look up by airline + flight number + route + date. Returns honest empty when the flight is unknown.

**Parameters:**
- `carrier` (string, required) — Operating airline IATA code (2 chars, e.g. BA = British Airways, AA = American, LH = Lufthansa).
- `flight_number` (string, required) — Flight number (numeric part only, e.g. 177; 'BA177' is also accepted).
- `source` (string, required) — Departure airport IATA code (e.g. LHR).
- `destination` (string, required) — Arrival airport IATA code (e.g. JFK).
- `date` (string, required) — Flight date, YYYY-MM-DD (must be a future date).
- `cabin_class` (enum, optional, default "economy") — Cabin class (unknown values fall back to economy). [one of: economy, premium_economy, business, first]

**Returns:** flight, carrier, source, destination, cabin_class, found, seat{pitch{value,unit}, width{value,unit}, recline{value,unit}, has_power, has_wifi, has_audio_video, power, audio_video}

**Example request body:**
```json
{
  "carrier": "BA",
  "flight_number": "177",
  "source": "LHR",
  "destination": "JFK",
  "date": "2026-08-19"
}
```

## More
- Try it live, no code: https://reefapi.com/playground?engine=flights
- Human docs page: https://reefapi.com/docs/flights
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt