Home

Using the Photo API

The Photo API enables you to efficiently 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. You can see how to use each in the following breakdown:

  • Managing photos:

    • Uploading photos: This includes uploading one or more photos per property, and adding and updating photo tags to describe the content of those photos.
    • Retrieving photo statuses: This refers to retrieving the status of the photos you uploaded, informing you of upload success, potential errors, or duplicates.
    • Retrieving photo metadata: This enables you to find all of the relevant metadata of your uploaded photos, also informing you of whether photos are in a property- or room-level photo gallery.

  • Managing photo galleries:

    • Managing property-level photo gallery: This includes retrieving, adding, removing, and reordering 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.
    • Managing room-level photo galleries: This includes retrieving, adding, removing, and reordering photos in one or more room-level galleries.

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 undertsanding of how to 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 when it is not in a room-level, you can still retrieve it by calling the /properties/{property_id}/photos endpoint.

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

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.

Have ideas for how we can improve your experience of using the Photo API? To give us your feedback:

  1. Log in to the Connectivity Portal
  2. In the top menu, click .
  3. Select Give Feedback.
Is this page helpful?    Yes   |    No