Blog / API guides

Booking.com Reviews API: Hotel Review Scores as JSON

22 Oct 2026Perceptlayer7 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.

Which endpoints return Booking.com review data?

Booking.com review data lives in four endpoints of the Booking.com API. 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.

The pages for Review Scores and 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 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.

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. Authentication is covered in the authentication docs.

Review scores parameters

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.

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"

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 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 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.

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:

{
  "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.

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.

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.

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 and the credits docs.

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 cover the rest. Lost replies after a timeout may have been billed, which the retry guide 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 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 is what the recorded call reads.

Related guides: the Yelp reviews guide and the Airbnb listings guide follow the same pattern for other travel and local sources, and the Travel APIs page lists the rest. To try a call first, open the playground on the Booking.com API page, pick Review Scores and run it with your key.

booking.comhotel reviewsreview scorestravelhotel data