Last updated

Using the Photo API

The Photo API enables you to add, manage, and organise the photos of your properties. This improves the visibility of what your properties have to offer and can help drive conversion.

What is possible with the Photo API?

On a high level, the photo API enables you to both manage photos and photo galleries. The following breakdown shows the individual capabilities:

  • Managing photos

    • Upload photos: Upload one or more photos per property, and add or update photo tags to describe the content of those photos. Whenever a new photo is uploaded, by default, the API places the photo in the property-level photo gallery.
    • Retrieve photo statuses: Retrieve the status of the photos you uploaded including upload status, potential errors, or duplicates.
    • Retrieve photo metadata: Find all relevant metadata of your uploaded photos including whether the photos are in a property- or room-level photo gallery.

  • Managing photo galleries

    • Manage property-level photo gallery: Retrieve, add, remove, or reorder photos in a property-level (listing's) photo gallery. You can also set a main photo for a property, which is the photo guests see when searching on Booking.com.
    • Manage room-level photo galleries: Retrieve, add, remove, or reorder photos in one or more room-level galleries.
    • Manage smart ordering: By default, photos in the property-level photo gallery are shown to the guests in the order optimised using Booking.com's machine learning algorithm, also known as smart ordering. If the property prefers to set the order of appearance of the photos using the API or extranet, make sure to disable smart ordering.
Photos limit per property

You can upload a maximum of 299 photos per property.

Why use the Photo API?

Using the Photo API is beneficial for the following reasons:

  • The Photo API does not use an overlay system and is completely separate from the Content API. This means you won't affect any other property content, which could result in potential data loss.
  • You can provide your properties with much more control in uploading, managing, and organising their photos.
  • The level in which you can manage photos and photo galleries is more detailed and clearer.
  • The Photo API is following modern API standards, which makes it both easier to implement and maintain.

How does the Photo API work?

To understand how the Photo API works on a high level, look at the following diagram and description:

Photo API data model

Figure 1. A simplified example of the Photo API data model

In this scenario you want to manage the photos and photo galleries for a property with two room types:

  • You uploaded three photos in total: All uploaded photos are automatically placed in the property-level photo gallery.
  • You added one photo to each room-level photo gallery, connecting them to room types with ID 11 and 22 respectively.
  • The third photo with ID 333 only appears in the property-level gallery, while the other two (with ids 111 and 222) appear in both room-level and property-level galleries.
This is a simplified version of the Photo API data model

The diagram doesn't show all the possible fields for each object. It only aims to provide a high-level understanding of how the different components are structured.

How to use the Photo API

Main URL and use of shortened endpoint paths

The Photo API's main URL is https://supply-xml.booking.com/photo-api. All shortened endpoint paths imply that you must add the main URL. For example: /tags becomes https://supply-xml.booking.com/photo-api/tags in an actual request.

Authentication

Photo API uses the same authentication methods as other APIs.

Use case

Follow these steps of an ideal workflow to understand how to use the Photo API:

  1. Upload one or more photos, see uploading photos.
    → You can also use tags to describe the photo content.

  2. Use the photo_batch_id to retrieve the status of the photo(s) you uploaded. See retrieving photo statuses.
    → After the photos are successfully processed, you can find their permanent photo_id.

  3. Use their photo_id to:

  4. Set a photo as the main photo for a property so that potential guests see it in the search results. See setting a main photo.

  5. Remove undesired photos from:

    • Property-level photo gallery.
    • A room-level photo gallery.
      → This does not delete the photo, it just removes it from a photo gallery. If you remove a photo from the property-level photo gallery when it is not in a room-level photo gallery, you can still retrieve it by calling the /properties/{property_id}/photos endpoint.

  6. Permanently delete a photo. See deleting a photo.

Going live

Before you go live with your API integration, you'll need to meet certain requirements. For more information, see Going Live.

Contact us

Before you go live with your Photo API integration, we recommend contacting your account manager or the Connectivity Support team.

Need help integrating with Photo API? The experts in our Connectivity Support team are here to help.

Do you want us to improve this page? Click Yes | No in the Was this page helpful? box at the bottom of this page.

Previous page
Next page