Managing property scores - Booking.com Connectivity API documentation (2024)

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.

Header parameters¶

The following table lists the header parameters in the request:

Query parameters¶

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:

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¶

Header parameters¶

The following table lists the header parameters in the request:

Query parameters¶

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:

Going live¶

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