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:
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:
- Upload one or more photos, see uploading photos.
→ You can also use tags to describe the photo content. - 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 permanentphoto_id
. -
Use their
photo_id
to:- 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.
-
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 when it is not in a room-level, you can still retrieve it by calling the/properties/{property_id}/photos
endpoint.
-
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:
- Log in to the Connectivity Portal
- In the top menu, click .
- Select Give Feedback.