Managing photos

This section describes all the possible actions related to managing photos for a property through the Photo API.

Uploading photos

Quick 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.

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

Only upload photos you have not yet uploaded, which means to only reupload a photo when the original is permanently deleted and not, for example, removed from the property-level photo gallery.

If you upload photos you have uploaded before, the system responds with a duplicate message when you retrieve the photo (batch) status, which includes the photo_id of the original photo. This duplicate photo does not appear in the property-level gallery.

Path parameters

The following table describes what 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 what elements you must add in the request body:

Element Description Type Required/Optional Notes
photos Contains photo objects. array required The maximum amount of photos you can upload at a time is 300.
: url Specifies the URL of the photo. object 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. 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

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 what 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 what 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 tags_id array, you remove 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 photo statuses

Quick actions:

Retrieving status of all photo batches

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

After seven days have passed since you uploaded the photos, you can only retrieve photo statuses by photo_batch_id and 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 uploaded photo. string Possible values are: bad_url, cancelled, delete, duplicate, enqueued, error, error_decode, new, ok.
: 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 status of individual photo batch

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: bad_url, cancelled, delete, duplicate, enqueued, error, error_decode, new, ok.
: 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 status of individual 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

Query parameters

The following table describes the query parameters:

Element Description Type Required/Optional Notes
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: bad_url, cancelled, delete, duplicate, enqueued, error, error_decode, new, ok.
: 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,
        "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": 1440,
        "height": 960,
        "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
: 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,
    "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
: 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 []
: 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