Home

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.

You can perform the following actions with 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.

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 
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 
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 
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 
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:

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 
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 
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 
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
Is this page helpful?    Yes   |    No