Managing photo galleries

This section describes all the possible actions related to managing photo galleries for a property through the Photo API. The Photo API supports two types of photo galleries:

Property-level photo gallery: When you upload a new photo, the API places the photo in the property-level photo gallery. You can perform several actions with the property-level photo gallery. For more information, see managing the property-level photo gallery.
Room-level photo gallery: For each room type, you can have a separate photo gallery. You can move photos from the property-level photo gallery to a specific room-level photo gallery. For more information, see managing room-level photo galleries.

Managing the property-level photo gallery

You can perform the following actions with the property-level photo gallery:

Retrieve the property-level photo gallery.
Move photos to the property-level photo gallery.
Remove photos from the property-level photo gallery.
Manage smart ordering of photos in the property-level photo gallery.
Change the order of photos in the property-level photo gallery.
Set a main photo for the property-level photo gallery.

Maximum of 40 photos shown on property page

When a guest lands on a property page on Booking.com, they see only 40 photos from the property's total collection of photos in the property-level photo gallery. The photos are shown in the order optimised using smart ordering, by default. If you want to show the photos in a different order, you must (i) disable smart ordering and (ii) change the order of photos in the property-level photo gallery.

Retrieving the property-level photo gallery

GET https://supply-xml.booking.com/photo-api/properties/{property_id}/gallery

The GET /properties/{property_id}/gallery request enables you to retrieve the property-level photo gallery.

Path parameters

The following table describes the path parameters:

Element	Description	Type	Required/Optional	Notes
`property_id`	Specifies the unique property ID you want to retrieve the property-level photo gallery for.	integer	required

Response body example

The following is a successful response body example:

{
  "data": {
    "order": [
      {
        "url": "https://supply-xml.booking.com/photo-api/properties/1234567890/photos/ALF95NB920ACXLS",
        "name": "originalfilename.jpg",
        "photo_id": "ALF95NB920ACXLS"
      },
      {
        "url": "https://supply-xml.booking.com/photo-api/properties/1234567890/photos/VN49VL30GLH04J2",
        "name": "originalfilename2.jpg",
        "photo_id": "VN49VL30GLH04J2"
      },
      {
        "url": "https://supply-xml.booking.com/photo-api/properties/1234567890/photos/9430VNAV32VLDS9",
        "name": "originalfilename3.jpg",
        "photo_id": "9430VNAV32VLDS9"
      }
    ],
    "main_photo": {
      "url": "https://supply-xml.booking.com/photo-api/properties/1234567890/photos/ALF95NB920ACXLS",
      "name": "originalfilename2.jpg",
      "photo_id": "ALF95NB920ACXLS"
    },
    "smart_ordering": 1
  },
  "warnings": [],
  "meta": {
    "next_page": "https://supply-xml.booking.com/photo-api/properties/1234567890/gallery?cursor=UkQAAAAbAAAACcLXKfTV0IWhg0m29bafA229j40dfdmm0RdlrARj8v9okw0OX5LZ2wLCMIbQk7YOTFPsiuGIzyp33JYxxg",
    "ruid": "UmFuZG9tSVYkc2RlIyh9YWFOqyMkTMArT9aWcwl7Ali3zqbWFDnNbiIV1plT0W3msU+6mSlt2MKiAUV732z2Hj9N9KuE5xD4AafO6lluWQM="
  },
  "errors": []
}

Response body parameters

The following table describes the response elements:

Element	Description	Type	Notes
`data`	Contains the response data.	object
> `order`	Contains the photos that are in the property-level photo gallery.	array	The first photo in the property-level photo gallery is the main photo.
>> `smart_ordering`	Specifies whether the order of photos shown to the guests from the property-level photo gallery is optimised using machine learning algorithm.	Boolean	Can have the following values: 0 - Photos are shown in the order set by the property 1 - Photos are shown in the order optimised by machine learning algorithm.
>> `url`	Specifies the URL of the photo.	string
>> `name`	Specifies the name of the photo.	string
> `photo_id`	Specifies the photo id.	string
`meta`	Contains the meta data that comes with the response.	object
> `next_page`	Specifies the URL with the next page of results.	string
> `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.
`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

Moving photos to the property-level photo gallery

POST https://supply-xml.booking.com/photo-api/properties/{property_id}/gallery

The POST /properties/{property_id}/gallery request enables you to move photos to the property-level photo gallery. Uploaded photos are automatically placed within the property-level photo gallery, but you can remove them from this gallery. See Removing photos from the property-level photo gallery.

Path parameters

The following table describes the path parameters:

Element	Description	Type	Required/Optional	Notes
`property_id`	Specifies the unique property ID and therefore the property-level photo gallery you want to move photos to.	integer	required

Body parameters

The following table describes the elements you must add in the request body:

Element	Description	Type	Required/Optional	Notes
`insert_photos`	Contains the photo ids that you want to move to the property-level photo gallery.	array of strings	required

Request body example

The following is a request body example:

{
  "insert_photos":[
    "7Q1IREzv-P0",
    "8-NjAmvGUuY"
  ]
}

Response body example

The following is a successful response body example:

{
    "meta": {
        "ruid": "UmFuZG9tetc"
    },
    "data": {
        "success": 1
    },
    "warnings": [],
    "errors": []
}

Response body parameters

The following table describes the response elements:

Element	Description	Type	Notes
`data`	Contains the response data.	object
`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.
`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

Removing photos from the property-level photo gallery

POST https://supply-xml.booking.com/photo-api/properties/{property_id}/gallery

The POST /properties/{property_id}/gallery request enables you to remove a photo from the property-level photo gallery, which does not imply deleting the photo.

Removing photo from property-level photo gallery does not delete the photo

Removing a photo from the gallery (property/room) does not delete the photo. You can still add the photo to the gallery later. To permanently delete a photo, use the delete endpoint. See deleting a photo.

Path parameters

The following table describes the path parameters:

Element	Description	Type	Required/Optional	Notes
`property_id`	Specifies the unique property ID and therefore the property-level photo gallery you want to remove a photo from.	integer	required

Body parameters

The following table describes the elements you must add in the request body:

Element	Description	Type	Required/Optional	Notes
`remove_photos`	Contains the photo ID that you want to remove from the property-level photo gallery.	array of one string	required

Request body example

The following is a request body example:

{
   "remove_photos":[
      "765432198"
   ]
}

Response body example

The following is a successful response body example:

{
    "meta": {
        "ruid": "UmFuZG9tetc"
    },
    "data": {
        "success": 1
    },
    "warnings": [],
    "errors": []
}

Response body parameters

The following table describes the response elements:

Element	Description	Type	Notes
`data`	Contains the response data.	object
`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.
`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

Changing the order of photos in the property-level photo gallery

POST https://supply-xml.booking.com/photo-api/properties/{property_id}/gallery

The POST /properties/{property_id}/gallery request enables you to change the order of the photos in the property-level photo gallery. The order that you choose, is the order they appear on Booking.com, provided you have disabled smart ordering.

Path parameters

The following table describes the path parameters:

Element	Description	Type	Required/Optional	Notes
`property_id`	Specifies the unique property ID and therefore the property-level photo gallery you want to reorder the photos for.	integer	required

Body parameters

The following table describes the elements you must add in the request body:

Element	Description	Type	Required/Optional	Notes
`order`	Contains the photo ids in the order that you want them to be in.	array of strings	required	Ensure that you include all the photos that are in the property-level photo gallery when reordering them.

Request body example

The following is a request body example:

{
  "order":[
    "987654321",
    "654321987",
    "765432198",
    "876543219"
  ]
}

Response body example

The following is a successful response body example:

{
    "meta": {
        "ruid": "UmFuZG9tetc"
    },
    "data": {
        "success": 1
    },
    "warnings": [],
    "errors": []
}

Response body parameters

The following table describes the response elements:

Element	Description	Type	Notes
`data`	Contains the response data.	object
`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.
`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

Setting a main photo for the property-level photo gallery

POST https://supply-xml.booking.com/photo-api/properties/{property_id}/gallery

The POST /properties/{property_id}/gallery request enables you to set a specific photo as the main photo for a property, which is the photo guests see when going through search results.

First photo seen as main photo

If you do not set a main photo, the first photo in the property-level photo gallery functions as the main photo. Room-level photo galleries do not have main photos.

Path parameters

The following table describes the path parameters:

Element	Description	Type	Required/Optional	Notes
`property_id`	Specifies the unique property ID and therefore the property-level photo gallery you want to set a main photo for.	integer	required

Body parameters

The following table describes the elements you must add in the request body:

Element	Description	Type	Required/Optional	Notes
`main_photo`	Contains the photo ID that you want to set as the main photo.	array of one string	required

Request body example

The following is a request body example:

{
   "main_photo": "987654321"
}

Response body example

The following is a successful response body example:

{
    "meta": {
        "ruid": "UmFuZG9tetc"
    },
    "data": {
        "success": 1
    },
    "warnings": [],
    "errors": []
}

Response body parameters

The following table describes the response elements:

Element	Description	Type	Notes
`data`	Contains the response data.	object
`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.
`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

Managing smart ordering

POST https://supply-xml.booking.com/photo-api/properties/{property_id}/gallery

Use the POST /properties/{property_id}/gallery request to enable or disable smart ordering. When smart ordering is enabled for a property, the order in which the guests see the property's photos on the property page is determined by Booking.com's machine learning algorithm. Alternatively, you can disable smart ordering using this endpoint and follow one of the two approaches:

As a provider, you can set the photo order using the Photo API
Let the property set the order using the extranet

Regardless of the smart order setting, the property can view the chosen order on the extranet or using the API. Enable smart ordering to help boost guests' views.

Smart ordering is enabled by default

By default, smart ordering is enabled for photos in the property-level photo gallery. Before changing the order of appearance of the photos in the property-level photo gallery, make sure to disable smart ordering using this endpoint.

Path parameters

The following table describes the path parameters:

Element	Description	Type	Required/Optional	Notes
`property_id`	Specifies the unique property ID to set smart ordering for its photo gallery.	integer	required

Body parameters

The following table describes the elements you must add in the request body:

Element	Description	Type	Required/Optional	Notes
`smart_ordering`	Indicates whether the photos in the property's photo gallery are ordered using Booking.com's machine learning algorithm.	Boolean	required	Can specify the following values: 0 - Disable smart ordering 1 - Enable smart ordering

Request body example

The following is a request body example:

{
   "smart_ordering": 0
}

Response body example

The following is a successful response body example:

{
    "meta": {
        "ruid": "UmFuZG9tetc"
    },
    "data": {
        "success": 1
    },
    "warnings": [],
    "errors": []
}

Response body parameters

The following table describes the response elements:

Element	Description	Type	Notes
`data`	Contains the response data.	object
`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.
`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

Managing room-level photo galleries

Quick actions:

Retrieving a room-level photo gallery.
Moving photos to a room-level photo gallery.
Removing photos from a room-level photo gallery.
Changing the order of photos in a room-level photo gallery.

Retrieving a room-level photo gallery

GET https://supply-xml.booking.com/photo-api/properties/{property_id}/rooms/{room_id}/gallery/

The GET /properties/{property_id}/rooms/{room_id}/gallery request enables you to retrieve a specific room-level photo gallery.

Path parameters

The following table describes the path parameters:

Element	Description	Type	Required/Optional	Notes
`property_id`	Specifies the unique property ID you want to retrieve the room-level photo gallery for.	integer	required
`room_id`	Specifies the unique room ID of the room you want to retrieve the photo gallery for.	integer	required

Response body example

The following is a successful response body example:

{
    "data": {
        "order": [
            {
                "url": "https://supply-xml.booking.com/photo-api/properties/6314570/photos/lmMaRxjFAcA",
                "name": "That_hotel_room._37442232241_.jpg",
                "photo_id": "lmMaRxjFAcA"
            },
              {
                "url": "https://supply-xml.booking.com/photo-api/properties/6314570/photos/hhJerTYbef",
                "name": "That_hotel_room._334532241_.jpg",
                "photo_id": "hhJerTYbef"
            },
              {
                "url": "https://supply-xml.booking.com/photo-api/properties/6314570/photos/eplvMrTeYk",
                "name": "That_hotel_room._346442232241_.jpg",
                "photo_id": "eplvMrTeYk"
            }
        ]
    },
    "errors": [],
    "warnings": [],
    "meta": {
        "next_page": "https://supply-xml.booking.com/photo-api/properties/6314570/rooms/631457002/gallery?cursor=UkRwGeRzjlSosiG40xQioJdedf_zc28ziz5j598Nnp6TA-2HiF_ftLyM7OfiUn5hMXWv5DAh4l39IrZ--lOEVCrBaeHXFqbw",
        "ruid": "UmFuZG9tSVYkc2RlIyh9YUJC2IPXdcdvbrts1PfpoAwg2QpLZUz58u/Dv+7LfnOmUZNRWI8W8IHyNfgAqhjWSFpOeh4sjxv21+pRAWF2Yk8lIowQTjrA9GPCSmx"
    }
}

Response body parameters

The following table describes the response elements:

Element	Description	Type	Notes
`data`	Contains the response data.	object
> `order`	Contains the photos that are in the property-level photo gallery.	array	The first photo in the property-level photo gallery is the main photo.
>> `url`	Specifies the URL of the photo.	string
>> `name`	Specifies the name of the photo.	string
>> `photo_id`	Specifies the photo id.	string
`meta`	Contains the meta data that comes with the response.	object
> `next_page`	Specifies the URL with the next page of results.	string
> `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.
`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

Moving photos to a room-level photo gallery

POST https://supply-xml.booking.com/photo-api/properties/{property_id}/rooms/{room_id}/gallery/

The POST /properties/{property_id}/rooms/{room_id}/gallery request enables you to move photos to a room-level photo gallery.

Path parameters

The following table describes the path parameters:

Element	Description	Type	Required/Optional	Notes
`property_id`	Specifies the unique property id.	integer	required
`room_id`	Specifies the unique room ID and therefore what room-level photo gallery you want to move photos to.	integer	required

Body parameters

The following table describes the elements you must add in the request body:

Element	Description	Type	Required/Optional	Notes
`insert_photos`	Contains the photo ids that you want to move to the property-level photo gallery.	array of strings	required

Request body example

The following is a request body example:

{
  "insert_photos":[
    "7Q1IREzv-P0",
    "8-NjAmvGUuY"
  ]
}

Response body example

The following is a successful response body example:

{
    "meta": {
        "ruid": "UmFuZG9tetc"
    },
    "data": {
        "success": 1
    },
    "warnings": [],
    "errors": []
}

Response body parameters

The following table describes the response elements:

Element	Description	Type	Notes
`data`	Contains the response data.	object
`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.
`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

Removing photos from a room-level photo gallery

POST https://supply-xml.booking.com/photo-api/properties/{property_id}/rooms/{room_id}/gallery/

The POST /properties/{property_id}/rooms/{room_id}/gallery request enables you to remove a photo from a room-level photo gallery, which does not necessarily mean that you permanently delete the photo. See deleting a photo.

Path parameters

The following table describes the path parameters:

Element	Description	Type	Required/Optional	Notes
`property_id`	Specifies the unique property id.	integer	required
`room_id`	Specifies the unique room ID and therefore what room-level photo gallery you want to remove a photo from.	integer	required

Body parameters

The following table describes the elements you must add in the request body:

Element	Description	Type	Required/Optional	Notes
`remove_photos`	Contains the photo ID that you want to remove from the room-level photo gallery.	array of one string	required

Request body example

The following is a request body example:

{
   "remove_photos":[
      "765432198"
   ]
}

Response body example

The following is a successful response body example:

{
    "meta": {
        "ruid": "UmFuZG9tetc"
    },
    "data": {
        "success": 1
    },
    "warnings": [],
    "errors": []
}

Response body parameters

The following table describes the response elements:

Element	Description	Type	Notes
`data`	Contains the response data.	object
`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.
`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

Changing the order of photos in a room-level photo gallery

POST https://supply-xml.booking.com/photo-api/properties/{property_id}/rooms/{room_id}/gallery/

The POST /properties/{property_id}/rooms/{room_id}/gallery request enables you to change the order of the photos in a room-level photo gallery. The order that you choose, is the order they appear on Booking.com.

Path parameters

The following table describes the path parameters:

Element	Description	Type	Required/Optional	Notes
`property_id`	Specifies the unique property id.	integer	required
`room_id`	Specifies the unique room ID and therefore the room-level photo gallery you want to reorder the photos for.	integer	required

Body parameters

The following table describes the elements you must add in the request body:

Element	Description	Type	Required/Optional	Notes
`order`	Contains the photo ids in the order that you want them to be in.	array of strings	required	Ensure that you include all photos that are in the room-level photo gallery when reordering them.

Request body example

The following is a request body example:

{
  "order":[
    "987654321",
    "654321987",
    "765432198",
    "876543219"
  ]
}

Response body example

The following is a successful response body example:

{
    "meta": {
        "ruid": "UmFuZG9tetc"
    },
    "data": {
        "success": 1
    },
    "warnings": [],
    "errors": []
}

Response body parameters

The following table describes the response elements:

Element	Description	Type	Notes
`data`	Contains the response data.	object
`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.
`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