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

Eligibility criteria present what criteria a property must fulfil to be eligible for a certain property score. This means that, unless your property is already eligible, you retrieve the eligibility_criteria object providing actionable information to become eligible.

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.