Last updated

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:

ParameterDescriptionTypeRequired/OptionalNotes
AuthorizationMachine account username and passwordstringRequiredExample: Authorization: Basic {username:password}

Query parameters

ParameterDescriptionTypeRequired/OptionalNotes
pageSpecifies the number of the page you want to retrieve.integerrequiredIf you use this query parameter and page_size, you must not use property_ids.
page_sizeSpecifies the number of properties you want to retrieve per page.integerrequiredIf you use this query parameter and page, you must not use property_ids.
property_idsSpecifies the unique ids (separated by &) of the properties you want to retrieve property scores for.integerrequiredIf 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:

ElementDescriptionTypeNotes
metaContains the meta data that comes with the response.object
ruidSpecifies the unique ID of the request.stringYou can send this ID to Booking.com customer support if you run into an issue. This can help to understand what went wrong.
dataContains the response data.object
: property_scoresContains the property score elements.arrayIf an property score element does not have a value, you see null.
:: property_idSpecifies the unique ID of the property.integer
:: content_scoreSpecifies the score in percentages for the content quality (or information that helps improve property performance) of a property.string
::: scoreSpecifies the score for the property score element it is nested within.string
::: max_scoreSpecifies the max score for the property score element it is nested within.string
::: area_average_scoreSpecifies the average score in a particular area for the property score element it is nested within.string
:: review_scoreSpecifies the average score that guests gave the property.string
:: reply_scoreSpecifies the score in percentages to indicate the property's reply performance.string
:: quality_rating_scoreSpecifies the rating for vacation rentals.string
:: work_friendly_scoreSpecifies in percentages how close a property is to obtaining the work-friendly badge.integer
: paginationContains the pagination information.object
:: pageSpecifies the page number that you requested. If you didn't specify the number, it returns page 1.integer
:: page_sizeSpecifies the number of properties per page. If you didn't specify the amount, it returns 100 properties per page.integer
:: page_countSpecifies the number of pages with properties.integer
:: total_amountSpecifies the total amount of properties connected to your machine account.integer
warningsContains potential warnings. These can help you improve your requests.array
errorsContains 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:

ParameterDescriptionTypeRequired/OptionalNotes
AuthorizationMachine account username and passwordstringRequiredExample: Authorization: Basic {username:password}

Query parameters

ParameterDescriptionTypeRequired/OptionalNotes
property_idSpecifies the unique ID of the property you want to retrieve property scores for.integerrequired

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:

ElementDescriptionTypeNotes
metaContains the meta data that comes with the response.object
ruidSpecifies the unique ID of the request.stringYou can send this ID to Booking.com customer support if you run into an issue. This can help to understand what went wrong.
dataContains the response data.object
: property_scoresContains the property score elements with actionable elements.objectIf an property score element does not have a value, you see null.
:: content_scoreSpecifies the score in percentages for the content quality (or information that helps improve property performance) of a property.string
::: metricsContains the action elements to improve the score for the property score element it is nested within.array
:::: metric_idSpecifies the ID of the action element.string
:::: doneIndicates whether the action has been done or not.boolean
:::: actionSpecifies the recommended action so that your property can improve the score for the property score element it is nested within.string
::: summaryContains the elements that specify the score, maximum score, and average score in the property's area.object
:::: scoreSpecifies the score for the property score element it is nested within.string
:::: max_scoreSpecifies the max score for the property score element it is nested within.string
:::: area_average_scoreSpecifies the average score in the property's area for the property score element it is nested within.string
:: review_scoreSpecifies the average score that guests gave the property.string
:: reply_scoreSpecifies the score in percentages to indicate the property's reply performance.string
:: quality_rating_scoreSpecifies the rating for vacation rentals.string
::: summarySpecifies the quality rating for vacation rentals.string
::: metricsContains the action elements to improve the quality rating for vacation rentals.array
:::: metric_idSpecifies the ID of the action element.string
:::: doneIndicates whether the action has been done.boolean
:::: actionSpecifies an action to improve the property score.string
::: eligibility_criteriaContains the action elements for eligibility for vacation rentals rating.array
:::: metric_idSpecifies the ID of the action element for eligibility.string
:::: doneIndicates whether the action has been done.boolean
:::: actionSpecifies an action to become eligible for the property score.string
:: work_friendly_scoreSpecifies in percentages how close a property is to obtaining the work-friendly badge.integer
::: unitsContains the metrics for the room type (unit) level.arrayOnly with work-friendly score.
:::: idSpecifies the ID of the room type (unit).arrayOnly with work-friendly score.
::: propertyContains the metrics for the property type level.arrayOnly with work-friendly score.
warningsContains potential warnings. These can help you improve your requests.array
errorsContains 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.