Hotel Prices API
Point of sale and display settings
Pass market=ES for Spain (Spanish and EUR defaults) or market=US for the United States (English and USD). The optional language and currency parameters override these defaults. Market is an ISO 3166-1 two-letter country code; unknown codes and conflicting market/country_market values return 400.
Legacy country_market remains supported and keeps English/USD defaults. Omitting both retains US targeting and English/USD. For search by URL, explicit language/currency query parameters override values embedded in the URL; explicit URL values override market defaults.
Defaults: ES es/EUR, US en-us/USD, GB en-gb/GBP, DE de/EUR, FR fr/EUR, IT it/EUR, PT pt-pt/EUR, NL nl/EUR, IE en-gb/EUR, CA en-us/CAD, AU en-gb/AUD, JP ja/JPY. Other valid countries use en-us/USD unless overridden.
data.effective_market reports requested_country, nullable targeted_country, language, and currency. Targeting is best-effort: country_verified is false and verified_country is null because the response does not independently verify geography. A null target means country targeting was not applied. MCP returns the same object as effective_market.
{"requested_country":"ES","targeted_country":"ES","country_verified":false,"verified_country":null,"language":"es","currency":"EUR"}
For prices, total_price_value follows the displayed gross basis and is not guaranteed to include every charge. taxes_and_charges_value is the included portion (gross minus net); inspect tax_breakdown[].included for excluded taxes.
Compare the same stay, occupancy, room, rate conditions and currency. Market can change tax inclusion and displayed totals without changing the all-in price; it does not guarantee a discount or availability. In the verified Spain/US comparison, the same rate displayed US$455 including taxes in Spain and $341 excluding taxes in the US, with the same $455.46 all-in amount.
Get real-time room pricing, tax breakdowns, and availability for any Booking.com hotel.
Overview
Live Pricing Data
Returns real-time prices with tax breakdowns, cancellation policies, meal plans, and bundle extras for all available rooms.
The Hotel Prices endpoint provides comprehensive pricing information for a specific Booking.com hotel, including per-night and total costs, detailed tax breakdowns, and individual room options with cancellation policies and meal plans.
Sold-out stays
A stay that is independently confirmed as sold out returns HTTP 200 with is_soldout: true, rooms: [], and available_rooms_count: 0. If empty inventory cannot be confirmed as sold out, the API returns a 502 instead of guessing.
Endpoint URL
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| hotel_id | string | Required | Booking.com hotel ID (numeric, up to 10 digits) |
| check_in | string | Required | Check-in date (YYYY-MM-DD) |
| check_out | string | Required | Check-out date (YYYY-MM-DD) |
| adults | integer | Optional | Number of adults (1-10, default: 2) |
| rooms | integer | Optional | Number of rooms (1-10, default: 1) |
| currency | string | Optional | 3-letter currency override (market default, otherwise USD) |
| country_market | string (ISO-3166) | Optional |
Legacy two-letter country target (default: US), preserving English/USD defaults. It must match market if both are supplied. The echo is a request value, not verified geography.
|
| children | integer | Optional | Number of children, 0–10; default 0. Supply one age per child. |
| children_ages | string | Optional | Comma-separated integer ages 0–17, for example 5,8. Required when children is positive; the age count must equal children. Omit or leave empty for zero children. |
Response Structure
Pricing Summary
Shows the cheapest available room. See the rooms array for all room categories and prices.
price_per_night/price_per_night_value- Formatted and numeric price per nighttotal_price/total_price_value- Total stay costnet_price/net_price_value- Price before taxestaxes_and_charges/taxes_and_charges_value- Tax totalcurrency- Currency code
Tax Breakdown
name- Tax nametype- Tax typepercentage- Tax rateamount/amount_value- Tax amountincluded- Whether tax is already included in the price
Rooms
Array of all available room categories with individual pricing. Each entry represents a bookable room option.
block_id/room_name- Room identifier and nameis_refundable/cancellation_policy- Cancellation detailsbreakfast_included/meal_plan- Meal informationprice_per_night/total_price- Room-level pricingbundle_extras- Included extras (WiFi, gym, etc.)
Sold-out response
Confirmed sold-out dates use the normal success schema: is_soldout is true, rooms is empty, and available_rooms_count is zero. Pricing summary values are null because there is no bookable rate.
Best Practices
Date Selection
Prices vary significantly by date. Always provide accurate check-in/check-out dates to get reliable pricing.
Implementation Tips
- Use both formatted strings and numeric values for flexible display
- Check
is_soldoutbefore displaying pricing - Display the tax breakdown for price transparency
- Highlight cancellation policies prominently for user confidence
Error handling and status codes
Status codes: 200 on success; errors use non-2xx (400, 500, 502) with Problem Details.
- 400
INVALID_HOTEL_ID: Hotel ID is not numeric or exceeds 10 digits. - 400
INVALID_DATE_FORMAT: Dates are not in YYYY-MM-DD format. - 400
INVALID_DATES: Check-out is before check-in or stay exceeds 90 nights. - 400
INVALID_CURRENCY: Currency is not a 3-letter code. - 502
UPSTREAM_ERROR: Upstream request or parsing failed, including empty inventory that could not be confirmed as sold out. - 500
INTERNAL_ERROR: Unexpected processing error.
Error responses (Problem Details)
All Booking.com hotel endpoints return errors using RFC 7807 Problem Details.
{
"type": "https://api.stayapi.com/errors/invalid-url",
"title": "Invalid URL",
"status": 400,
"detail": "Parameter 'url' must be a full Booking.com hotel URL of the form https://www.booking.com/hotel/{cc}/{slug}.html.",
"error_code": "INVALID_URL",
"provided": "baan-coconut"
}
Media type: application/problem+json
Standard fields: type, title, status, detail
Extensions: error_code and any endpoint-specific fields
2xx policy: 2xx is returned only when data extraction succeeds.
Family occupancy
For two adults and a child aged eight, send adults=2&children=1&children_ages=8. Multiple ages use a single CSV value, for example children=2&children_ages=5%2C8. Missing ages, count mismatches, noninteger ages and ages outside 0–17 return HTTP 400 Problem Details with error_code: INVALID_OCCUPANCY. Invalid count types or counts outside 0–10 return HTTP 422. Adults-only requests can omit both child parameters.
Each data.rooms[] includes fits_requested_occupancy: true means that one rate accommodates the entire requested party, false means it does not, and null means the fit is unknown. Room alternatives may accommodate only part of your party. The prices summary selects a verified full-family rate; if none can be verified, prices returns HTTP 502 instead of a misleading family quote. Prices describe one room for the stay, not a combined multiroom reservation total. The rooms parameter does not establish an allocation of guests across rooms.
Rate labels
data.pricing_summary and each data.rooms[] item includes labels (an array of readable strings), genius_discount_pct (a number or null), and is_mobile_rate (a boolean). Labels describe the quoted rate, for example Mobile rate or Bonus savings. Unlabelled rates return [].
These are anonymous public quotes. A property Genius badge alone does not prove a Genius discount on this rate. A null percentage means no rate-specific percentage was observed; is_mobile_rate: false means no explicit mobile-rate marker was observed. Labels can vary by market and occupancy and do not guarantee eligibility for logged-in member prices. Existing discount fields remain available.