--- title: "Booking.com Reviews API: Hotel Review Scores as JSON" description: "Pull Booking.com review scores and guest reviews as JSON with two GET calls at 1 credit each. Parameters, sorting, paging and the cost of covering a city." url: https://perceptlayer.com/blog/booking-com-reviews-api-json --- [Blog](https://perceptlayer.com/blog) / [API guides](https://perceptlayer.com/blog/category/api-guides) # Booking.com Reviews API: Hotel Review Scores as JSON 22 Oct 2026 Perceptlayer 7 min read Two endpoints return Booking.com review data as JSON. `GET /v1/booking/review-scores` returns a hotel's review scores, and `GET /v1/booking/reviews` returns its guest reviews, sortable by date or score. You identify the hotel with its Booking.com URL or a country code plus slug, and each successful call costs 1 credit. This guide covers the parameters, how to list the hotels in a city first, and what covering a whole city costs. It's about reviews. For prices and rooms, see the [Booking.com hotel prices guide](https://perceptlayer.com/blog/booking-com-hotel-prices-api). ## Key takeaways - `/v1/booking/review-scores` and `/v1/booking/reviews` both cost 1 credit per successful call; failed calls cost nothing and return `X-Credits-Used: 0`. - Identify a hotel with `url`, or with `country` (two letters) and `slug`, such as `country=fr&slug=royal-saint-michel`. - `reviews` takes `page`, `limit` and `sort` ( `recent_desc`, `recent_asc`, `score_desc`, `score_asc`) so you can page through a hotel's reviews. - To cover a city, list its hotels with `/v1/booking/prices`, then call `review-scores` once per hotel: 25 hotels is 1 + 25 = 26 credits. - Free accounts get 1,000 credits a month with no credit card, enough for that city run about 38 times. ## Which endpoints return Booking.com review data? Booking.com review data lives in four endpoints of the [Booking.com API](https://perceptlayer.com/apis/booking). `review-scores` returns the score data for one hotel, `reviews` returns the individual guest reviews, `search` lists hotels for a destination, and `prices` returns a hotel list with a `review_score` string for every hotel. All return JSON, and each call is 1 credit. | Endpoint | Returns | Use it for | Credits | | --- | --- | --- | --- | | `GET /v1/booking/review-scores` | Review Scores | A hotel's review scores; accepts optional dates and party size | 1 | | `GET /v1/booking/reviews` | Reviews | Guest reviews, paged and sorted | 1 | | `GET /v1/booking/search` | Search | Listing hotels for a destination (response not recorded) | 1 | | `GET /v1/booking/prices` | Prices | Hotel list with a `review_score` per hotel (recorded) | 1 | The pages for [Review Scores](https://perceptlayer.com/apis/booking/review-scores) and [Reviews](https://perceptlayer.com/apis/booking/reviews) list the full field set, and each has a playground where you can run a real call with your key. We haven't recorded a response for `review-scores` or `reviews`, so this guide doesn't show their fields. Run one in the [playground](https://perceptlayer.com/apis/booking) to see exactly what comes back before you build on it. ## How do you call the review scores endpoint? Send a GET request to `/v1/booking/review-scores` with the hotel identified by `url`, or by `country` and `slug`. Nothing is required by the schema, but without a hotel identifier there is nothing to look up. Add your key in the `X-API-Key` header and the call costs 1 credit on success. ```bash curl "https://api.perceptlayer.com/v1/booking/review-scores?country=fr&slug=royal-saint-michel" \ -H "X-API-Key: $API_KEY" ``` The `country` and `slug` pair comes straight from a hotel URL. In `https://www.booking.com/hotel/fr/royal-saint-michel.html`, `fr` is the country and `royal-saint-michel` is the slug. You can also pass the whole address as `url`. If you don't have a key yet, [get a free API key](https://perceptlayer.com/signup). Authentication is covered in the [authentication docs](https://docs.perceptlayer.com/authentication). ### Review scores parameters | Parameter | Type | Notes | | --- | --- | --- | | `url` | string | Booking.com hotel URL, up to 4096 characters | | `country` | string | Two-letter country code, up to 2 characters | | `slug` | string | Hotel slug, up to 255 characters | | `checkin`, `checkout` | string | Stay dates | | `group_adults`, `group_children`, `no_rooms` | integer | Party size and rooms | | `lang` | string | Language, up to 10 characters | | `currency` | string | Currency, up to 3 characters | The dates, party and currency parameters are optional. If you pass `checkin`, `checkout` and the party size, use the same values you use in your other Booking.com calls so the requests match. ## How do you fetch guest reviews and sort them? Call `GET /v1/booking/reviews` with the same hotel identifiers plus `page`, `limit` and `sort`. Sorting by `score_asc` puts the lowest-rated reviews first, which is usually where the useful complaints are. Each call returns one page and costs 1 credit, so paging costs 1 credit per page. ```bash curl "https://api.perceptlayer.com/v1/booking/reviews?country=fr&slug=royal-saint-michel&sort=score_asc&page=1&limit=10" \ -H "X-API-Key: $API_KEY" ``` | Parameter | Type | Allowed values | | --- | --- | --- | | `url` | string | Up to 4096 characters | | `country` | string | Up to 2 characters | | `slug` | string | Up to 255 characters | | `lang` | string | Up to 10 characters | | `currency` | string | Up to 3 characters | | `page` | integer | Page number | | `limit` | integer | Reviews per page | | `sort` | string | `recent_desc`, `recent_asc`, `score_desc`, `score_asc` | We haven't documented defaults for `page` or `limit`, so set both explicitly and check the response, rather than assuming a page size. When you loop, stop on an empty page. The [pagination guide](https://perceptlayer.com/blog/paginate-web-data-api-python) shows a safe loop pattern. ## How do you get review scores for every hotel in a city? List the city's hotels with `prices`, then call `review-scores` for each hotel in the result. The `prices` response is the one we've recorded, and it returns each hotel's `url`, so you never build slugs by hand. Total cost is 1 credit for the list plus 1 credit per hotel. If you don't know the destination ID, `GET /v1/booking/destinations` takes a required `q` parameter; the [Destinations page](https://perceptlayer.com/apis/booking/destinations) has the details. The `dest_id` and `dest_type` parameters are optional on `prices`, and the example below uses the Paris values from the recorded request. `GET /v1/booking/search` is an alternative way to list hotels, but we haven't recorded its response, so check its list field in the playground before relying on it. ```bash curl "https://api.perceptlayer.com/v1/booking/prices?ss=Paris&checkin=2026-11-20&checkout=2026-11-23&group_adults=2&dest_id=-1456928&dest_type=city" \ -H "X-API-Key: $API_KEY" ``` This is a recorded excerpt of that call, for Paris, 20 to 23 November 2026, two adults: ```json { "success": true, "data": { "title": "Booking.com: hotels in Paris", "prices": [ { "name": "Royal Saint Michel", "url": "https://www.booking.com/hotel/fr/royal-saint-michel.html", "price": "$351.05", "review_score": "8.8", "location": "3 Boulevard Saint Michel, Paris", … }, … ], "total_prices": 25, "parsed": true }, … } ``` Note that `review_score` is a string ( `"8.8"`), so convert it before you sort or average. If a single list is enough, that field already answers "which hotels score highest" for one credit. Use `review-scores` and `reviews` when you need more than the headline number. ### A script for the whole city This Python script lists the city with `prices`, then fetches `review-scores` for each hotel URL and prints the JSON it gets back. It needs `requests` and your key in `API_KEY`. It reads the hotel list from `data.prices`, as in the recorded response above, and waits one second between calls to stay within the free tier's 1 request a second. ```python import os import time import requests BASE = "https://api.perceptlayer.com" HEADERS = {"X-API-Key": os.environ["API_KEY"]} prices = requests.get( f"{BASE}/v1/booking/prices", headers=HEADERS, params={ "ss": "Paris", "checkin": "2026-11-20", "checkout": "2026-11-23", "group_adults": 2, "dest_id": -1456928, "dest_type": "city", }, timeout=60, ).json() results = [] for hotel in prices["data"]["prices"]: time.sleep(1) r = requests.get( f"{BASE}/v1/booking/review-scores", headers=HEADERS, params={"url": hotel["url"]}, timeout=60, ) if r.status_code != 200: print(hotel["name"], r.status_code, r.json()["error"]["code"]) continue results.append({"name": hotel["name"], "url": hotel["url"], "scores": r.json()}) print(hotel["name"], r.headers["X-Credits-Used"], r.headers["X-Credits-Remaining"]) print(results) ``` Every successful response carries `X-Credits-Used` and `X-Credits-Remaining`, so the loop doubles as a running spend check, and `results` holds each hotel's `review-scores` response for you to save or inspect. Errors come back as a status plus `{"error": {"code", "message", "request_id"}}`; see the [error docs](https://docs.perceptlayer.com/errors). ## What does it cost to pull reviews for a city? Each call is 1 credit, so cost is a count of calls. Covering the 25 hotels in the recorded Paris result with one `review-scores` call each is 1 list call + 25 calls = 26 credits. Adding 3 pages of reviews for each hotel adds 25 × 3 = 75 credits, for 101 in total. | Job | Calls | Credits | | --- | --- | --- | | List the city once with `prices` | 1 | 1 | | `review-scores` for 25 hotels | 25 | 25 | | 3 pages of `reviews` for 25 hotels | 75 | 75 | | Total | 101 | 101 | The free tier is 1,000 credits a month after you verify an email, with no credit card. That covers the 101-credit run nine times with credits to spare (9 × 101 = 909). Failed calls cost nothing, and purchased credits last 12 months. For what credits cost, see [pricing](https://perceptlayer.com/pricing) and the [credits docs](https://docs.perceptlayer.com/credits). Free accounts get 1 request a second, so a 26-call run takes about half a minute plus the time each call takes when you pace it as the script does. A 429 response carries a `Retry-After` header with the seconds to wait. The [rate limits docs](https://docs.perceptlayer.com/rate-limits) cover the rest. Lost replies after a timeout may have been billed, which the [retry guide](https://perceptlayer.com/blog/retry-web-api-calls-without-paying-twice) explains. ## When should you use the official Booking.com API instead? Booking.com has its own developer program, and it's worth a look first: [Booking.com for developers](https://developers.booking.com/) documents the API products it offers and how to get started. A web data API fits when you want public review data in the same JSON shape as the rest of your sources. Data is collected from publicly available sources and returned as found at the time of the call, so a hotel's score is whatever the page showed when you asked. Store the `scraped_at` value from `meta` with every score you keep; it records when the call ran. The page itself is the primary source: for example, the [Royal Saint Michel listing](https://www.booking.com/hotel/fr/royal-saint-michel.html) is what the recorded call reads. Related guides: the [Yelp reviews guide](https://perceptlayer.com/blog/yelp-reviews-api-json) and the [Airbnb listings guide](https://perceptlayer.com/blog/airbnb-listings-data-api) follow the same pattern for other travel and local sources, and the [Travel APIs](https://perceptlayer.com/verticals/travel) page lists the rest. To try a call first, open the playground on the [Booking.com API page](https://perceptlayer.com/apis/booking), pick Review Scores and run it with your key. ## APIs in this post - [Booking.com **1 credit per call** · 11 endpoints](https://perceptlayer.com/apis/booking) ## Frequently asked questions ### Does the Booking.com reviews API need a Booking.com account? No. You send your Perceptlayer key in the `X-API-Key` header, and the hotel is identified by `url` or by `country` and `slug`. Keys start with `sk_live_`. If a header isn't possible, you can pass the `api_key` query parameter instead. ### How much does one Booking.com review call cost? A successful call to `review-scores` or `reviews` costs 1 credit. A failed call costs nothing and returns `X-Credits-Used: 0`. Pulling 3 pages of reviews for one hotel is 3 credits. The free tier gives you 1,000 credits a month, and [pricing](https://perceptlayer.com/pricing) shows what packs cost. ### Can I sort reviews by lowest score? Yes. Set `sort=score_asc` on `/v1/booking/reviews` for the lowest scores first. The other values are `score_desc`, `recent_desc` and `recent_asc`. Combine `sort` with `page` and `limit` to walk through a hotel's reviews, at 1 credit per page. ### How do I find a hotel's slug? Take it from the hotel's Booking.com URL. In `https://www.booking.com/hotel/fr/royal-saint-michel.html`, the country is `fr` and the slug is `royal-saint-michel`. The `prices` response also returns each hotel's full `url`, which you can pass directly as the `url` parameter. ### Can an AI agent call these endpoints? Yes. The MCP server at `https://api.perceptlayer.com/mcp` exposes `search_endpoints`, `get_endpoint` and `call_endpoint`. The first two only look up the catalogue and cost nothing; `call_endpoint` spends the endpoint's credits on success only. See the [AI agents docs](https://docs.perceptlayer.com/ai-agents). booking.com hotel reviews review scores travel hotel data ## More from the blog 1. [API guides](https://perceptlayer.com/blog/category/api-guides) 25 Aug 2026 Perceptlayer 8 min read ## [Booking.com Hotel Prices API: Search, Rooms and Reviews](https://perceptlayer.com/blog/booking-com-hotel-prices-api) Eleven Booking.com endpoints as JSON: search, prices, rooms and reviews, with parameters and a 1,000-hotel price check costed in credits. 2. [API guides](https://perceptlayer.com/blog/category/api-guides) 21 Oct 2026 Perceptlayer 6 min read ## [Vrbo API: Vacation Rental Listings and Availability](https://perceptlayer.com/blog/vrbo-api-vacation-rental-listings) Search Vrbo with required check\_in and check\_out, then pull a listing's availability and reviews by property\_id. Parameters, cURL and the cost of 50 listings. 3. [API guides](https://perceptlayer.com/blog/category/api-guides) 7 Sept 2026 Perceptlayer 6 min read ## [Kiwi.com API: Search Fares and Cheapest Dates as JSON](https://perceptlayer.com/blog/kiwi-flights-api-cheapest-dates) Search Kiwi.com fares by origin, destination and date, then scan a window with calendar-cheapest-dates. A recorded London–Barcelona response and costs.