Last updated

Self-assessment tutorial: Guest Reviews API

In this Self-assessment tutorial, you will use the Guest Review API to:

  • Retrieve reviews for a property
  • Retrieve a specific review
  • Respond to a review

Who is this for?

You should read this if you're any of the following:

  • a developer who works for an existing Connectivity Partner which is preparing to implement Guest Reviews API
  • a developer who wants to estimate the time needed to implement the Guest Reviews API
  • a developer who wants to try out most of the essential endpoints of Guest Reviews API on a test environment

Before you start

Test properties do not come with reservations and reviews pre-filled. For this tutorial, you will need to create a couple of reservations, write your own reviews, and then use the Guest Reviews API to manage them.

You will need the below to complete the tutorial:

  • A test property with active Review API connection that has at least one room, availability and prices
  • A valid email address which you have access to

Step 1 - Create a reservation

Create a test reservation following this link (remember to provide your test property ID):

https://secure.booking.com/book.html?test=1;hotel_id={property_id}

Review requests are sent to the guest one day after check-out. For the purposes of this tutorial, please create a reservation with TODAY as check-in date, lasting one night.

create reservation

Fill in the required details for the reservation. Keep in mind that you need to provide a real email address that you have access to. This is the address we will send the review request to.

The required information will vary according to your test property setup. If a credit card is required to make a booking, please enter a dummy credit card (for example 4111111111111111).

create reservation

Once you've completed your reservation, you will receive a reservation confirmation to the specified email address.

Bonus step: Create another reservation to test out more than one type of guest review.

Step 2 - Leave a review

You will receive an email from Booking.com called "Rate {property_name}". From that email you will be taken to the review survey. Please fill out the review survey as detailed as possible. Depending on the setup and amenities of your test property, there might be bonus questions added in the survey, (for example to rate the quality of the breakfast).

review

Reviews go through an approval process so you will not be able to see the newly created review in the Booking.com extranet immediately. Reviews on test properties will be automatically approved within 24 hours.

review

It is no longer possible to write anonymous reviews. Guests using older versions of our mobile apps may still be able to leave anonymous reviews, but we don’t expect this to happen often. As with all other reviews, any existing anonymous reviews will remain public for 36 months.

Step 3 - Retrieve reviews

Send the request with below method and URL to get all of the property reviews:

Request:
GET https://supply-xml.booking.com/review-api/properties/{hotel_id}/reviews
Headers:
Content-Type: application/json
Authorization: Basic TWFjaGluZV9BY2NvdW50X1VzZXJuYW1lOk1hY2hpbmVfQWNjb3VudF9QYXNzd29yZA==
Sample response body:
{
  "meta": {
    "next_page": "https://supply-xml.booking.com/review-api/properties/3309550/reviews?from_date=2018-04-01&cursor=UjQn7mKNem0XSsuc6q85e11Y9j3Ryf1sKcab9FKI2yiA5pxZFPmaP6b1zGPBlN51NIoQUy72",
    "ruid": "UmFuZG9tSVYkc2RlIyh9YTlNYOP4c64o8cmU5d/QzPXHq86GVKMhCBHhTK9xpL6xQ+cqHKTg2d2sMdpuPVqGxuQIZNolNTZa"
  },
  "errors": [],
  "warnings": [],
  "data": {
    "reviews": [
      {
        "reviewer": {
          "name": "BernardWillems",
          "is_genius": 1,
          "country_code": "nl"
        },
        "content": {
          "headline": null,
          "negative": "the croissants were not that flaky and the bed was not that comfy",
          "language_code": "en",
          "positive": "I liked the fact that it was a test hotel"
        },
        "reservation_id": 1063476917,
        "last_change_timestamp": "2018-08-21 13:45:47",
        "url": "https://supply-xml.booking.com/review-api/properties/3309550/reviews/UKilKjD2Hls",
        "response": {
          "response_text": "Thanks for your review! We'll take your feedback on board.",
          "response_timestamp": "2019-01-15 15:07:36"
        },
        "created_timestamp": "2018-08-21 10:10:42",
        "review_id": "UKilKjD2Hls",
        "scoring": {
          "facilities": 5,
          "value": 5,
          "comfort": 7.5,
          "review_score": 7.5,
          "staff": 7.5,
          "location": 10,
          "clean": 10
        }
      },
      {
        "scoring": {
          "review_score": 7,
          "staff": 7.5,
          "location": 5,
          "clean": 7.5,
          "facilities": 10,
          "value": 5,
          "comfort": 7.5
        },
        "reservation_id": null,
        "content": null,
        "reviewer": null,
        "url": "https://supply-xml.booking.com/review-api/properties/3309550/reviews/mSOWl6DZo6A",
        "last_change_timestamp": "2019-01-10 10:15:43",
        "response": null,
        "review_id": "mSOWl6DZo6A",
        "created_timestamp": "2019-01-10 10:01:07"
      }
    ]
  }
}

If you have left additional ratings these will not be returned in the response body. Availability of additional ratings such as “breakfast” or “wifi” varies based on the property’s specified facilities and various other factors. They are not taken into account for calculating the final property score.

Step 4 - Retrieve a specific review

Send the request with below method and URL to get the review we’ve previously created:

Request
GET https://supply-xml.booking.com/review-api/properties/{hotel_id}/reviews/{review_id}
Headers:
Content-Type: application/json
Authorization: Basic TWFjaGluZV9BY2NvdW50X1VzZXJuYW1lOk1hY2hpbmVfQWNjb3VudF9QYXNzd29yZA==
Sample response body:
{
  "meta": {
    "ruid": "UmFuZG9tSVYkc2RlIyh9YQuRnifEn85gfTqcWzaQ7EN2hsE79i+y54d9M0OuvpzicTBKpcqmtE3Sx7Yfn0vXjiZOger6DV/h"
  },
  "data": {
    "review": {
      "reservation_id": 1063476917,
      "created_timestamp": "2018-08-21 10:10:42",
      "content": {
        "language_code": "en",
        "negative": "the croissants were not that flaky and the bed was not that comfy",
        "headline": null,
        "positive": "I liked the fact that it was a test hotel"
      },
      "last_change_timestamp": "2018-08-21 13:45:47",
      "scoring": {
        "comfort": 7.5,
        "staff": 7.5,
        "facilities": 5,
        "clean": 10,
        "location": 10,
        "review_score": 7.5,
        "value": 5
      },
      "reviewer": {
        "is_genius": 1,
        "name": "BernardWillems",
        "country_code": "nl"
      },
      "url": "https://supply-xml.booking.com/review-api/properties/3309550/reviews/UKilKjD2Hls",
      "review_id": "UKilKjD2Hls",
      "response": {
        "response_text": "Thanks for your review! We'll take your feedback on board.",
        "response_timestamp": "2019-01-15 15:07:36"
      }
    }
  },
  "warnings": [],
  "errors": []
}

Step 5 - Reply to a review

Send a post request to the review that you’ve retrieved in the last step.

Request:
POST https://supply-xml.booking.com/review-api/properties/{hotel_id}/reviews/{review_id}
Headers:
Content-Type: application/json
Authorization: Basic TWFjaGluZV9BY2NvdW50X1VzZXJuYW1lOk1hY2hpbmVfQWNjb3VudF9QYXNzd29yZA==
Sample request body:
{
  "reply": "Thanks for your review! We'll take your feedback on board."
}
Sample response body:
{
    "meta": {
        "ruid": "UmFuZG9tSVYkc2RlIyh9YQuRnifEn85g5V6MK28/MFKkVT/R/UNzR32YCF8dDELDDyrMHWuX3hRc10yNS0iLxrmtuftn21sE"
    },
    "warnings": [],
    "errors": []
}

Just like reviews, your review response will not show up on the property page instantly. Review replies go through a moderation process and should be approved or rejected within 48 hours. You can see your posted reply and its status in the extranet:

review

If you retrieve the reviews again you will be able to see your response included.

Step 6 - Retrieve review score

Once you have a couple of reviews, you can retrieve the overall property score. Again, this will not include additional score categories like breakfast as they are not used in the final score calculation.

review score

Send the request with below method and URL to get the property score:

Request:
GET https://supply-xml.booking.com/review-api/properties/{hotel_id}/score
Headers:
Content-Type: application/json
Authorization: Basic TWFjaGluZV9BY2NvdW50X1VzZXJuYW1lOk1hY2hpbmVfQWNjb3VudF9QYXNzd29yZA==
Sample response body:
{
  "errors": [],
  "data": {
    "scores": {
      "clean": {
        "score": 7.9166665,
        "review_count": 12
      },
      "comfort": {
        "score": 7.0833335,
        "review_count": 12
      },
      "location": {
        "score": 5.625,
        "review_count": 12
      },
      "value": {
        "review_count": 12,
        "score": 6.6666665
      },
      "review_score": {
        "score": 7.1875,
        "review_count": 12
      },
      "facilities": {
        "score": 7.7083335,
        "review_count": 12
      },
      "staff": {
        "review_count": 12,
        "score": 8.125
      }
    }
  },
  "meta": {
    "ruid": "UmFuZG9tSVYkc2RlIyh9YQuRnifEn85g10ZjWGO7yq6/4zSokCBJHPIw9pXEoEt3fIF5ENLXdT2X1zEeqXQRdLbF9omUd9Wd"
  },
  "warnings": []
}

Step 7 - Check

Retrieve all the reviews and property score, and check on your property’s extranet whether your implementation matches the results.

Make as many test reservations and reviews as you like.

Previous page
Next page