Managing photos

This section describes all the possible actions related to managing photos for a property through the Photo API. Note that you can upload only 299 photos per property.

Uploading photos

You can perform the following actions:

When you upload photos, they are added to a processing queue where the system runs tests, such as checking for errors and duplicates. During that time each photo has a temporary photo pending ID. After a photo is successfully processed, it gets a permanent photo ID.

Uploaded photos are placed in property-level photo gallery

Whenever one or more photos are uploaded, by default, the API places the photos in the property-level photo gallery.

Uploading one or more photos per property

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

The POST /properties/{property_id}/pending/photos request enables you to upload one or more photos to a property-level photo gallery (after they are successfully processed).

Avoid uploading duplicates

Make sure to upload unique photos. If you upload a duplicate photo, the API does not immediately return a warning or an error. However, duplicate photos are rejected and not saved to the gallery.

You can find the status of the photo upload by running the GET pending/photos endpoint. If it is a duplicate, the API marks the status as duplicate and returns the ID of the matching photo that already exists in the gallery.

If you must add the duplicate photo, make sure to delete the original photo and upload the photo again.

Photo restrictions

Each photo that you want to upload must adhere to the following restrictions:

  • Minimum dimensions: 300 x 300 pixels
  • Maximum dimensions: 14000 x 14000 pixels
  • Maximum file size: 50000000 bytes or 50 megabyte

Path parameters

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

Element Description Type Required/Optional Notes
property_id Specifies the unique property ID you want to upload 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
photos Contains photo objects. array required The maximum number of photos you can upload per property is 299.
> url Specifies the URL of the photo. string required
> tag_ids Contains the photo tag(s) that describe the photo content. array of integers optional To retrieve all the photo tags used on Booking.com, see retrieving all photo tags

Request body example

The following is a request body example:

{
  "photos": [
    {
      "url": "http://image.example.com/example_image_01.jpg",
      "tag_ids": [
        3, 6, 81
      ]
    },
    {
      "url":"http://image.example.com/example_image_02.jpg",
      "tag_ids": [
        112, 90
      ]
    }
  ]
}

Response body example

The following is a successful response body example:

{
    "data": {
      "photo_batch_id": "N_rVh0sK6wI"
    },
    "meta": {
        "ruid": "UmFuZG9tSVYkc2RlIyh9Yb6ToEKUv9VcWwaZQWB/kI/9XRt0IBvKGP54DLARQ9OvgIz8zi5UKxHWYbAGlHfhRt7RAbwCPS868uNWfkiDT1I="
    },
    "warnings": [],
    "errors": []
}

Response body parameters

The following table describes the response elements:

Element Description Type Notes
data Contains the response data. object
> photo_batch_id Specifies the ID of the uploaded photo batch. string
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

Retrieving all Booking.com photo tags

GET https://supply-xml.booking.com/photo-api/tags

The GET /tags request enables you to retrieve all the available photo tags on Booking.com, which can help to describe the content of a photo.

→ If you want to update the photo tags of an existing uploaded photo, see updating existing photo tags.

Response body example

The following is a successful response body example:

{
    "errors": [],
    "warnings": [],
    "data": [
        {
            "id": 1,
            "tag": "Shower"
        },
        {
            "tag": "Toilet",
            "id": 2
        },
        {
            "id": 3,
            "tag": "Property building"
        },
        {
            "tag": "Patio",
            "id": 4
        },
        ...
    "meta": {
        "ruid": "UmFuZG9tSVYkc2RlIyh9Yb6ToEKUv9VcWwaZQWB/kI/9XRt0IBvKGP54DLARQ9Ovgwdwv4UKxHWYbAGlHfhRt7RAbwCPS868uNWfkiDT1I="
    }
}

Response body parameters

The following table describes the response elements:

Element Description Type Notes
data Contains the response data. object
> id Specifies the ID of the photo tag, which you can use when uploading photos to describe their content. integer
> tag Specifies the description of the photo tag. string
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

Updating photo tags

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

The POST /properties/{property_id}/photos/{photo_id}/tags request enables you to update the photo tags of existing uploaded photos.

Path parameters

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

Element Description Type Required/Optional Notes
property_id Specifies the unique property ID for which you want to update photo tags. integer required
photo_id Specifies the unique photo ID for which you want to update the photo tags. string required

Body parameters

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

Element Description Type Required/Optional Notes
tag_ids Contains the photo tag(s) that describe the photo content. array of integers required Add both existing and new (updated) tags in the request.
To retrieve all the photo tags used on Booking.com, see retrieving all photo tags.

Empty array removes all tags.

If you send a request with an empty tag_ids array, the API removes all existing photo tags attached to the specified photo.

Request body example

The following is a request body example:

{
  "tag_ids": [1, 5, 7]
}

Response body example

The following is a successful response body example:

{
    "data": {
        "success": 1
    },
    "meta": {
        "ruid": "UmFuZG9tSVYkc2RlIyh9Yd6zYn4H/Yq81zhSeCU73pHOvz/lmKy3wP2mumR9PfHiG9+2ccr3DkUH9e4Wy8ES3++asmdXwsmKVy83Q4/L34="
    },
    "warnings": [],
    "errors": []
}

Response body parameters

The following table describes the response elements:

Element Description Type Notes
data Contains the response data. object
> success Indicates the success of the operation. Boolean
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

Retrieving pending photo statuses

A pending photo status only refers to the status of a photo during the uploading process. It does not keep track of any changes to a successfully uploaded photo (with status ok).

For example, if an upload was successful, the pending photo status remains ok even if you delete the photo. Therefore, you must ony use the retrieving photos endpoint to find the currently available photos (photo ids) that you can move and modify.

Quick actions:

Retrieving status of all uploaded photos

GET https://supply-xml.booking.com/photo-api/properties/{property_id}/pending/photos?start_date={YYYY-MM-DD}

The GET /properties/{property_id}/pending/photos?start_date={YYYY-MM-DD} request enables you to retrieve the status of all photos after a specific date.

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 photo statuses for. integer required

Query parameters

The following table describes the query parameters:

Element Description Type Required/Optional Notes
start_date Specifies the date you want to retrieve photo statuses from. It also functions as a date range from start date until time of the request. string optional If you do not specify a date, the default value is seven days.

Retrieving by date only possible within seven days

You can retrieve statuses of photos uploaded seven days ago or later by specifying its photo_batch_id or photo_pending_id.

Response body example

The following is a successful response body example:

{
    "data": [
        {
            "status": "new",
            "photo_pending_id": "tnQs69gYd_o",
            "request_timestamp": "2018-06-22 10:38:58",
            "url": "http://example.image.com/example_image_01.jpg",
            "status_message": "The photo is still in processing queue."
        },
        {
            "status": "ok",
            "photo_pending_id": "oJgwI5LhE3s",
            "photo_id": "fklD4gkl32",
            "request_timestamp": "2018-06-22 10:38:58",
            "url": "http://example.image.com/example_image_02.jpg",
            "status_message": "The photo has been successfully processed and ready to be used."
        }
    ],
    "meta": {
      "limit": 100,
      "ruid": "UmFuZG9tSVYkc2RlIyh9Yb6ToEKUv9Vc+ekaaV5YR21O34VxTP222jwNovIjdWnoklSigfkA1HSD2V+scpDJLfNVn5I/y9j+Ebws0qhyzAo=",
      "next_page": "https://supply-xml.booking.com/photo-api/properties/1234567890/pending/photos/?after=oJgwI5LhE3s",
      "start_date": "2018-06-15",
      "items_retrieved": 2,
      "hotel_id": "1234567890"
    },
    "errors": [],
    "warnings": []
}

Response body parameters

The following table describes the response elements:

Element Description Type Notes
data Contains the response data. object
> url Specifies the URL of the enqueued photo. string
> request_timestamp Specifies the time the photo began processing. string Time is in CE(S)T.
> status Specifies the status of the photo. string Possible values are: new, ok, enqueued, bad_url, duplicate, error, and error_decode.
> status_message Specifies the message in correlation with its status. string
> photo_pending_id Specifies the temporary photo ID (while it is being processed). string This ID expires seven days after creation.
> photo_id Specifies the photo ID (after it is processed). string
meta Contains the meta data that comes with the response. object
> next_page Specifies the URL with the next page of results. string
> items_retrieved Specifies the amount of photos that you retrieved. integer
> hotel_id Specifies the property id. string
> limit Specifies the limit of the amount of photos per page. integer
> start_date Specifies the date you set as start date. 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

Retrieving pending status of photos by photo batch id

GET https://supply-xml.booking.com/photo-api/properties/{property_id}/pending/photos?photo_batch_id={photo_batch_id}

The GET /properties/{property_id}/pending/photos?photo_batch_id={photo_batch_id} request enables you to retrieve the status of photos by photo_batch_id.

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 photo statuses for. integer required

Query parameters

The following table describes the query parameters:

Element Description Type Required/Optional Notes
photo_batch_id Specifies the unique photo batch ID you want to retrieve photo statuses for. string optional

Response body example

The following is a successful response body example:

{
    "data": [
      {
        "url": "http://example.image.com/example_image_01.jpg",
        "request_timestamp": "2018-06-22 10:38:58",
        "status": "new",
        "photo_pending_id": "tnQs69gYd_o",
        "status_message": "The photo is still in processing queue."
      },
      {
        "status": "new",
        "photo_pending_id": "oJgwI5LhE3s",
        "request_timestamp": "2018-06-22 10:38:58",
        "url": "http://example.image.com/example_image_02.jpg",
        "status_message": "The photo is still in processing queue."
      }
    ],
    "meta": {
        "next_page": "https://supply-xml.booking.com/photo-api/properties/3374627/pending/photos/?photo_batch_id=N_rVh0sK6wI&after=oJgwI5LhE3s",
        "items_retrieved": 2,
        "hotel_id": "3374627",
        "limit": 100,
        "ruid": "UmFuZG9tSVYkc2RlIyh9Yaf+UcT6KAbCBwplV7qrRifGx4G3hJj5vYPE2lRDMn/PY7kGj6NUywN4V0adQXPG8z9Ew8An3RkUD2pX0yeUCBM="
    },
    "errors": [],
    "warnings": []
}

Response body parameters

The following table describes the response elements:

Element Description Type Notes
data Contains the response data. object
> url Specifies the URL of the enqueued photo. string
> request_timestamp Specifies the time the photo began processing. string Time is in CE(S)T.
> status Specifies the status of the uploaded photo. string Possible values are: new, ok, enqueued, bad_url, duplicate, error, and error_decode.
> status_message Specifies the message in correlation with its status. string
> photo_pending_id Specifies the temporary photo ID (while it is being processed). string This ID expires seven days after creation.
> photo_id Specifies the photo ID (after it is processed). string
meta Contains the meta data that comes with the response. object
> next_page Specifies the URL with the next page of results. string
> items_retrieved Specifies the amount of photos that you retrieved. integer
> hotel_id Specifies the property id. string
> limit Specifies the limit of the amount of photos per page. integer
> 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

Retrieving pending status of a specific photo

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

The GET /properties/{property_id}/pending/photos/{photo_pending_id} request enables you to retrieve the status of a specific photo by photo_pending_id.

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 photo statuses for. integer required
photo_pending_id Specifies the unique temporary ID of the photo you want to retrieve the photo status for. string required

Response body example

The following is a successful response body example:

{
    "data":{
        "id":"ABCDEF123456",
        "request_timestamp":"1514764800",
        "url":"http://example.image.com/example_image_01.jpg",
        "status":"ok",
        "status_message":"The photo has been successfully processed and ready to be used.",
        "photo_id":"XYZXYZ987654321"
    },
    "errors":[],
    "warnings":[],
    "meta":{}
}

Response body parameters

The following table describes the response elements:

Element Description Type Notes
data Contains the response data. object
> url Specifies the URL of the enqueued photo. string
> request_timestamp Specifies the time the photo began processing. string Time is in CE(S)T.
> status Specifies the status of the uploaded photo. string Possible values are: new, ok, enqueued, bad_url, duplicate, error, and error_decode.
> status_message Specifies the message in correlation with its status. string
> photo_pending_id Specifies the temporary photo ID (while it is being processed). string This ID expires seven days after creation.
> photo_id Specifies the photo ID (after it is processed). string
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 photos

Quick actions:

Retrieving metadata of all photos

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

The GET /properties/{property_id}/photos request enables you to retrieve the metadata of all photos for a property.

Path parameters

The following table describes the path parameters:

Element Description Type Required/Optional Notes
property_id Specifies the unique property ID of the property you want to retrieve all their photos' metadata for. integer required

Response body example

The following is a successful response body example:

{
  "data": {
    "photos": [
      {
        "photo_id": "7Q1IREzv-P0",
        "name": "original_125772780.jpg",
        "width": 1440,
        "height": 960,
        "quality": "high",
        "url": "https://supply-xml.booking.com/photo-api/properties/1234567890/photos/7Q1IREzv-P0",
        "sample": "https://example.com/path/max500_watermarked_standard/e77/e7742a01c8a3a8a038b7e0ada1b597124800ab94.jpg",
        "tag_ids": [1, 3, 7],
        "in_property_gallery": null,
        "in_room_galleries": [
          {
            "url": "https://supply-xml.booking.com/photo-api/properties/1234567890/rooms/123456789002/gallery",
            "room_id": 123456789002
          }
        ]
      },
      {
        "photo_id": "8-NjAmvGUuY",
        "name": "original_125772783.jpg",
        "url": "https://supply-xml.booking.com/photo-api/properties/1234567890/photos/8-NjAmvGUuY",
        "sample": "https://example.com/path/max500_watermarked_standard/8ee/8ee267492f453018befb28391c641bb0c993ef35.jpg",
        "width": 1140,
        "height": 960,
        "quality": "low",
        "message": "Your photos will have the greatest impact with guests if they are atleast 1280x900 pixels.",
        "tag_ids": [1, 8, 17],
        "in_property_gallery": {
          "url": "https://supply-xml.booking.com/photo-api/properties/1234567890/gallery",
          "property_id": 1234567890
        },
        "in_room_galleries": [
          {
            "room_id": 123456789002,
            "url": "https://supply-xml.booking.com/photo-api/properties/1234567890/rooms/123456789002/gallery"
          }
        ]
      }
    ]
  },
  "meta": {
    "next_page": "https://supply-xml.booking.com/photo-api/properties/1234567890/photos?cursor=UkQAAAAbAAAAAaA7-M_WOjCg6wlbfvCIE_CziAcfTvH0MrsgzDpyR2t3byjFFeUTTzt5aoulwH6sU9LzvqKf44TE2wLHDw",
    "ruid": "UmFuZG9tSVYkc2RlIyh9YWFOqyMkTMArQ8j4RHj1y73YowTqnhZhQ5lSBWXHp+al1oKXqiHL37AvlKkYfdGJAW7o+oaoEKqk+uM5C9HPPn0="
  },
  "warnings": [],
  "errors": []
}

Response body parameters

The following table describes the response elements:

Element Description Type Notes
data Contains the response data. object
> name Specifies the name of the uploaded photo. string
> photo_id Specifies the photo ID (after it is processed). string
> url Specifies the URL of the uploaded photo. string
> sample Specifies the URL for a preview of that photo, for example for displaying on your frontend. string
> height Specifies the height of the uploaded photo in pixels. integer
> width Specifies the width of the uploaded photo in pixels. integer
> quality Specifies the quality of the uploaded photo following Booking.com standards. enum Possible values are low and high.
> message Specifies the preferred resolution if the uploaded photo is of low quality. string
> tag_ids Contains the photo tag(s) that describe the photo content. array of integers To retrieve all the photo tags used on Booking.com, see retrieving all photo tags.
> in_property_galleries Contains the metadata specific to the property-level photo gallery. object
>> property_id Specifies the unique property ID to which the property-level photo gallery belongs. string
>> url Specifies the URL of the property-level photo gallery. string
> in_room_galleries Contains the metadata specific to a room-level photo gallery. object
>> room_id Specifies the unique room ID to which the room-level photo gallery belongs. string
>> url Specifies the URL of the room-level photo gallery. string
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

Retrieving metadata of individual photo

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

The GET /properties/{property_id}/photos/{photo_id} request enables you to retrieve the metadata of a specific photo for a property.

Path parameters

The following table describes the path parameters:

Element Description Type Required/Optional Notes
property_id Specifies the unique property ID of the property you want to retrieve a photo's metadata for. integer required
photo_id Specifies the unique photo ID of the photo you want to retrieve metadata for. integer required

Response body example

The following is a successful response body example:

{
  "data": {
    "name": "original_125772783.jpg",
    "photo_id": "8-NjAmvGUuY",
    "url": "https://supply-xml.booking.com/photo-api/properties/1234567890/photos/8-NjAmvGUuY",
    "sample": "https://example.com/8ef/8ef267492f453018befb28391c641bb0c993ef32.jpg",
    "height": 960,
    "width": 1440,
    "quality": "high",
    "tag_ids": [1, 3, 7],
    "in_property_gallery": {
      "property_id": 1234567890,
      "url": "https://supply-xml.booking.com/photo-api/properties/1234567890/gallery"
    },
    "in_room_galleries": [
      {
        "room_id": 123456789002,
        "url": "https://supply-xml.booking.com/photo-api/properties/1234567890/rooms/123456789002/gallery"
      }
    ]
  },
  "meta": {
    "ruid": "UmFuZG9tSVYkc2RlIyh9YWFOqyMkTMAreuCQEh5uXaBtUCNfQh5H7s59v9v3HswKuMitZoGvAfLlPYkWtW3ohDrMvfLJAzlLeBZ1LKUVBNo="
  },
  "errors": [],
  "warnings": []
}

Response body parameters

The following table describes the response elements:

Element Description Type Notes
data Contains the response data. object
> name Specifies the name of the uploaded photo. string
> photo_id Specifies the photo id. string
> url Specifies the URL of the uploaded photo. string
> sample Specifies the original URL of the photo. string
> height Specifies the height of the uploaded photo in pixels. integer
> width Specifies the width of the uploaded photo in pixels. integer
> quality Specifies the quality of the uploaded photo following Booking.com standards. enum Possible values are low and high.
> message Specifies the preferred resolution if the uploaded photo is of low quality. string
> tag_ids Contains the photo tag(s) that describe the photo content. array of integers To retrieve all the photo tags used on Booking.com, see retrieving all photo tags.
> in_property_galleries Contains the metadata specific to the property-level photo gallery. object
>> property_id Specifies the unique property ID to which the property-level photo gallery belongs. string
>> url Specifies the URL of the property-level photo gallery. string
> in_room_galleries Contains the metadata specific to a room-level photo gallery. object
>> room_id Specifies the unique room ID to which the room-level photo gallery belongs. string
>> url Specifies the URL of the room-level photo gallery. string
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

Deleting a photo

DELETE https://supply-xml.booking.com/photo-api/properties/{property_id}/photos/{photo_id}

The DELETE /properties/{property_id}/photos/{photo_id} request enables you to permanently delete a specific photo for a property. It is not possible to delete more than one photo per request.

Path parameters

The following table describes the path parameters:

Element Description Type Required/Optional Notes
property_id Specifies the unique property ID of the property you want to delete a photo for. integer required
photo_id Specifies the unique photo ID of the photo you want to delete. integer required You can only delete the property's main photo when the property is closed. If it is open and bookable, you must first set a different photo as the main photo. See, setting a main photo

Response body example

The following is a successful response body example:

{
  "data": {
    "success": 1
  },
  "errors": [],
  "meta": {
    "ruid": "UmFuZG9tSVYkc2RlIyh9YQUrOThXN/oqVMumdc9B5QdAneVkZDLauuIPkoD5f2I5e4Ck+SIXzBmeoOLGPupPZoJJaHgR0v0huOR+e/09HJd+AasYDki84Q=="
  },
  "warnings": []
}

Response body parameters

The following table describes the response elements:

Element Description Type Notes
data Contains the response data. object
> success Indicates the success of the operation. Boolean
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