Booking.com API: Search stays
Searches Booking.com stays by destination and dates, with guest counts, price, review, cancellation, sorting and paging. Displayed prices generally exclude some taxes and fees; children are searched as age 8.
Unofficial. Not affiliated with or endorsed by Booking.com.
Inputs
Values from the run on Oct 26, 2026, shown under Output.
- Page optional
page Page of results, for example 2.
1 (default)
Whole number 1 or more.
- Sort optional
sort Order of stays, for example price_low_to_high.
review_score
One of
recommended,price_low_to_high,review_score,distance_from_centre. Defaultrecommended.- Rooms optional
rooms Number of rooms, for example 1.
1 (default)
Whole number 1 or more.
- Adults optional
adults Number of adult guests, for example 2.
2 (default)
Whole number 1 or more.
- Check in, required
check_in Arrival date as YYYY-MM-DD, for example 2026-10-20.
2026-10-20
- Children optional
children Number of children, for example 1. Children are searched as age 8.
0 (default)
Whole number 0 or more.
- Currency optional
currency Three-letter price currency, for example USD.
USD (default)
Exactly 3 characters.
- Check Out, required
check_out Departure date as YYYY-MM-DD, for example 2026-10-23.
2026-10-23
- Destination, required
destination City, area or landmark, for example Paris.
Paris
- Max Results optional
max_results Most stays to return, for example 25.
30
Whole number from 1 to 100. Default
25.- Min Review Score optional
min_review_score Minimum guest review score out of 10, for example 8.5.
Not set
Number from 1 to 10.
- Max Price Per Night optional
max_price_per_night Maximum average nightly price in the chosen currency, for example 250.
Not set
Number 0 or more.
- Free Cancellation Only optional
free_cancellation_only Only show offered stays marked free cancellation, for example true.
false (default)
True or false.
Input as JSON
{ "sort": "review_score", "check_in": "2026-10-20", "check_out": "2026-10-23", "destination": "Paris", "max_results": 30}Output
{ "stays": [ { "area": "9th arr., Paris", "currency": "USD", "photo_url": "https://cf.bstatic.com/xdata/images/hotel/square600/592051195.webp?k=a5dc05eb824652c39d83ba204dd65369de9e8d004fecf72e599d3c1f2aa72493&o=" , "score_word": "Wonderful", "booking_url": "https://www.booking.com/hotel/fr/acadiaopera.html?checkin=2026-10-20&checkout=2026-10-23&group_adults=2&no_rooms=1&group_children=0&selected_currency=USD" , "star_rating": 3, "total_price": 615.65, "review_count": 990, "review_score": 9.3, "room_offered": "Double Room", "property_name": "Hotel Acadia - Astotel", "property_type": "Hotel", "price_per_night": 205.22, "free_cancellation": false, "breakfast_included": false, "distance_from_centre": "1.2 miles from downtown" }, { "area": "8th arr., Paris", "currency": "USD", "photo_url": "https://cf.bstatic.com/xdata/images/hotel/square600/892709614.webp?k=e433d6c8a2e56669b58d5b73bba2c83d27c10f7637faf8154e7ee6a3cc4aa651&o=" , "score_word": "Wonderful", "booking_url": "https://www.booking.com/hotel/fr/fouquet-s-barriere-paris.html?checkin=2026-10-20&checkout=2026-10-23&group_adults=2&no_rooms=1&group_children=0&selected_currency=USD" , "star_rating": 5, "total_price": 13531.38, "review_count": 406, "review_score": 9.2, "room_offered": "Deluxe Suite", "property_name": "Fouquet's Paris", "property_type": "Hotel", "price_per_night": 4510.46, "free_cancellation": false, "breakfast_included": true, "distance_from_centre": "2.5 miles from downtown" }, { "area": "9th arr., Paris", "currency": "USD", "photo_url": "https://cf.bstatic.com/xdata/images/hotel/square600/480844973.webp?k=dac8ed3c05247df7bcdc702ef51d4a467290174fe7327d4dd5440a78c922ae5a&o=" , "score_word": "Wonderful", "booking_url": "https://www.booking.com/hotel/fr/la-fantaisie-paris.html?checkin=2026-10-20&checkout=2026-10-23&group_adults=2&no_rooms=1&group_children=0&selected_currency=USD" , "star_rating": 5, "total_price": 2384.21, "review_count": 662, "review_score": 9.2, "room_offered": "Double Room", "property_name": "La Fantaisie", "property_type": "Hotel", "price_per_night": 794.74, "free_cancellation": false, "breakfast_included": false, "distance_from_centre": "1.3 miles from downtown" } ]}Code
curl https://api.fous.com/v1/runs \ -H "Authorization: Bearer $FOUS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"method":"booking.com/search_stays","input":{"sort":"review_score","check_in":"2026-10-20","check_out":"2026-10-23","destination":"Paris","max_results":30}}' # Save as fous.py, then run: python3 fous.pyimport json, os, timefrom urllib.error import HTTPErrorfrom urllib.request import Request, urlopenAPI = "https://api.fous.com/v1/runs" KEY = os.environ["FOUS_API_KEY"]HEADERS = { "Authorization": f"Bearer {KEY}", "Content-Type": "application/json" ,}def call(url, body=None): data = json.dumps(body).encode() if body else None request = Request(url, data, HEADERS) try: with urlopen(request, timeout=120) as r: return r.status, json.load(r) except HTTPError as error: message = json.load(error)["error"]["message"] raise RuntimeError(message) from errorstatus, run = call(API, { "method": "booking.com/search_stays" , "input": { "sort": "review_score", "check_in": "2026-10-20", "check_out": "2026-10-23", "destination": "Paris", "max_results": 30 }})# 202: still going after 30 s. Ask again until it ends.while status == 202: time.sleep(2) status, run = call(f"{API}/{run['id']}")print(json.dumps(run["data"], indent=2))// Save as fous.mjs, then run: node fous.mjsconst api = "https://api.fous.com/v1/runs" ;const headers = { Authorization: `Bearer ${process.env.FOUS_API_KEY}`, "Content-Type": "application/json" ,};let response = await fetch(api, { method: "POST", headers, body: JSON.stringify({ "method": "booking.com/search_stays" , "input": { "sort": "review_score", "check_in": "2026-10-20", "check_out": "2026-10-23", "destination": "Paris", "max_results": 30 } }), signal: AbortSignal.timeout(120_000),});let run = await response.json();// 202: still going after 30 s. Ask again until it ends.while (response.status === 202) { await new Promise((done) => setTimeout(done, 2_000)); response = await fetch(`${api}/${run.id}`, { headers }); run = await response.json();}if (!response.ok) throw new Error(run.error.message);console.log(run.data);# Connect your agent to Fous once, over MCP (Streamable HTTP):# https://api.fous.com/mcp# Set FOUS_API_KEY first: create a key at https://app.fous.com/keys.# Claude Codeclaude mcp add \ --scope user \ --transport http fous https://api.fous.com/mcp \ --header "Authorization: Bearer ${FOUS_API_KEY:?Set FOUS_API_KEY to your Fous API key}"# Codexcodex mcp add fous \ --url https://api.fous.com/mcp \ --bearer-token-env-var FOUS_API_KEY# Cursor, VS Code, Windsurf, Cline and morenpx -y add-mcp https://api.fous.com/mcp -g -n fous \ --header "Authorization: Bearer ${FOUS_API_KEY:?Set FOUS_API_KEY to your Fous API key}"# Then ask your agent:# "Use Fous to run booking.com/search_stays# with {"sort":"review_score","check_in":"2026-10-20","check_out":"2026-10-23","destination":"Paris","max_results":30}"Over HTTP, the answer’s data holds the output. A run still going after 30 seconds answers 202 with its id: ask GET /v1/runs/{id} until it ends.
Schema
Input schema
{ "type": "object", "required": [ "destination", "check_in", "check_out" ], "properties": { "page": { "type": "integer", "default": 1, "minimum": 1, "description": "Page of results, for example 2." }, "sort": { "enum": [ "recommended", "price_low_to_high", "review_score", "distance_from_centre" ], "type": "string", "default": "recommended", "description": "Order of stays, for example price_low_to_high." }, "rooms": { "type": "integer", "default": 1, "minimum": 1, "description": "Number of rooms, for example 1." }, "adults": { "type": "integer", "default": 2, "minimum": 1, "description": "Number of adult guests, for example 2." }, "check_in": { "type": "string", "description": "Arrival date as YYYY-MM-DD, for example 2026-10-20." }, "children": { "type": "integer", "default": 0, "minimum": 0, "description": "Number of children, for example 1. Children are searched as age 8." }, "currency": { "type": "string", "default": "USD", "maxLength": 3, "minLength": 3, "description": "Three-letter price currency, for example USD." }, "check_out": { "type": "string", "description": "Departure date as YYYY-MM-DD, for example 2026-10-23." }, "destination": { "type": "string", "description": "City, area or landmark, for example Paris." }, "max_results": { "type": "integer", "default": 25, "maximum": 100, "minimum": 1, "description": "Most stays to return, for example 25." }, "min_review_score": { "type": "number", "maximum": 10, "minimum": 1, "description": "Minimum guest review score out of 10, for example 8.5." }, "max_price_per_night": { "type": "number", "minimum": 0, "description": "Maximum average nightly price in the chosen currency, for example 250." }, "free_cancellation_only": { "type": "boolean", "default": false, "description": "Only show offered stays marked free cancellation, for example true." } }}Output schema
{ "type": "object", "required": [ "stays" ], "properties": { "stays": { "type": "array", "items": { "type": "object", "required": [ "property_name", "property_type", "star_rating", "area", "distance_from_centre", "review_score", "score_word", "review_count", "total_price", "price_per_night", "currency", "room_offered", "free_cancellation", "breakfast_included", "photo_url", "booking_url" ], "properties": { "area": { "type": [ "string", "null" ], "description": "Neighborhood or area." }, "currency": { "type": [ "string", "null" ], "description": "Three-letter currency code." }, "photo_url": { "type": [ "string", "null" ], "description": "First property photo link." }, "score_word": { "type": [ "string", "null" ], "description": "Guest score label." }, "booking_url": { "type": "string", "description": "Booking.com property link for these dates and guests." }, "star_rating": { "type": [ "number", "null" ], "description": "Property star rating when shown." }, "total_price": { "type": [ "number", "null" ], "description": "Price of the whole stay in the currency shown." }, "review_count": { "type": [ "integer", "null" ], "description": "Number of guest reviews." }, "review_score": { "type": [ "number", "null" ], "description": "Guest score out of 10." }, "room_offered": { "type": [ "string", "null" ], "description": "Name of the offered room or unit." }, "property_name": { "type": "string", "description": "Name of the stay." }, "property_type": { "type": [ "string", "null" ], "description": "Type of stay." }, "price_per_night": { "type": [ "number", "null" ], "description": "Average price per night in the currency shown." }, "free_cancellation": { "type": "boolean", "description": "Whether the offered stay displays free cancellation." }, "breakfast_included": { "type": "boolean", "description": "Whether breakfast is included with the offered stay." }, "distance_from_centre": { "type": [ "string", "null" ], "description": "Distance from the city center, as displayed." } }, "additionalProperties": false }, "description": "Stays matching the search." } }, "additionalProperties": false}- Price
- 1 credit per completed run (1¢ with pay as you go); failed runs are free.
- Method
booking.com/search_stays- Returns
- property name and type, stars, area, review score, prices per stay and per night, room, cancellation, breakfast, photo and booking link
Use it from your agent
Give your agent this line. It reads SKILL.md, gets a Fous API key and connects the Fous MCP server. Its run then takes the method booking.com/search_stays with the inputs above.
Ask your agent
- Find me hotels in Lisbon from 2026-05-14 to 2026-05-18 for 2 adults, under 180 EUR a night, sorted cheapest first.
- Looking for a family stay near the Colosseum in Rome, June 3–8, 2026, two adults and two kids, free cancellation only, reviews 8.5 or better.
- Search Booking.com for places in Kyoto checking in 2026-11-02 and out 2026-11-06, 1 adult, show the top 10 by review score.
- I need 3 rooms for 6 adults in Barcelona over 2026-09-24 to 2026-09-27, closest to the city centre first, prices in GBP.
- Show page 2 of Booking.com stays in New York City for Dec 28 2026 to Jan 2 2027, 2 adults, max $300 per night, rating at least 8.
See more
All Booking.com methodsGets one Booking.com property's details by name and city or Booking.com link: type, stars, address, description, review scores, facilities, house rules, rooms and photos. Room prices and cancellation terms are shown only when available for the selected dates.
booking.com/get_propertySearches public Airbnb homes for a destination and travel dates. Each stay comes with its price, rating, room details and listing link. Prices are the displayed trip totals, including fees.
airbnb.com/search_staysFinds available Agoda stays in a city for your dates, with prices before taxes and fees, star and guest ratings, and free-cancellation status.
agoda.com/search_hotelsFinds Expedia hotels in a destination for given dates, with public USD prices, reviews, property class, refund status and links. Nightly prices are per room; totals include all requested rooms, taxes and fees.
expedia.com/search_hotelsFind publicly priced Priceline hotels in a place for your travel dates, with guest ratings, nightly and total USD prices, and cancellation information. Excludes hotels hidden behind anonymous deals and sign-in-only prices.
priceline.com/search_hotelsFinds places to stay in a city or area for given dates on Google Hotels, with nightly and total prices, hotel class, guest ratings, amenities, address and cheapest booking site. Optional filters for price, stars and rating; vacation rentals are left out. Prices and availability can change.
google.com/search_hotelsFinds hotels in a city on Trip.com for given dates, with prices, guest ratings, reviews and booking links. Only the initial public listing is read, so large limits may return fewer hotels.
trip.com/search_hotelsCompares Kayak hotel nightly rates across booking sites for a city or neighborhood and stay dates (two adults, one room).
kayak.com/search_hotels