Deprecated functionality: Reply score value Reply score value is deprecated and will be sunset by July 02, 2025. After sunsetting, the API will no longer return the reply score field. # 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 ```http 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](/connectivity/docs/authentication) | 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 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 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: ```json { "warnings": [], "errors": [], "data": { "property_scores": [ { "property_id": 304378, "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, "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: ```json { "errors": [], "data": { "property_scores": [ { "property_id": 12345, "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 | | | **::** `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) ```http 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](/connectivity/docs/authentication) | 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 curl -X GET \ https://supply-xml.booking.com/property-scores/properties/12345/breakdown \ ``` ### Sample response You can find a sample response here: ```json { "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 } }, "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 | | | **::** `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.](/connectivity/docs/going_live/)