Requirements and best practicesCopy link

This section highlights requirements and best practices to keep in mind when developing your Image API integration.

If you are looking for information about capabilities offered by additional APIs, such as Property API or Product API, refer to the overview page.

Development requirements

Before implementing Image API, make sure you meet these requirements:

• Have a reliable connection to the Internet
• Be able to initiate HTTPS connections to Expedia Group servers and provide authentication (username/password)
• Expedia will only accept request sent using TLS v1.2 protocol for PCI compliance
• Be able to connect using the provided Expedia Group URL. Expedia Group does not support connection to the API directly via IP address, as this address is subject to change without notice.
  • If you prefer IP addresses for communication performance reasons, you may consider implementing an address caching strategy to reduce DNS lookups for the URLs.
  • If you whitelist outbound connections, you must do so using a URL pattern rather than an IP range, as Expedia Group cannot guarantee a specific IP range/subnet.
• Be able to generate JSON documents for read, create, and update requests, and accept JSON payloads for create and update requests.
• Use Availability and Rates (AR) API to send XML updates about inventory availability.
• Use either Booking Retrieval and Booking Confirmation APIs or Booking Notification API to
  • Be able to retrieve or receive bookings (reservations, modifications and cancellations) using XML messages
  • Be able to provide confirmation numbers for bookings (reservations, modifications, and cancellations) using XML messages
  • Be able to troubleshoot errors and warning scenarios according to this specification’s recommendations
• Abide by Expedia Group’s terms and conditions

JSON requirements

The service will return JSON documents for read, create, and update requests, and accept JSON payloads for create and update requests.

In addition:

• Entity - All successful responses returned by this API are encapsulated within an HTTP entity. Entities are used to make successful responses generic across different resources and operations. The <Entity> element may represent a single object, or multiple objects. When referring to multiple objects, it is called an array.
• Errors - If a request produces one or more errors, the response will return an array of one or more errors. If errors are present, Entity will not be present.
• MUST-IGNORE - The service is constantly evolving and you should utilize a must-ignore policy. If Image API starts returning additional data elements in responses, you should ignore the data elements you do not need.

Security requirements

Image API uses secure endpoints provided by Expedia Group, https://services.expediapartnercentral.com/. For a complete list of endpoints for different functions within Image API, refer to Requests.

Here are the general guidelines for Image API integration:

• HTTP 1.1-Our API only supports HTTP 1.1. Requests made with HTTP 1.0 explicitly will be denied.

• TLS 1.2 is required. SSL has been deprecated as a supported protocol and its use is not permitted with integrations to Expedia Group systems. Instead, use TLS to provide over-the-wire encryption (HTTPS).

  Note that Expedia Group’s servers are not configured to accept posts over unsecured HTTP.

• Be secured using basic authentication

Minimum certification requirements

Partners who want to adopt Image API are required to successfully complete end-to-end certification with Expedia Group teams. Specifically, the partner must be able to

• Read (GET) data for single property
• Create (POST) single image
• Update/modify single image via full overlay (PUT) and/or partial update (PATCH).
• Set Image Status to inactive via PUT and/or PATCH or able to remove (DELETE) Image
• Categorize images at property level or room level by specifying the roomTypes node using Create (POST) or Update (PUT/PATCH)

Best practices

When designing the electronic interface used to connect to Expedia Group servers to read, create, update, and delete images, you should make sure to read and understand the following guidelines, recommendations and best practices.

DO:

• Use Expedia property and room IDs to identify correct rooms and rate plans to be updated. The property ID is defined by Expedia Group and uniquely identifies a property in the Expedia Group system, which you map to the code in your system. Property IDs are referred to in the endpoint URL. You must also ensure the correct Expedia Group room and rate IDs are accurately mapped in their implementation of Product API to make sure the right rooms and/or rate plans are updated when the API sends updates.
• Send high-resolution images. Expedia Group recommends at least 2,880 pixels on the image’s longest side.
• Refer to the photo guidelines when selecting images to load on Expedia Group points of sale.
• Use HTTP/HTTPS servers or Amazon Web Services (AWS) locations to host images. Expedia Group cannot accept other types of locations like FTP or SFTP.
• Ensure monitoring is in place in the Image API implementation to validate the success rate of updates, including visibility in error details/messaging.

DON’T:

• Send low-resolution images.
• Send multiple sizes of the same image. Expedia Group will produce all required thumbnails and other derivatives from the high-resolution images submitted.
• Ignore any errors that might be received. These may signal connection issues or problems with your request.

Alarms and monitoring

You should ensure monitoring is in place for your API implementation so you can get detailed information on any errors. Alarms should also be created to notify you when the rate of message errors returned by Expedia Group exceeds an acceptable threshold. You should review errors frequently to ensure that room types and rate plans are correct, and that all updates are processed accurately. Failure to do so may result in the incorrect images or mislabeled images being displayed on Expedia Group’s points of sale.

Image read function

The image read function allows you to retrieve images assigned to the property in Expedia Group’s system. The API allows you to read all existing images for your properties whether they were added with Image API, Partner Central, or Property API. The result will be an array of images assigned to the property. Note that only the first 1,000 active images associated with the property are returned.

To get started:

• If you already use other Expedia Group APIs, access https://services.expediapartnercentral.com/properties/%5bExpediaPropertyId%5d/images in a browser and provide your API username and password credentials when prompted.
• If you are a new partner, you must register with Expedia and obtain API credentials by submitting your request on this page. You can also obtain the rights to use a test property to run tests before going to production with a new integration.

Example:

1{
2  "entity": [
3    {
4      "resourceId": "6d266700-f59c-4f61-be81-fd43e4da9d4e",
5      "publishedImageUrl": "https://images.trvl-media.com/hotels/13000000/12940000/12933900/12933870/6d266700_b.jpg",
6      "displayable": true,
7      "state": "Published",
8      "categoryCode": "SUNDECK",
9      "propertyFeatured": true,
10      "lastUpdateDateTime": "2016-08-19 15:29:00.000 GMT",
11      "originalImageUrl": "https://some_url_that_expedia_whitelisted_for_our_partner.com/highresimage.jpg",
12      "fileName": "65466_78961ABC.jpg"
13    }
14  ]
15}

Adding images (POST)

Those interested in uploading images to Expedia Group can do so using the POST feature. When you post a new image for a property, Expedia Group first validates that the reference given is valid and can be accessed. To add new images, you will have to first contact Expedia Group to enable communication between Expedia Group servers and your image hosting solution.

Once Expedia Group has validated that the image location can be accessed, a successful response will be returned, along with the image resource ID. This is the identifier you can then use to obtain additional information about the image(s) created.

If the image is not corrupted, and meets the minimum size requirements, it should then eventually be published, within a few minutes. There is currently no mechanism to proactively inform you of images that either went live, or failed to be published. It is your responsibility to verify the status of your images using either the GET images endpoint, or by querying each image individually using the resource ID returned upon posting the image, to confirm its publication.

If the image is corrupted or doesn't meet Expedia Group’s minimum image resolution requirements, it will be put in the REJECTED state, along with an appropriate comment explaining the reasons why it was rejected. At this point, you should DELETE this image and resubmit it for processing after fixing the problem (usually by providing a higher resolution image or a non-corrupted file).

If the image is accepted, it will quickly be published. After that, Expedia Group audits all images within a few hours to make sure they meet the Expedia guidelines. If they do not meet the guidelines, they will be inactivated, in which case additional comments might also be added to the image's metadata. Once again, you can inquire about the image using the GET operation and the image's resource ID.

An example of a valid POST message is provided here, but you will not be able to try this on their own until you contact Expedia Group to get their domain whitelisted.

Example:

1{
2  "originalImageUrl": "https://some_url_that_expedia_whitelisted_for_our_partner.com/highresimage.jpg",
3  "categoryCode": "HOTEL_FRONT",
4  "propertyFeatured": true,
5  "roomTypes": [
6    {
7      "resourceId": 12345,
8      "roomTypeFeatured": false
9    }
10  ]
11}

Once received, Expedia Group will first validate if the location is valid, and if yes, will return a successful response along with the RECEIVED state and the new image resource ID. To confirm the processing is successful, it is recommended for you to verify the state of the images by leveraging the resource ID:

GET https://services.expediapartnercentral.com/properties/ExpediaPropertyId/images/imageResourceId

1{
2  "entity": {
3    "resourceId": "6d266700-f59c-4f61-be81-fd43e4da9d4e",
4    "publishedImageUrl": "https://images.trvl-media.com/hotels/13000000/12940000/12933900/12933870/6d266700_b.jpg",
5    "displayable": true,
6    "state": "Published",
7    "categoryCode": "SUNDECK",
8    "propertyFeatured": true,
9    "lastUpdateDateTime": "2016-08-19 15:29:00.000 GMT",
10    "originalImageUrl": "https://some_url_that_expedia_whitelisted_for_our_partner.com/highresimage.jpg"
11  }
12}

Using PATCH to update images

The PATCH modify operation is a way for you to send a request containing only the data you would like to modify about the image, as opposed to the entire data about the resource. From your perspective, the PATCH feature allows for modification of the image resource without having to pre-load the entire data about the resource.

Expedia Group implemented the Merge-PATCH strategy for Image API. You can send any of the top-level elements you'd like to modify, and omit the ones you do not want to change. Expedia Group will take care of merging the resource updates and preserve what was not included in your PATCH request.

It is important to note that any top-level object is treated as a full overlay even when using Merge-PATCH. For example, if you decide to include the room type object, all the elements/values of that object need to be included as this specific object update will be treated as a full overlay.

Please refer to the Examples section for samples of how to use the PATCH operation.

Assigning an image to one or more room types

By providing the roomTypes array with the room types' resource IDs, you can tell Expedia Group which images belong to which room types. Expedia Group allows you to specify one or more room types when you add a new image. For each room type, you can specify whether the image should be the featured one or not.

It is also possible to modify an image's metadata with PATCH to change the room type(s) assignment. With PATCH, you can either add different room types, remove any room type association, or just change the room types.

The room type resource IDs need to be provided. To obtain room type resource IDs, theProduct API can be used.

Transfer image management from Property API to Image API

Expedia Group recommends that Image API should always be used to load images if resources are available to code to it. Image API supports associating images to specific room types, which can help convert customer views into bookings.

If the reason for adopting Image API is to completely discontinue sending images with Property API, then control of the images needs to be converted to Image API.

Do so with the following steps:

1. GET the property details with Property API.
2. Send a PUT update (full overlay) including all existing content, but with empty image arrays via Property API. This will deactivate these images in the Expedia Group system.
3. Send the images with a create (POST) in Image API. This will fully transfer image control of those images to Image API.

If steps 1 and 2 are skipped, and only step step 3 is completed, the images will be flagged as duplicates. If an update (PATCH) of the images originally created via Property API using Image API is attempted, the creator of the images is still Property API in Expedia Group’s system. Thus, any subsequent content updates with an empty image array using Property API would delete these images again.