# FlightPowers: complete reference (llms-full.txt)

> Live flight and hotel prices, and the context to judge them. Real-time Google Flights and Booking.com data as clean JSON, for developers and AI agents. This file is the whole API reference in one place; the shorter index is at https://flightpowers.com/llms.txt and the OpenAPI 3.1 spec at https://flightpowers.com/openapi.json.

Last-Updated: 2026-08-27

## Authentication

Bring your own RapidAPI key; every request is billed to your own subscription. Accepted, in precedence order: `x-api-key` header, `x-rapidapi-key` header, `Authorization: Bearer <key>`, and `?api_key=` (discouraged: keys in URLs end up in logs). Get a key: https://rapidapi.com/mtnrabi/api/google-flights-live-api/pricing (flights) or https://rapidapi.com/mtnrabi/api/booking-live-api/pricing (hotels). Flights and hotels are separate subscriptions.

Base URL: https://api.flightpowers.com (canonical REST front). The same engines also serve RapidAPI-native hosts google-flights-live-api.p.rapidapi.com and booking-live-api.p.rapidapi.com with RapidAPI's own paths.

## What makes it different

- Google's own price band, plus a verdict: Every fare carries price_insights_low / price_insights_high (Google's historical band for the route and dates) and a low | typical | high verdict. You can tell a user "$112 is a good price," not just "$112."
- Round-trip as one paired itinerary: A real /roundtrip endpoint: one object per itinerary with total_price, total_duration_seconds and both legs already paired, not two one-way searches stapled together.
- "No flights" and "the search failed" are different answers: X-Search-Status separates a genuine empty result from a degraded search. An empty array is only ever reported when the page it came from positively said so. Opt-in strict mode turns a degraded search into an HTTP 503.
- A working buy_link on every result: Every itinerary ships with a deep link straight into Google Flights for that exact flight. Metasearch and agent handoff without reconstructing the booking URL.
- Rate limits sized for parallel date scans: 150 requests/minute on Pro, 250 on Ultra, 500 on Mega. A flexible-date search (31 dates × 3 durations) finishes in one burst instead of a slow serial loop.
- Per-country hotel pricing with proxy_country: Every hotels endpoint accepts a two-letter proxy_country that routes through a residential proxy in that market. Same room, priced from the US, Germany, and Israel. Rate-parity monitoring from a single API.

## REST endpoints

### GET /v1/verify

Check that an API key works, as cheaply as possible

Validates the caller's RapidAPI key against the cheapest possible upstream call. A key subscribed to either API is valid. Built for platform "Test connection" buttons.

Response 200: The key is valid.
Fields:
- valid (boolean)
- checks (array of object)
  - api (flights | hotels)
  - ok (boolean)
  - checked (string)
  - reason (string)
- api_usage (object) - Your RapidAPI plan quota counters.
- key_source (string) - Which channel supplied the key (header name or query param). Never the value.

Response 401: Missing, malformed, or unsubscribed key.

### POST /v1/flights/oneway

Search one-way flights (live Google Flights results)

Returns live Google Flights itineraries for a route and date. Every result carries Google's historical price band (`price_insights_low`/`price_insights_high`) and a `low | typical | high` verdict. Read `X-Search-Status` before interpreting an empty array: `empty` means Google genuinely has no itineraries, `degraded` means the search did not complete and should be retried (or send `"strict": true` to get an HTTP 503 instead). Responses also carry your RapidAPI plan quota as `x-plan-*` headers (forwarded from the upstream billing layer), so you can watch usage without a dashboard.

Request body (application/json):
- from_airport (string, REQUIRED) - Origin IATA code, e.g. `JFK`.
- to_airport (string, REQUIRED) - Destination IATA code, e.g. `LHR`.
- departure_date (string, REQUIRED) - YYYY-MM-DD.
- max_stops (integer) - Maximum stops, e.g. 0 for non-stop only.
- airline_codes (array of string) - Only include these airlines (IATA codes).
- exclude_airline_codes (array of string) - Exclude these airlines (IATA codes).
- departure_time_min (integer) - Earliest departure hour (0-23).
- departure_time_max (integer) - Latest departure hour (0-23).
- departure_arrival_time_min (integer) - Earliest arrival hour (0-23).
- departure_arrival_time_max (integer) - Latest arrival hour (0-23).
- sort_type (Overall | Price | Duration, default "Overall") - Result ordering.
- currency (string, default "USD") - ISO currency code for prices, e.g. `USD`, `EUR`.
- max_price (integer) - Only return itineraries at or below this price.
- seat_type (1 | 3) - Cabin: 1 = Economy, 3 = Business.
- passengers (array of 1 | 2 | 3 | 4) - One integer per passenger: 1 = adult, 2 = child, 3 = infant on lap, 4 = infant in seat. Default: one adult.
- limit (integer, default 10) - Maximum number of results to return.
- use_fallback (boolean) - A secondary flight-data source the API can escalate to when the live Google Flights search does not come back with results. Last resort, not part of the normal path: a search that succeeds never touches it. Send `false` to switch the escalation off for a request. Responses that do use it can take longer.
- strict (boolean, default false) - Opt-in. Return HTTP 503 with a `search_incomplete` error body instead of an empty array when the search did not complete (X-Search-Status `degraded`).
- use_ext_proxy (boolean, default true) - When true, requests may be routed through an external residential proxy to reduce blocks from Google. Set false to force a direct request (lower latency, more block risk).

Response 200: A JSON array of itineraries, cheapest patterns first. May be empty: check `X-Search-Status`.
Each array item:
- price_range_in_relation_to_other_periods (low | typical | high) - Google's verdict on this fare vs the route's historical range. The field rival Google Flights APIs generally do not return.
- price_insights_low (number) - Bottom of Google's historical price range for this route and dates.
- price_insights_high (number) - Top of Google's historical price range for this route and dates.
- from_airport (string)
- to_airport (string)
- departure_date (string)
- price (string) - Display price, e.g. `$433`.
- price_as_number (number) - Numeric price for sorting and comparison.
- duration (string) - Human-readable duration.
- duration_seconds (integer)
- buy_link (string) - Deep link to book this exact itinerary on Google Flights.
- airline (string)
- stops (integer)
- stops_info (array of object)
  - stop_airport (string)
  - stop_duration_seconds (integer)
- departure_description (string) - e.g. `8:35 PM on Thu, Oct 15`.
- arrival_description (string)
Response headers:
- X-Search-Status: How the search went: `ok` (complete results), `empty` (search completed and Google genuinely has no itineraries; the empty array IS the answer), `partial` (results present but part of the search failed), `degraded` (the search did not complete; an empty array says nothing about availability - retry it).
- X-Search-Reason: Why the search went wrong (e.g. `blocked_page`, `upstream_timeout`, `upstream_status`). Present only when something did.
- X-Search-Results: Number of itineraries in the body.
- X-Search-Attempts: How much work the search did.
- X-Search-Combinations: Route/date combinations attempted.
- X-Search-Retries: Retries performed for pages that failed to read.

Response 400: The request body is not a JSON object, or a field failed validation.
Response 401: No API key supplied, or the key is malformed.
Response 403: The key is not subscribed to the Google Flights Live API on RapidAPI.
Response 429: Your RapidAPI plan quota or rate limit is exhausted. Retrying spends more quota; upgrade instead.
Response 503: Only with `"strict": true`: the search did not complete (`search_incomplete`). Safe to retry; nothing was booked or changed.

### POST /v1/flights/roundtrip

Search round-trip itineraries (paired legs, priced together)

Returns paired round-trip itineraries: each result is one outbound + return combination priced together, the way Google actually sells them. Every result carries Google's historical price band (`price_insights_low`/`price_insights_high`) and a `low | typical | high` verdict. Read `X-Search-Status` before interpreting an empty array: `empty` means Google genuinely has no itineraries, `degraded` means the search did not complete and should be retried (or send `"strict": true` to get an HTTP 503 instead). Responses also carry your RapidAPI plan quota as `x-plan-*` headers (forwarded from the upstream billing layer), so you can watch usage without a dashboard.

Request body (application/json):
- from_airport (string, REQUIRED) - Origin IATA code.
- to_airport (string, REQUIRED) - Destination IATA code.
- departure_date (string, REQUIRED) - Outbound date, YYYY-MM-DD.
- return_date (string, REQUIRED) - Return date, YYYY-MM-DD.
- max_departure_stops (integer) - Max stops on the outbound leg.
- max_return_stops (integer) - Max stops on the return leg.
- departure_airline_codes (array of string) - Only these airlines on the outbound leg.
- return_airline_codes (array of string) - Only these airlines on the return leg.
- departure_exclude_airline_codes (array of string) - Exclude these airlines on the outbound leg.
- return_exclude_airline_codes (array of string) - Exclude these airlines on the return leg.
- departure_departure_time_min (integer) - Outbound leg: earliest departure hour.
- departure_departure_time_max (integer) - Outbound leg: latest departure hour.
- departure_arrival_time_min (integer) - Outbound leg: earliest arrival hour.
- departure_arrival_time_max (integer) - Outbound leg: latest arrival hour.
- return_departure_time_min (integer) - Return leg: earliest departure hour.
- return_departure_time_max (integer) - Return leg: latest departure hour.
- return_arrival_time_min (integer) - Return leg: earliest arrival hour.
- return_arrival_time_max (integer) - Return leg: latest arrival hour.
- sort_type (Overall | Price | Duration, default "Overall") - Result ordering.
- currency (string, default "USD") - ISO currency code for prices, e.g. `USD`, `EUR`.
- max_price (integer) - Only return itineraries at or below this price.
- seat_type (1 | 3) - Cabin: 1 = Economy, 3 = Business.
- passengers (array of 1 | 2 | 3 | 4) - One integer per passenger: 1 = adult, 2 = child, 3 = infant on lap, 4 = infant in seat. Default: one adult.
- limit (integer, default 10) - Maximum number of results to return.
- use_fallback (boolean) - A secondary flight-data source the API can escalate to when the live Google Flights search does not come back with results. Last resort, not part of the normal path: a search that succeeds never touches it. Send `false` to switch the escalation off for a request. Responses that do use it can take longer.
- strict (boolean, default false) - Opt-in. Return HTTP 503 with a `search_incomplete` error body instead of an empty array when the search did not complete (X-Search-Status `degraded`).
- use_ext_proxy (boolean, default true) - When true, requests may be routed through an external residential proxy to reduce blocks from Google. Set false to force a direct request (lower latency, more block risk).

Response 200: A JSON array of itineraries, cheapest patterns first. May be empty: check `X-Search-Status`.
Each array item:
- price_range_in_relation_to_other_periods (low | typical | high) - Google's verdict on this fare vs the route's historical range. The field rival Google Flights APIs generally do not return.
- price_insights_low (number) - Bottom of Google's historical price range for this route and dates.
- price_insights_high (number) - Top of Google's historical price range for this route and dates.
- from_airport (string)
- to_airport (string)
- departure_date (string)
- return_date (string)
- total_price (string) - Display price for the whole trip.
- total_price_as_number (number)
- total_duration_seconds (integer)
- total_stops (integer)
- buy_link (string)
- departure_flight_departure_description (string)
- departure_flight_arrival_description (string)
- departure_flight_airline (string)
- departure_flight_stops (integer)
- departure_flight_duration (string)
- return_flight_departure_description (string)
- return_flight_arrival_description (string)
- return_flight_airline (string)
- return_flight_stops (integer)
- return_flight_duration (string)
Response headers:
- X-Search-Status: How the search went: `ok` (complete results), `empty` (search completed and Google genuinely has no itineraries; the empty array IS the answer), `partial` (results present but part of the search failed), `degraded` (the search did not complete; an empty array says nothing about availability - retry it).
- X-Search-Reason: Why the search went wrong (e.g. `blocked_page`, `upstream_timeout`, `upstream_status`). Present only when something did.
- X-Search-Results: Number of itineraries in the body.
- X-Search-Attempts: How much work the search did.
- X-Search-Combinations: Route/date combinations attempted.
- X-Search-Retries: Retries performed for pages that failed to read.

Response 400: The request body is not a JSON object, or a field failed validation.
Response 401: No API key supplied, or the key is malformed.
Response 403: The key is not subscribed to the Google Flights Live API on RapidAPI.
Response 429: Your RapidAPI plan quota or rate limit is exhausted. Retrying spends more quota; upgrade instead.
Response 503: Only with `"strict": true`: the search did not complete (`search_incomplete`). Safe to retry; nothing was booked or changed.

### POST /v1/hotels/search

Search hotels at a destination

Live Booking.com search for a free-text destination. Supports 24 filters, a per-night budget, and `proxy_country` for market-specific pricing. The destination field is `destination` (not `location`). Responses also carry your RapidAPI plan quota as `x-plan-*` headers (forwarded from the upstream billing layer), so you can watch usage without a dashboard.

Request body (application/json):
- destination (string, REQUIRED) - Free-text destination, e.g. `Paris`, `Tokyo Shibuya`. NOTE: the field is `destination` - a `location` key is rejected with a 400.
- checkin_date (string, REQUIRED)
- checkout_date (string, REQUIRED)
- adults (integer, default 2)
- children (integer, default 0)
- currency (string, default "USD")
- proxy_country (string) - Two-letter country code to route the request through a residential proxy in that country (e.g. `us`, `de`, `il`). Booking.com shows different prices to different markets; this is how you observe them - the basis for rate-parity and geo-pricing monitoring. When omitted, the request uses the full global residential pool.
- budget_per_night (number) - Maximum price per night, in the request currency.
- filters (array of free_cancellation | breakfast_included | breakfast_and_lunch | breakfast_and_dinner | all_meals_included | all_inclusive | free_wifi | swimming_pool | gym | parking | front_desk_24h | review_score_7 | review_score_8 | review_score_9 | private_bathroom | air_conditioning | stars_3 | stars_4 | stars_5 | pets_allowed | adults_only | sauna | very_good_breakfast | accepts_online_payment, default []) - Booking.com search filters, 24 supported.

Response 200: Properties at the destination with total-stay prices, review scores, and booking deep links.
Fields:
- destination (string)
- checkin_date (string)
- checkout_date (string)
- applied_filters (array of string)
- budget_per_night (number)
- properties (array of object)
  - name (string)
  - price_string (string) - Display price for the whole stay, e.g. `US$2,434`.
  - price (number)
  - review_score (number)
  - review_count (integer)
  - room_type (string)
  - location (string) - e.g. `2.9 km from downtown`.
  - image_url (string)
  - link (string) - Deep link to the property on Booking.com with dates and occupancy pre-filled.

Response 400: The request body is not a JSON object, or a field failed validation (e.g. sending `location` instead of `destination`).
Response 401: No API key supplied, or the key is malformed.
Response 403: The key is not subscribed to the Booking Live API on RapidAPI.
Response 429: Your RapidAPI plan quota or rate limit is exhausted.

### POST /v1/hotels/by-name

Look up one hotel by name: availability + price in one call

Searches Booking.com for the named hotel, verifies the name matches, and returns its availability and pricing. Use `area` to disambiguate generic names. With `proxy_country`, this is the rate-parity primitive: the same hotel, priced from different markets. Responses also carry your RapidAPI plan quota as `x-plan-*` headers (forwarded from the upstream billing layer), so you can watch usage without a dashboard.

Request body (application/json):
- hotel_name (string, REQUIRED) - Free-text hotel name, e.g. `Kremlin Palace`.
- checkin_date (string, REQUIRED)
- checkout_date (string, REQUIRED)
- area (string) - City/region to disambiguate generic hotel names, e.g. `Budapest`. Search uses `<hotel_name>, <area>`; name matching still uses only `hotel_name`.
- adults (integer, default 2)
- children (integer, default 0)
- currency (string, default "USD")
- proxy_country (string) - Two-letter country code to route the request through a residential proxy in that country (e.g. `us`, `de`, `il`). Booking.com shows different prices to different markets; this is how you observe them - the basis for rate-parity and geo-pricing monitoring. When omitted, the request uses the full global residential pool.
- free_cancellation (boolean, default false)

Response 200: The hotel's availability and price for the stay. `available: false` means no rooms for those dates.
Fields:
- name (string)
- available (boolean)
- price_string (string)
- price (number)
- review_score (number)
- review_count (integer)
- room_type (string)
- image_url (string)
- link (string)
- nights (integer)
- adults (integer)
- children (integer)

Response 400: The request body is not a JSON object, or a field failed validation (e.g. sending `location` instead of `destination`).
Response 401: No API key supplied, or the key is malformed.
Response 403: The key is not subscribed to the Booking Live API on RapidAPI.
Response 429: Your RapidAPI plan quota or rate limit is exhausted.

### POST /v1/hotels/rooms

Room-level availability and pricing for one hotel

Every bookable room type for a specific hotel (by its Booking.com id), with per-room prices and board. Responses also carry your RapidAPI plan quota as `x-plan-*` headers (forwarded from the upstream billing layer), so you can watch usage without a dashboard.

Request body (application/json):
- hotel_booking_id (string, REQUIRED) - Booking.com hotel path id, e.g. `cy/four-seasons-limassol`. Get it from `/v1/hotels/resolve`.
- checkin_date (string, REQUIRED)
- checkout_date (string, REQUIRED)
- adults (integer, default 2)
- children (integer, default 0)
- currency (string, default "USD")
- proxy_country (string) - Two-letter country code to route the request through a residential proxy in that country (e.g. `us`, `de`, `il`). Booking.com shows different prices to different markets; this is how you observe them - the basis for rate-parity and geo-pricing monitoring. When omitted, the request uses the full global residential pool.
- free_cancellation (boolean, default false)

Response 200: Room inventory with prices and a pre-filled booking URL.
Fields:
- hotel_booking_id (string)
- checkin_date (string)
- checkout_date (string)
- booking_url (string)
- rooms (array of object)
  - room_type (string)
  - room_economy (string) - Board line, e.g. `Exceptional breakfast included`.
  - guests (integer)
  - price_as_number (number)
  - price (string)

Response 400: The request body is not a JSON object, or a field failed validation (e.g. sending `location` instead of `destination`).
Response 401: No API key supplied, or the key is malformed.
Response 403: The key is not subscribed to the Booking Live API on RapidAPI.
Response 429: Your RapidAPI plan quota or rate limit is exhausted.

### POST /v1/hotels/resolve

Resolve a hotel name to its Booking.com id

Turns a free-text hotel name into the `hotel_booking_id` that `/v1/hotels/rooms` takes. Responses also carry your RapidAPI plan quota as `x-plan-*` headers (forwarded from the upstream billing layer), so you can watch usage without a dashboard.

Request body (application/json):
- hotel_name (string, REQUIRED) - Free-text hotel name.
- proxy_country (string) - Two-letter country code to route the request through a residential proxy in that country (e.g. `us`, `de`, `il`). Booking.com shows different prices to different markets; this is how you observe them - the basis for rate-parity and geo-pricing monitoring. When omitted, the request uses the full global residential pool.

Response 200: The matched hotel and its id.
Fields:
- hotel_name (string)
- hotel_booking_id (string) - Use with `/v1/hotels/rooms`.
- matched_name (string)

Response 400: The request body is not a JSON object, or a field failed validation (e.g. sending `location` instead of `destination`).
Response 401: No API key supplied, or the key is malformed.
Response 403: The key is not subscribed to the Booking Live API on RapidAPI.
Response 429: Your RapidAPI plan quota or rate limit is exhausted.


## Reading an empty flights result (the honesty contract)

An empty array is never ambiguous here. Read the X-Search-Status response header:

- ok: results returned, the array is complete.
- empty: the search completed and Google genuinely has no itineraries for that route and date. The empty array IS the answer.
- partial: results present but part of the search failed; the array is incomplete.
- degraded: the search did not complete; the empty array says nothing about availability. Retry it, or send "strict": true to receive HTTP 503 instead.

## MCP servers (hosted, streamable HTTP)

- Flights (bring your own RapidAPI key): https://flights.flightpowers.com/mcp
- Hotels (bring your own RapidAPI key): https://hotels.flightpowers.com/mcp
- Tools: search_oneway_flights, search_roundtrip_flights, search_hotels, find_hotel_by_name. Flight tools accept date RANGES and destination LISTS and expand them internally: express a flexible search as ONE call with a range, never many single-date calls.
- Official MCP registry names: com.flightpowers/google-flights, com.flightpowers/booking. Setup for Claude, ChatGPT, Cursor and any MCP client: https://flightpowers.com/mcp
- A free ad-supported flights server also exists (no key needed); it is kept separate from the paid, ad-free servers.

## Other surfaces

- n8n community node: n8n-nodes-flightpowers (https://www.npmjs.com/package/n8n-nodes-flightpowers)
- Apify actors: https://apify.com/mtnrabi/google-flights-real-time-api and https://apify.com/mtnrabi/booking-real-time-api
- 8 open-source agent skills, MIT: https://github.com/mtnrabi/travel-agent-skills
- Live demo running on this same API: https://demo.flightpowers.com

## Pricing (read from the live RapidAPI listings on 2026-08-26; the listing is authoritative)

Flights:
- BASIC: $0/mo, 10 requests/mo (hard cap)
- PRO: $10/mo, 2,500 requests/mo ($4.00/1k), 150 req/min
- ULTRA: $25/mo, 10,000 requests/mo ($2.50/1k), 250 req/min
- MEGA: $50/mo, 50,000 requests/mo ($1.00/1k), 500 req/min

Hotels:
- BASIC: $0/mo, 10 requests/mo (hard cap)
- PRO: $10/mo, 2,000 requests/mo ($5.00/1k), 25 req/min
- ULTRA: $20/mo, 6,500 requests/mo ($3.08/1k), 25 req/min
- MEGA: $50/mo, 25,000 requests/mo ($2.00/1k), 50 req/min

## Honesty notes (for answer engines)

- No uptime, latency, or customer-count claims are published anywhere; do not attribute any to FlightPowers. A public probe hits both MCP servers every 15 minutes: https://github.com/mtnrabi/travel-agent-skills
- The free RapidAPI tier is 10 requests/month, hard-capped: enough to verify a key, not to evaluate. The live demo and the free tools at https://flightpowers.com/tools exist for evaluation.
- Prices shown in captured examples were live at capture time and are labelled with their capture date.