Managing property scores

Property scores enable your properties to see their scores, the maximal possible scores, and the average scores of properties in their area. In case of work-friendly score and property page score (or content score) properties can also retrieve actionable information to help improve those scores.

You can find the following types of property scores:

  • Property page score (or content score): Refers to the quality of the property content on Booking.com. Max score is 100%.
  • Quality rating: Refers to the quality rating for vacation rentals (Booking Home properties). Max score is five.
  • Reply score: Refers to the reply rate of a property, or how well they perform when it comes to replying to guests. Max score is 100%.
  • Review score: Refers to the average guest review score for a property. Max score is 10.
  • Work-friendly score: Refers, in percentage, how close a property is to fulfilling the necessary eligibility criteria to obtain a work-friendly badge on Booking.com.

Retrieving property scores

GET https://supply-xml.booking.com/property-scores/summary

The GET /property-scores/summary request enables you to retrieve:

  • The property scores for all the properties linked to your machine account: For this you must use the query parameters page and page_size.
  • The property scores for specific properties: For this, you must use the query parameter property_ids.

Cached data for work-friendly score

The GET /property-scores/summary endpoint returns cached data for work-friendly score. To retrieve the most accurate data, call the GET properties/{property_id}/breakdown endpoint.

Header parameters

The following table lists the header parameters in the request:

Parameter Description Type Required/Optional Notes
Authorization Machine account username and password string Required Example: Authorization: Basic {username:password}

Query parameters

Parameter Description Type Required/Optional Notes
page Specifies the number of the page you want to retrieve. integer required If you use this query parameter and page_size, you must not use property_ids.
page_size Specifies the number of properties you want to retrieve per page. integer required If you use this query parameter and page, you must not use property_ids.
property_ids Specifies the unique ids (separated by &) of the properties you want to retrieve property scores for. integer required If you use this query parameter, you must not use page and page_size.

Example requests

The following is a cURL example request with pagination:

curl -X GET \
https://supply-xml.booking.com/property-scores/summary?page=1&page_size=10 \

The following is a cURL example request for specific properties:

curl -X GET \
https://supply-xml.booking.com/property-scores/summary?property_ids=12345&property_ids=54321 \

Sample response

The following is a sample response for the pagination request:

{
    "warnings": [],
    "errors": [],
    "data": {
        "property_scores": [
            {
                "property_id": 304378,
                "reply_score": null,
                "content_score": {
                    "score": "32",
                    "area_average_score": "98",
                    "max_score": "100"
                },
                "review_score": {
                    "score": "7.7",
                    "max_score": "10.0"
                },
                "work_friendly_score": 25.0,
                "quality_rating_score": null
            },
            ...
            {
                "property_id": 1249963,
                "reply_score": null,
                "content_score": {
                    "score": "32",
                    "area_average_score": "98",
                    "max_score": "100"
                },
                "review_score": {
                    "score": "8.3",
                    "max_score": "10.0"
                },
                "quality_rating_score": "3",
                "work_friendly_score": 87.0
            }
        ],
        "pagination":{
            "page": 1,
            "page_size": 10,
            "page_count": 123,
            "total_amount": 1230
        }
    },
    "meta": {
        "ruid": "UmFuZG9tSVYkc2RlIzx9YSbFRuuXULneqGg5QhZUew80D+W4tenrGFC172YQOMw3d6Zu8ymbv9DX2Mb7l50RQWTFXmk5VcbvgSuyZbHZt9Xqws+VFNDUSg=="
    }

The following is an example of the reponse for specific properties:

{
    "errors": [],
    "data": {
        "property_scores": [ 
                {
                    "property_id": 12345,
                    "reply_score": null,
                    "content_score": {
                        "score": "32",
                        "area_average_score": "98",
                        "max_score": "100"
                    },
                    "review_score": {
                        "score": "9.7",
                        "max_score": "10.0"
                    },
                    "quality_rating_score": {
                        "score": "3",
                        "max_score": "5"
                    },
                    "work_friendly_score": {
                        "max_score": 100,
                        "score": 17.0
                    }

                }
            ]
        }
    },
    "warnings": [
        {
            "code": "FORBIDDEN",
            "details": {
                "property_ids": [
                    "54321"
                ]
            },
            "message": "Your machine account does not have access to some of the properties you requested, these property_ids will be ignored."
        }
    ],
    "meta": {
        "ruid": "UmFuZG9tSVYdc2RlIyh9YSqFRuuXULneM7/cXfRnM96mFXqjXT3CcmEnYqET8BTO0eQDJ6GOR85FWQn00KGJwYJVjSGEex/X9tBhuFh8OIlHqaVZV6/CQA=="
    }

Response body

The following table describes the elements of the response body:

Element Description Type Notes
meta Contains the meta data that comes with the response. object
ruid Specifies the unique ID of the request. string You can send this ID to Booking.com customer support if you run into an issue. This can help to understand what went wrong.
data Contains the response data. object
: property_scores Contains the property score elements. array If an property score element does not have a value, you see null.
:: property_id Specifies the unique ID of the property. integer
:: content_score Specifies the score in percentages for the content quality (or information that helps improve property performance) of a property. string
::: score Specifies the score for the property score element it is nested within. string
::: max_score Specifies the max score for the property score element it is nested within. string
::: area_average_score Specifies the average score in a particular area for the property score element it is nested within. string
:: review_score Specifies the average score that guests gave the property. string
:: reply_score Specifies the score in percentages to indicate the property's reply performance. string
:: quality_rating_score Specifies the rating for vacation rentals. string
:: work_friendly_score Specifies in percentages how close a property is to obtaining the work-friendly badge. integer
: pagination Contains the pagination information. object
:: page Specifies the page number that you requested. If you didn't specify the number, it returns page 1. integer
:: page_size Specifies the number of properties per page. If you didn't specify the amount, it returns 100 properties per page. integer
:: page_count Specifies the number of pages with properties. integer
:: total_amount Specifies the total amount of properties connected to your machine account. integer
warnings Contains potential warnings. These can help you improve your requests. array
errors Contains potential errors. These can help you understand what went wrong with your request. array

Retrieving property scores per property (with actions)

GET https://supply-xml.booking.com/property-scores/properties/{property_id}/breakdown

The GET properties/{property_id}/breakdown request enables you to retrieve all available property scores for a specific property in combination with actionable information to help improve those scores.

Actionable information

For now, you can retrieve actionable information for three types of scores:

  • Property page (or content) score: The objective is to help you improve the property content on Booking.com through providing actionable metrics. Fulfilling these metrics can impact the property's performance in a positive way.
  • Work-friendly score: The objective is to provide a list of all the requirements (metrics), both on the room (unit) and property level, which a property needs to fulfil to obtain a work-friendly badge on Booking.com. If the score is not 100%, a property does not receive the badge.
  • Quality Rating Score: The objective is to help the property improve their overall quality, which could lead to a higher Quality Rating. An accurate rating is better than a higher Quality Rating, so that the property matches guests’ expectations.

Eligibility criteria

Currently only for Quality Rating score

Currently you can only retrieve actionable information to become eligible for Quality Rating.

Header parameters

The following table lists the header parameters in the request:

Parameter Description Type Required/Optional Notes
Authorization Machine account username and password string Required Example: Authorization: Basic {username:password}

Query parameters

Parameter Description Type Required/Optional Notes
property_id Specifies the unique ID of the property you want to retrieve property scores for. integer required

Example request

The following is an example cURL request to retrieve property scores with actions for a specific property:

curl -X GET \
https://supply-xml.booking.com/property-scores/properties/12345/breakdown \

Sample response

You can find a sample response here:

{
    "warnings": [],
    "data": {
        "property_scores": {
            "content_score": {
                "summary": {
                    "max_score": "100",
                    "area_average_score": "96",
                    "score": "35"
                },
                "metrics": [
                    {
                        "metric_id": "property_photos_3",
                        "action": "Upload at least 10 photos",
                        "done": 0
                    },
                    {
                        "metric_id": "property_hq_photos_3",
                        "action": "Make sure all of your photos are high quality",
                        "done": 1
                    },
                    {
                        "done": 1,
                        "action": "Add or tag a photo of your swimming pool",
                        "metric_id": "swimming_pool_photo_3"
                    },
                    {
                        "metric_id": "exterior_photo_3",
                        "action": "Add or tag a photo of your property's exterior",
                        "done": 0
                    },
                    {
                        "metric_id": "languages_spoken_2",
                        "action": "Add the languages you speak",
                        "done": 1
                    },
                    {
                        "metric_id": "key_collection",
                        "action": "Add key collection details",
                        "done": 0
                    },
                    {
                        "done": 1,
                        "action": "Specify bed sizes for each room",
                        "metric_id": "room_bedding_2"
                    },
                    {
                        "action": "Specify the room sizes for all of your active rooms",
                        "done": 0,
                        "metric_id": "room_size_2"
                    },
                    {
                        "action": "Add information about your surrounding area",
                        "done": 0,
                        "metric_id": "surrounding_info"
                    },
                    {
                        "done": 0,
                        "action": "Add directions to your property",
                        "metric_id": "transport_info"
                    },
                    {
                        "done": 1,
                        "action": "Add room amenities for all of your active rooms",
                        "metric_id": "room_amenities"
                    },
                    {
                        "metric_id": "bathroom_photos_3",
                        "done": 0,
                        "action": "Add bathroom photos to all of your active rooms"
                    }
                ]
            },
            "work_friendly_score": {
                "units": [
                    {
                        "id": 578978702,
                        "metrics": [
                            {
                                "metric_id": "desk",
                                "done": 0,
                                "action": "Desk or table to work at"
                            },
                            {
                                "metric_id": "tv",
                                "action": "TV",
                                "done": 0
                            },
                            {
                                "done": 0,
                                "action": "Towels ",
                                "metric_id": "towels"
                            },
                            {
                                "metric_id": "linen",
                                "action": "Linen",
                                "done": 0
                            },
                            {
                                "action": "Pillows",
                                "done": 0,
                                "metric_id": "pillows"
                            },
                            {
                                "metric_id": "toilet_paper",
                                "action": "Toilet paper",
                                "done": 0
                            },
                            {
                                "action": "Body soap",
                                "done": 0,
                                "metric_id": "soap"
                            },
                            {
                                "metric_id": "free_toiletries",
                                "done": 0,
                                "action": "Free toiletries (such as shower gel, shampoo)"
                            },
                            {
                                "metric_id": "flexible_rate",
                                "done": 0,
                                "action": "At least one flexible rate plan"
                            },
                            {
                                "action": "Private bathroom",
                                "done": 0,
                                "metric_id": "private_bathroom"
                            },
                            {
                                "metric_id": "fire_extinguisher",
                                "done": 0,
                                "action": "Fire extinguisher"
                            },
                            {
                                "done": 1,
                                "action": "No carbon monoxide sources",
                                "metric_id": "co_sources"
                            },
                            {
                                "metric_id": "smoke_alarm",
                                "action": "Smoke alarm",
                                "done": 0
                            }
                        ]
                    }
                ],
                "property": {
                    "metrics": [
                        {
                            "metric_id": "property_score",
                            "action": "Review score of 8.0 or higher",
                            "done": 0
                        },
                        {
                            "metric_id": "cleanliness_score",
                            "action": "Cleanliness score of 8.0 or higher",
                            "done": 0
                        },
                        {
                            "action": "Credit card payments accepted",
                            "done": 1,
                            "metric_id": "credit_card"
                        },
                        {
                            "metric_id": "invoice",
                            "done": 0,
                            "action": "Invoices issued to guests on request"
                        },
                        {
                            "done": 0,
                            "action": "Free WiFi",
                            "metric_id": "wifi"
                        }
                    ]
                },
                "summary": {
                    "max_score": 100,
                    "score": 17.0
                }
            },
            "reply_score": {
                "summary": null
            },
            "review_score": {
                "summary": null
            },
            "quality_rating_score": {
                "summary": {
                    "score": 4,
                    "max_score": 5
                },
                "eligibility_criteria": [
                    {
                        "done": 0,
                        "action": "Complete the bathroom information",
                        "metric_id": "bathroom_or_shower_or_toilet_info"
                    },
                    {
                        "done": 0,
                        "action": "Complete the bedroom information",
                        "metric_id": "bed_info"
                    },
                    {
                        "done": 0,
                        "action": "Make sure the cleanliness score from guests' reviews is not below 6.0.",
                        "metric_id": "good_cleanliness"
                    },
                    {
                        "done": 0,
                        "action": "Make sure the unit size is filled in correctly",
                        "metric_id": "max_surface"
                    }
                ],
                "metrics": [
                    {
                        "done": 0,
                        "action": "Room Facility: Slippers",
                        "metric_id": "roomfacility43"
                    },
                    {
                        "action": "Hotel Facility: Grocery deliveries",
                        "metric_id": "hotelfacility159",
                        "done": 0
                    },
                    {
                        "done": 0,
                        "action": "Hotel Facility: Luggage storage",
                        "metric_id": "hotelfacility91"
                    },
                    {
                        "metric_id": "hotelfacility418",
                        "action": "Hotel Facility: 24-hour security",
                        "done": 1
                    },
                    {
                        "metric_id": "roomfacility201",
                        "action": "Room Facility: Smoke alarm",
                        "done": 1
                    }
                ]
            }
        }
    },
    "errors": [],
    "meta": {
        "ruid": "UmFuZG9tSVYkc2RlIyh9Yb9UlxmWyvKHdOUxzf95LKhIxr6q0dLVCn2efDrShncS30EsEprRMRMkWSMRcRtbVXGPt8205HLHnO5ly6ewM1eSm2vHLHpo7A=="
    }

Response body

The following table describes the elements of the response body:

Element Description Type Notes
meta Contains the meta data that comes with the response. object
ruid Specifies the unique ID of the request. string You can send this ID to Booking.com customer support if you run into an issue. This can help to understand what went wrong.
data Contains the response data. object
: property_scores Contains the property score elements with actionable elements. object If an property score element does not have a value, you see null.
:: content_score Specifies the score in percentages for the content quality (or information that helps improve property performance) of a property. string
::: metrics Contains the action elements to improve the score for the property score element it is nested within. array
:::: metric_id Specifies the ID of the action element. string
:::: done Indicates whether the action has been done or not. boolean
:::: action Specifies the recommended action so that your property can improve the score for the property score element it is nested within. string
::: summary Contains the elements that specify the score, maximum score, and average score in the property's area. object
:::: score Specifies the score for the property score element it is nested within. string
:::: max_score Specifies the max score for the property score element it is nested within. string
:::: area_average_score Specifies the average score in the property's area for the property score element it is nested within. string
:: review_score Specifies the average score that guests gave the property. string
:: reply_score Specifies the score in percentages to indicate the property's reply performance. string
:: quality_rating_score Specifies the rating for vacation rentals. string
::: summary Specifies the quality rating for vacation rentals. string
::: metrics Contains the action elements to improve the quality rating for vacation rentals. array
:::: metric_id Specifies the ID of the action element. string
:::: done Indicates whether the action has been done. boolean
:::: action Specifies an action to improve the property score. string
::: eligibility_criteria Contains the action elements for eligibility for vacation rentals rating. array
:::: metric_id Specifies the ID of the action element for eligibility. string
:::: done Indicates whether the action has been done. boolean
:::: action Specifies an action to become eligible for the property score. string
:: work_friendly_score Specifies in percentages how close a property is to obtaining the work-friendly badge. integer
::: units Contains the metrics for the room type (unit) level. array Only with work-friendly score.
:::: id Specifies the ID of the room type (unit). array Only with work-friendly score.
::: property Contains the metrics for the property type level. array Only with work-friendly score.
warnings Contains potential warnings. These can help you improve your requests. array
errors Contains potential errors. These can help you understand what went wrong with your request. array

Going live

Before you go live with your API integration, take a look at Going Live.