Managing property scores

Property scores enable your properties to see how they are scored, what the maximal score is, and how properties in their area are scored. In case of property page score (or content score) properties can also retrieve actionable information to help improve their score.

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.

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.

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": 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"
                }
            }
        ],
        "pagination":{
            "page": 1,
            "page_size": 100,
            "page_count": 123,
            "total_amount": 12300
        }
    },
    "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": null,
                    "quality_rating_score": {
                        "score": "3",
                        "max_score": "5"
                    }
                }
            ]
        }
    },
    "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
: 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.

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:

{
    "errors": [],
    "warnings": [],
    "meta": {
        "ruid": "UmFuZG9tSVYkc2RlIzh9YbMtRWMV+bwN8B414cHGY95jEoTuDI9WSXMuxdG7EcpfUawpBZFSwlJsr+OvYuamWVulTK0B6keMyGXX624IOV14C80/aZsEKA=="
    },
    "data": {
        "property_scores": {
            "content_score": {
                "metrics": [
                    {
                        "action": "Make sure all of your photos are high quality",
                        "done": 1,
                        "metric_id": "property_hq_photos_3"
                    },
                    {
                        "metric_id": "key_collection",
                        "done": 0,
                        "action": "Add key collection details"
                    },
                    {
                        "action": "Add information about your surrounding area",
                        "metric_id": "surrounding_info",
                        "done": 0
                    }

              ...

                ],
                "summary": {
                    "area_average_score": "98",
                    "score": "42",
                    "max_score": "100"
                }
            },
            "reply_score": {
                "summary": {
                    "area_average_score": "67",
                    "score": "70",
                    "max_score": "100"
                }
            },
            "review_score": {
                "summary": null
            }
        }
    }
}

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