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:
- 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.
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:
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:
https://supply-xml.booking.com/photo-api/tags in an actual request.
Photo API uses the same authentication methods as other APIs.
Follow these steps of an ideal workflow to understand how to use the Photo API:
- Upload one or more photos, see uploading photos.
→ You can also use tags to describe the photo content.
- Use the
photo_batch_idto retrieve the status of the photo(s) you uploaded. See retrieving photo statuses.
→ After the photos are successfully processed, you can find their permanent
- Move photos from the default property-level photo gallery to specific room-level photo galleries. See moving photos to a room-level photo gallery.
- Change the order in which the photos appear in the property-level photo gallery. See reordering photos in the property-level photo gallery.
- Change the order in which the photos appear in a room-level photo gallery. See reordering photos in a room-level photo gallery.
💡 Photos in the property-level photo gallery are shown to the guests in the order optimised using smart ordering. Before changing the order of appearance of the photos in the property-level photo gallery, make sure to disable smart ordering.
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.
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
Permanently delete a photo. See deleting a photo.
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:
- Log in to the Connectivity Portal
- In the top menu, click .
- Select Give Feedback.