Connectivity Solutions / Instant Booking API / Documentation / /availability

Availability requests are sent by adding /availability to your endpoint and sending the parameters explained below in a POST request.

Hotel Availability

In the below example three hotels are requested and the response_type for each is different. The first one has availability ("available"), the second has no availability ("unavailable") and the third has an error ("error").

Request

{
  "api_version": 8,
  "start_date": "2017-05-01",
  "end_date": "2017-05-03",
  "party": [
    {
      "adults": 3
    },
    {
      "adults": 2,
      "children": [
        9,
        5
      ]
    }
  ],
  "language": "en_US",
  "query_key": "6167a22d1f87d2028bf60a8e5e27afa7_191_1360299600000_2_2",
  "currency": "USD",
  "user_country": "US",
  "device_type": "Desktop",
  "availability_id": "a2fd740a-ad02-476d-b314-925a125509be",
  "requested_payload": {
    "categories": {
      "room_type_details": false,
      "rate_plan_details": false,
      "room_rate_details": false,
      "hotel_details": false
    },
    "category_modifiers": {
      "partner_booking_data": false,
      "real_time_pricing": false,
      "multiple_room_rates": false,
      "photos": false,
      "text": false
    }
  },
  "hotels": [
    {
      "ta_hotel_id": 258705,
      "partner_hotel_code": "A123"
    },
    {
      "ta_hotel_id": 730099,
      "partner_hotel_code": "B456"
    },
    {
      "ta_hotel_id": 555555,
      "partner_hotel_code": "555"
    },
  ]
}

Parameters

Name

Type

Description

api_version

integer

The version of the API of this request.

start_date

string

The check-in date of the traveler using the hotel's time zone. The date is required to be in ISO8601 full-date format (YYYY-MM-DD).

end_date

string

The check-out date of the traveler using the hotel's time zone. The date is required to be in ISO8601 full-date format (YYYY-MM-DD).

party

array

Array of JSON objects representing number of adults and children traveling.

key	description	type
adults	The number of adults staying in the room.	integer
children	[Optional] The ages of any children staying in the room. If no children are requested Tripadvisor may send an empty children array. For example: "party":[{“adults": 2}{children:[]}]. Or no children at all. Both variants should be accepted.	integer array

Each Party object represents a request for a separate room. For example, "party":[{“adults": 2}] is a request for 1 room that accommodates 2 adults, or "party":[{"adults": 3},{"adults": 2, "children": [9,5]}] is a request for 1 room for 3 adults and 1 room for 2 adults and 2 children for a total of 2 rooms.

language

string

Language code (see Supported Languages). Language codes are a combination of the ISO 639-1 language codes and the ISO 3166-1 country codes. When used in an AvailabilityRequest, this is the language that Tripadvisor would prefer that the partner return with. When used in an AvailabilityResponse, this is the language that the partner is responding with.

If the partner does not have the language of the request, they can return a less specific language. e.g. If the request is asking for de_AT, then the response can be de.

query_key

string

String useful for debugging. It is recommended for this value to be logged.

currency

string

ISO 4217 currency code.

user_country

string

ISO 3166-1 alpha-2 country code.

device_type

string

Identifies the user’s device type. Takes values “Desktop”, “Mobile” or “Tablet”. This value is required if pricing differs by device type.

query_key

string

String useful for debugging. It is recommended for this value to be logged.

availability_id

string

Identifier primarily used for internal purposes. Partners implementing the API may ignore this parameter.

requested_payload

array

Each of these flags correspond to particular sets of information in the response. Currently Tripadvisor will always set the requested flag as False in Hotel Availability search. You are free to return whichever content you would like however at this time only Free Cancellation and Pay at Stay information is used in Hotel Availability. Additional content is displayed in the Booking Availability response for Instant Booking.

In the request, this signifies that these pieces of information are required. In the response, these flags indicate this information has been given to the best of your ability, there is not another call which will provide better information.

Scenario	Requested Flag	Acceptable Response Flag	Explanation and expectations
1	False	False	Partner is responding with the exact set of data being requested.
2	False	True	Partner is capable of responding with more data than what was asked in the request. This may be useful in case a Partner's system does not allow you split content per the Tripadvisor requirements.
3	True	True	Partner is providing the required pieces of information to the best of their knowledge. Best case, Partner provides all the content requested.
4	True	False	Partner cannot provide this information at this time, either due to an error in the partner's system / load capabilities. Tripadvisor may be unable to display the rest of your content.

Example: in a single hotel request with all flags set to false - i.e TA is requesting at least one room-rate to be returned (assuming there is availability for that hotel). Potential response options:

At minimum we expect to receive a single room-rate with the response flags set to all be false.
However, for the same request, a Partner is permitted to send TA more information. For example, Partner can potentially send all room-rates (instead of just one) for that hotel. Here a Partner is expected to set the "multiple_room_rates_included" to "true"

Example: the request has flags for "room_type_details" and "photos" set to "true. Acceptable responses where Partner sets "room_type_details" and "photos" flag to "true"

Partner provides photos for each room type
It is possible that the partner just does not have access to / full coverage for the content being requested. It is expected that the response flags for "photos" and "room_type_details" are set to "true" but the payload returned may not contain any photos. Partner is indicating that they understand the requested fields, are trying to provide that data to us, and there is no better content available in a separate call or otherwise

Responses should include as much extra information as they can without incurring significant costs in time the call takes or rate of calls supported. If any of these fields are missing they will be interpreted as false. New flags may be added in the future in which case they should either not be returned or returned as false.

Response

The below represents the minimum amount of information you can provide in order to be displayed in Tripadvisor's Hotel Availability search.

Currently Tripadvisor will always set the requested flag as False in Hotel Availability search. You are free to return whichever content you would like however at this time only Free Cancellation and Pay at Stay information is used in Hotel Availability. Additional content is displayed in the Booking Availability response for Instant Booking.

{
  "api_version": 8,
  "language": "en_US",
  "availability_request": {
    "api_version": 8,
    "start_date": "2017-05-01",
    "end_date": "2017-05-03",
    "party": [
      {
        "adults": 3
      },
      {
        "adults": 2,
        "children": [
          9,
          5
        ]
      }
    ],
    "language": "en_US",
    "query_key": "6167a22d1f87d2028bf60a8e5e27afa7_191_1360299600000_2_2",
    "currency": "USD",
    "user_country": "US",
    "device_type": "Desktop",
    "availability_id": "a2fd740a-ad02-476d-b314-925a125509be",
    "requested_payload": {
      "categories": {
        "room_type_details": false,
        "rate_plan_details": false,
        "room_rate_details": false,
        "hotel_details": false
      },
      "category_modifiers": {
        "partner_booking_data": false,
        "real_time_pricing": false,
        "multiple_room_rates": false,
        "photos": false,
        "text": false
      }
    },
    "hotels": [
      {
        "ta_hotel_id": 258705,
        "partner_hotel_code": "A123"
      },
      {
        "ta_hotel_id": 730099,
        "partner_hotel_code": "B456"
      },
      {
        "ta_hotel_id": 555555,
        "partner_hotel_code": "555"
      },
    ]
  },
  "response_payload": {
    "categories": {
      "room_type_details": false,
      "rate_plan_details": false,
      "room_rate_details": false,
      "hotel_details": false
    },
    "category_modifiers": {
      "partner_booking_data": false,
      "real_time_pricing": false,
      "multiple_room_rates": false,
      "photos": false,
      "text": false
    }
  },
  "hotels": {
    "A123": {
      "response_type": "available",
      "available": {
        "room_types": {
          "1": {
            "persistent_room_type_code": "king1"
            "name": "Deluxe King Room",
          },
          "2": {
            "persistent_room_type_code": "king2"
            "name": "Deluxe King Room - Non Smoking",
          }
        },
        "rate_plans": {
          "1": {
            "persistent_rate_plan_code": "BR21"
            "name": "Best Available Rate",
          },
          "2": {
            "persistent_rate_plan_code": "OL44"
            "name": "Online Discount",
          }
        },
        "room_rates": {
          "1": {
            "persistent_room_rate_code": "21dr-wi4g-aaa9-kg2np",
            "room_type_key": "1",
            "rate_plan_key": "1",
            "url": "http: //www.partner-site.com/hotel_commonwealth/fenway_room?start_date=2017-05-01&end_date=2017-05-03&num_adults=3&num_child=2",
            "line_items": [
              {
                "price": {
                  "requested_currency_price": {
                    "amount": 220,
                    "currency": "USD"
                  }
                },
                "type": "rate",
                "paid_at_checkout": false,
                },
              {
                "price": {
                  "requested_currency_price": {
                    "amount": 20,
                    "currency": "USD"
                  }
                },
                "type": "tax",
                "sub_type": "tax_city",
                "paid_at_checkout": false,
                }
            ]
          },
          "2": {
            "persistent_room_rate_code": "581d-la3n-pg9a-vnr3",
            "room_type_key": "1",
            "rate_plan_key": "2",
            "url": "http: //www.partner-site.com/hotel_commonwealth/fenway_room2?start_date=2017-05-01&end_date=2017-05-03&num_adults=3&num_child=2",
            "line_items": [
              {
                "price": {
                  "requested_currency_price": {
                    "amount": 200,
                    "currency": "USD"
                  }
                },
                "type": "rate",
                "paid_at_checkout": false,
                },
              {
                "price": {
                  "requested_currency_price": {
                    "amount": 20,
                    "currency": "USD"
                  }
                },
                "type": "tax",
                "sub_type": "tax_vat",
                "paid_at_checkout": false,
                }
            ]
          },
          "3": {
            "persistent_room_rate_code": "nv3i-lgex-kxx2-ajge",
            "room_type_key": "2",
            "rate_plan_key": "1",
            "url": "http: //www.partner-site.com/hotel_commonwealth/fenway_room3?start_date=2017-05-01&end_date=2017-05-03&num_adults=3&num_child=2",
            "line_items": [
              {
                "price": {
                  "requested_currency_price": {
                    "amount": 180,
                    "currency": "USD"
                  }
                },
                "type": "rate",
                "paid_at_checkout": false,
                },
              {
                "price": {
                  "requested_currency_price": {
                    "amount": 20,
                    "currency": "USD"
                  }
                },
                "type": "fee",
                "sub_type": "fee_resort",
                "paid_at_checkout": false,
                }
            ]
          }
        }
      }
    },    
    "B456": {
      "response_type": "unavailable"
    },
    "555": {
      "response_type": "error",
      "error": {
        error_code: 3
        message: "Unknown hotel id was requested."
      }
    }
  }
}

Booking Availability

Booking Availability is specifically used for instant booking. All requested payload flags are set to True in the request.

Request

{
  "api_version": 8,
  "start_date": "2017-05-01",
  "end_date": "2017-05-03",
  "party": [
    {
      "adults": 3
    },
    {
      "adults": 2,
      "children": [
        9,
        5
      ]
    }
  ],
  "language": "en_US",
  "query_key": "6167a22d1f87d2028bf60a8e5e27afa7_191_1360299600000_2_2",
  "currency": "USD",
  "user_country": "US",
  "device_type": "Desktop",
  "availability_id": "a2fd740a-ad02-476d-b314-925a125509be",
  "requested_payload": {
    "categories": {
      "room_type_details": true,
      "rate_plan_details": true,
      "room_rate_details": true,
      "hotel_details": true
    },
    "category_modifiers": {
      "partner_booking_data": true,
      "real_time_pricing": true,
      "multiple_room_rates": true,
      "photos": true,
      "text": true
    }
  },
  "hotels": [
    {
      "ta_hotel_id": 258705,
      "partner_hotel_code": "A123"
    }
  ]
}

Response

{
  "api_version": 8,
  "language": "en_US",
  "availability_request": {
    "api_version": 8,
    "start_date": "2017-05-01",
    "end_date": "2017-05-03",
    "party": [
      {
        "adults": 3
      },
      {
        "adults": 2,
        "children": [
          9,
          5
        ]
      }
    ],
    "language": "en_US",
    "query_key": "6167a22d1f87d2028bf60a8e5e27afa7_191_1360299600000_2_2",
    "currency": "USD",
    "user_country": "US",
    "device_type": "Desktop",
    "availability_id": "a2fd740a-ad02-476d-b314-925a125509be",
    "requested_payload": {
      "categories": {
        "room_type_details": true,
        "rate_plan_details": true,
        "room_rate_details": true,
        "hotel_details": true
      },
      "category_modifiers": {
        "partner_booking_data": true,
        "real_time_pricing": true,
        "multiple_room_rates": true,
        "photos": true,
        "text": true
      }
    },
    "hotels": [
      {
        "ta_hotel_id": 258705,
        "partner_hotel_code": "A123"
      }
    ]
  },
  "response_payload": {
    "categories": {
      "room_type_details": true,
      "rate_plan_details": true,
      "room_rate_details": true,
      "hotel_details": true
    },
    "category_modifiers": {
      "partner_booking_data": true,
      "real_time_pricing": true,
      "multiple_room_rates": true,
      "photos": true,
      "text": true
    }
  },
  "hotels": {
    "A123": {
      "response_type": "available",
      "available": {
        "room_types": {
          "1": {
            "persistent_room_type_code": "king1",
            "name": "Deluxe King Room",
            "description": "Plush King bed, deluxe beddings, recently renovated bathroom, smoking permitted",
            "photos": [
              {
                "url": "https://www.example.com/FenwayRoomBed.jpg",
                "width": 480,
                "height": 270,
                "caption": "Image of King Bed"
              }
            ],
            "room_amenities": {
              "standard": [
                20,
                900118
              ],
              "custom": [
                "My custom chair",
                "Wolf appliances"
              ]
            },
            "room_size": {
              "value": 500,
              "unit": "square_feet"
            },
            "bed_configurations": [
              {
                "standard": [
                  {
                    "code": 3,
                    "count": 1
                  }
                ],
                "custom": [
                  {
                    "name": "Loft",
                    "count": 1
                  }
                ]
              }
            ],
            "extra_bed_configurations": [
              {
                "standard": [
                  {
                    "count": 1,
                    "code": 900302
                  }
                ]
              },
              {
                "custom": [
                  {
                    "count": 2,
                    "name": "Rollaway with wheel locks and adjustable height"
                  }
                ]
              }
            ],
            "room_view_types": {
              "standard": [
                10
              ],
              "custom": [
                "Northern Lights"
              ]
            },
            "accessibility_features": {
              "standard": [
                900501,
                900505
              ]
            },
            "max_occupancy": {
              "number_of_adults": 2,
              "number_of_children": 0
            },
            "room_smoking_policy": "smoking"
          },
          "2": {
            "persistent_room_type_code": "king2",
            "name": "Deluxe King Room - Non Smoking",
            "description": "Plush King bed, deluxe beddings, recently renovated bathroom",
            "photos": [
              {
                "url": "https://www.example.com/FenwayRoomBed.jpg",
                "width": 480,
                "height": 270,
                "caption": "Image of King Bed"
              }
            ],
            "room_amenities": {
              "standard": [
                20,
                101,
                900118
              ],
              "custom": [
                "My custom chair",
                "Wolf appliances"
              ]
            },
            "room_size": {
              "value": 400,
              "unit": "square_feet"
            },
            "bed_configurations": [
              {
                "standard": [
                  {
                    "code": 3,
                    "count": 1
                  }
                ]
              },
              {
                "standard": [
                  {
                    "code": 5,
                    "count": 2
                  }
                ]
              }
            ],
            "extra_bed_configurations": [
              {
                "standard": [
                  {
                    "count": 1,
                    "code": 4
                  }
                ]
              },
              {
                "custom": [
                  {
                    "count": 1,
                    "name": "Rollaway with wheel locks and adjustable height"
                  }
                ]
              }
            ],
            "room_view_types": {
              "standard": [
                10
              ],
              "custom": [
                "Northern Lights"
              ]
            },
            "accessibility_features": {
              "standard": [
                900504
              ]
            },
            "max_occupancy": {
              "number_of_adults": 2,
              "number_of_children": 0
            },
            "room_smoking_policy": "non_smoking"
          }
        },
        "rate_plans": {
          "1": {
            "persistent_rate_plan_code": "BR21",
            "name": "Best Available Rate",
            "description": "Best available rate available, suitable for family stays under 7 days",
            "photos": [
              {
                "url": "https://www.example.com/jetski01.jpg",
                "width": 480,
                "height": 270,
                "caption": "Image of complimentary jet skis that are provided."
              },
              {
                "url": "https://www.example.com/kayak01.jpg",
                "width": 480,
                "height": 270,
                "caption": "Image of kayak that are available to rent."
              }
            ],
            "rate_amenities": {
              "standard": [
                75
              ],
              "custom": [
                "Complimentary jet skis",
                "Kayak rentals"
              ]
            },
            "cancellation_policy": {
              "cancellation_summary": {
                "refundable": "full",
                "cancellation_deadline": "2017-06-15T00:00:00Z",
                "unstructured_cancellation_text": "Free cancellation until 2017-06-15 GMT. From 2017-06-15 GMT to 2017-06-20 GMT, there is a cancellation fee of 50.00 USD. From 2017-06-20 GMT until date and time of check-in, there is a fee of 25.00% of stay and a fee of one night's stay."
              },
              "cancellation_rules": [
                {
                  "start_datetime": "2017-06-15T00:00:00Z",
                  "end_datetime": "2017-06-20T00:00:00Z",
                  "fixed_fee": {
                    "fee": {
                      "amount": 50,
                      "currency": "USD"
                    },
                    "taxes_included": true
                  }
                },
                {
                  "start_datetime": "2017-06-20T00:00:00Z",
                  "percent_fee": {
                    "amount": 0.25
                  },
                  "night_fee": {
                    "num_nights": 1
                  }
                }
              ]
            },
            "meal_plan": {
              "standard": [
                22
              ],
              "custom": [
                "Brunch on weekend mornings"
              ]
            }
          },
          "2": {
            "persistent_rate_plan_code": "OL44",
            "name": "Online Discount",
            "description": "Exclusive, non-refundable rate for online reservations",
            "photos": [
              {
                "url": "https://www.example.com/nfl_cable.jpg",
                "width": 480,
                "height": 270,
                "caption": "Image of cable TV selection."
              }
            ],
            "rate_amenities": {
              "standard": [
                207
              ],
              "custom": [
                "NFL Network"
              ]
            },
            "cancellation_policy": {
              "cancellation_summary": {
                "refundable": "none",
                "unstructured_cancellation_text": "Non-refundable rate. No cancellations permitted, all taxes and fees will need to be paid."
              },
              "cancellation_rules": [
                {
                  "percent_fee": {
                    "amount": 1
                  }
                }
              ]
            },
            "meal_plan": {
              "standard": [
                22
              ],
              "custom": [
                "Brunch on weekend mornings"
              ]
            }
          }
        },
        "room_rates": {
          "1": {
            "persistent_room_rate_code": "21dr-wi4g-aaa9-kg2np",
            "room_type_key": "1",
            "rate_plan_key": "1",
            "partner_data": "{ 'myhotel_code': 'sfssc1', 'myroom_code': 'FENWAY', 'rate_hotel_info': 1 }",
            "payment_policy": "Valid ID with proof of payment required at check in",
            "other_policy": "Other policy room rate text",
            "rooms_remaining": 2,
            "line_items": [
              {
                "price": {
                  "requested_currency_price": {
                    "amount": 220,
                    "currency": "USD"
                  },
                  "currency_of_charge_price": {
                    "amount": 178,
                    "currency": "EUR"
                  }
                },
                "type": "rate",
                "paid_at_checkout": false
              },
              {
                "price": {
                  "requested_currency_price": {
                    "amount": 20,
                    "currency": "USD"
                  },
                  "currency_of_charge_price": {
                    "amount": 16,
                    "currency": "EUR"
                  }
                },
                "type": "tax",
                "sub_type": "tax_city",
                "paid_at_checkout": false
              }
            ]
          },
          "2": {
            "persistent_room_rate_code": "581d-la3n-pg9a-vnr3",
            "room_type_key": "1",
            "rate_plan_key": "2",
            "partner_data": "{ 'myhotel_code': 'sfssc1', 'myroom_code': 'FENWAY', 'rate_hotel_info': 2 }",
            "payment_policy": "Valid ID with proof of payment required at check in",
            "rooms_remaining": 1,
            "line_items": [
              {
                "price": {
                  "requested_currency_price": {
                    "amount": 200,
                    "currency": "USD"
                  },
                  "currency_of_charge_price": {
                    "amount": 161,
                    "currency": "EUR"
                  }
                },
                "type": "rate",
                "paid_at_checkout": false
              },
              {
                "price": {
                  "requested_currency_price": {
                    "amount": 20,
                    "currency": "USD"
                  },
                  "currency_of_charge_price": {
                    "amount": 16,
                    "currency": "EUR"
                  }
                },
                "type": "tax",
                "sub_type": "tax_environmental",
                "paid_at_checkout": false
              }
            ]
          },
          "3": {
            "persistent_room_rate_code": "nv3i-lgex-kxx2-ajge",
            "room_type_key": "2",
            "rate_plan_key": "1",
            "partner_data": "{ 'myhotel_code': 'sfssc1', 'myroom_code': 'FENWAY', 'rate_hotel_info': 3 }",
            "payment_policy": "Valid ID with proof of payment required at check in",
            "rooms_remaining": 5,
            "line_items": [
              {
                "price": {
                  "requested_currency_price": {
                    "amount": 180,
                    "currency": "USD"
                  },
                 "currency_of_charge_price": {
                    "amount": 145,
                    "currency": "EUR"
                  }
                },
                "type": "rate",
                "paid_at_checkout": false
              },
              {
                "price": {
                  "requested_currency_price": {
                    "amount": 20,
                    "currency": "USD"
                  },
                  "currency_of_charge_price": {
                    "amount": 16,
                    "currency": "EUR"
                  }
                },
                "type": "fee",
                "sub_type": "fee_resort",
                "paid_at_checkout": false
              }
            ]
          }
        },
        "hotel_details": {
          "name": "Hotel Commonwealth",
          "address1": "500 Commonwealth Avenue",
          "address2": "",
          "city": "Boston",
          "state": "Massachusetts",
          "postal_code": "02492",
          "phone": "8001234567",
          "checkin_checkout_policy": "For early check in, please contact hotel.",
          "checkin_time": "12:00",
          "checkout_time": "14:00",
          "hotel_smoking_policy": {
            "standard": [
              47
            ],
            "custom": [
              "Strict non smoking policy"
            ]
          },
          "pet_policy": {
            "standard": [
              6
            ],
            "custom": [
              "My own pet policy if applicable"
            ]
          },
          "child_policy": "All children are welcome",
          "parking_shuttle": {
            "standard": [
              185
            ],
            "custom": [
              "You can park on curbside in a metered spot"
            ]
          },
          "hotel_extra_bed": "Rollaway beds and cribs available on request",
          "hotel_amenities": {
            "standard": [
              5,
              15
            ],
            "custom": [
              "Bean bag chairs"
            ]
          },
          "photos": [
            {
              "url": "https://www.example.com/hotel_lobby.png",
              "width": 480,
              "height": 270,
              "caption": "Hotel Lobby"
            },
            {
              "url": "https://www.example.com/hotel_cafe.png",
              "width": 480,
              "height": 270,
              "caption": "Hotel Cafe"
            }
          ]
        },
        "partner_booking_details": {
          "accepted_credit_cards": [
            "Visa",
            "MasterCard",
            "AmericanExpress"
          ],
          "customer_support": {
            "phone_numbers": {
              "standard": [
                {
                  "country_code": "1",
                  "number": "5555555555",
                  "description": "Support phone line"
                }
              ]
            }
          },
            "terms_and_conditions": "Terms and conditions text",
            "terms_and_conditions_url": "http://www.example.com/terms_and_conditions",
            "payment_policy": "Payment policy partner text - use this field for payment policies that apply to the entire hotel",
            "other_policy": "Other policy partner text"
          }
        }
      }
    }
  }

Properties

Field	Type	Description
api_version	integer	The version of the API of this response.
language	string	Language code (see Supported Languages). Language codes are a combination of the ISO 639-1 language codes and the ISO 3166-1 country codes. When used in an AvailabilityRequest, this is the language that Tripadvisor would prefer that the partner return with. When used in an AvailabilityResponse, this is the language that the partner is responding with. If the partner does not have the language of the request, they can return a less specific language. e.g. If the request is asking for de_AT, then the response can be de.
availability_request	array	The request parameters.
response_payload	array	The response parameters.
hotels	hotels map	Map of partner_hotel_code to SingleHotelResponse entries. See below.

Hotels

Map of partner_hotel_code to SingleHotelResponse entries. Each key must match a corresponding partner_hotel_code in the request's hotel array. Note that each hotel may have a different response_type. This Map must be the same size as the list of the hotels in the request to be considered a valid response.

Field	Type	Description
response_type	string	The type of response returned for a hotel. Must be one of "available", "unavailable" or "error"
available	SingleHotel map	Representation of an individual hotel. Only if response_type is "available".
error	Error object	Only if response_type is "error". See Error.

RoomTypes

Field	Type	Description
room_types	RoomType map	Affected when all flags below are true: multiple_room_rates A map from room type keys to room types. At minimum, there must exist a room type entry for every unique room_type_key used in room_rates RoomRate objects.

Field Type Description

persistent_room_type_code

string

This code identifies unique room types. We expect that this code persists across future availability calls. The combination of persistent_room_type_code and partner_hotel_code must be unique.

name

string

The name of this room type. Room names must summarize 1-2 significant selling points for the room, ideally in less than 50 characters. For example, you can include the bed type configuration information and the room view in the name (e.g. “One Bedroom Suite, One King Bed”, “Courtyard King”, “Garden View Room, King”, “King Studio”); or simply match the room name to brand.com

If a room name consists of only numbers and symbols, or is shorter than 4 characters, it will be blocked from Instant Booking.

description

string

Provide when all flags below are true:

room_type_details
text

Longer room description. This will be displayed to end users, and should be in the language indicated by the lang parameter. Ideal room descriptions are 250-400 characters in length. They are written in third person voice and highlight selling point for the room. For example, "This one-bedroom suite has a king bed. This corner suite also features a separate living room with a sofa bed, a well-equipped kitchen with complimentary grocery delivery services, and Paul Mitchell bath products."

Language specific requirements will be applied. For example, if a room description in English consists of only numbers and symbols, or is shorter than 4 characters, it may be blocked. See supported HTML tags.

photos

Photo array

Provide when all flags below are true:

room_type_details
photos

List of photos of the room.

Image file type should be able to render on modern web browsers (JPG, PNG, GIF) (TIFF is not supported). Photos should support https.

room_amenities

object

Provide when all flags below are true:

room_type_details

Array of number codes. Each code corresponds to an amenity for the OpenTravel Hotel Amenity Code List. A map of the standard room amenities is listed under the Supported Amenities section. Hotel and room amenities are provided in separate parts of the response, and should not overlap. For example, amenities that have no bearing on the room (e.g. “free parking”) should not be included as a room amenity, but rather as a hotel amenity. We recommend rooms offer a minimum of 10 amenities.

The standard amenities will be returned as an integer array. If an amenity does not exist in the Supported Amenities list, then the Connectivity Partner may provide their own values. Return "custom":[ ] if no custom list exists.

Example:
{ "standard": [1 ,2, 5, 20, 60,], "custom": ["myamenity1", "myamenity2"] }

max_occupancy

map of string:int

Provide when all flags below are true:

room_type_details

Maximum number of guests permitted in the room. {"number_of_adults": <num_adult>, "number_of_children": <num_child>}.

Example: {"number_of_adults": 3, "number_of_children": 2 }.

room_size

map of string:int

Provide when all flags below are true:

room_type_details

Area of room in given units. If given, both value and unit are required.

Example: {"value":500, "unit": "square_feet" }

bed_configurations

object

Provide when all flags below are true:

room_type_details

A list of one or more possible configurations.

In order for a bed configuration to be valid, at least one element must exist in either the standard array or custom array.
Two or more configurations mean that the room could be configured to contain either (any) of these set ups.

For example, the following snippet illustrates how to represent two bed configurations, either one king bed OR two double beds:

"bed_configurations": [
  { "standard": [ { "count": 1, "code": 3 } ] },
  { "standard": [ { "count": 2, "code": 1 } ] }
]

The following snippet illustrates how to represent one bed configuration, with a crib AND a custom bunk bed:

"bed_configurations": [
  { "standard": [ { "count": 1, "code": 900302 } ],
    "custom": [ { "count": 1, "name": "Bunk bed"} ] }
]

Specify the bed types for a room, and if needed multiple bed configurations available. The type of bed provided is based on OpenTravel BED code table:

1	Double
2	Futon
3	King
4	Murphy Bed
5	Queen
6	Sofa Bed
7	Tatami Mats
8	Twin
9	Single
10	Full
11	Run of the House
12	Dorm Bed
900301	Roll-Away Bed
900302	Crib
900303	Unspecified Bed

extra_bed_configurations

object

Provide when all flags below are true:

room_type_details

A list of one or more possible extra bed configurations.
Extra bed configurations are configurations of extra beds that can physically be added to the RoomType for the guest on request. This service may or may not be included in the price of this room.

In order for an extra bed configuration to be valid, at least one element must exist in either the standard array or custom array.
Two or more configurations mean that the room could be configured to contain either (any) of these set ups.

For examples, see bed_configurations.

room_view_types

object

Provide when all flags below are true:

room_type_details

Choose from available OpenTravel codes for Room View Type when available:

1	Airport view
2	Bay view
3	City view
4	Courtyard view
5	Golf view
6	Harbor view
7	Intercoastal view
8	Lake view
9	Marina view
10	Mountain view
11	Ocean view
12	Pool view
13	River view
14	Water view
15	Beach view
16	Garden view
17	Park view
18	Forest view
19	Rain forest view
20	Various views
21	Limited view
22	Slope view
23	Strip view
24	Countryside view
25	Sea view

The standard room_view_types will be returned as an integer array. If a room_view_types does not exist in the table above, then the Connectivity Partner may provide their own values in the "custom" field as a string array. Return "custom":[ ] if no custom list exists.

Example: { "standard": [1,2,25], "custom": ["my own view of the dunes"] }

Example: {"standard": [2, 25], "custom": [ ]}

accessibility_features

object

Provide when all flags below are true:

room_type_details

Choose from available codes for accessibility features below:

900501	ADA compliant
900502	Compliant with local laws for disabled
900503	Accessible
900504	Mobility accessible
900505	In-room accessibility
900506	Accessible for blind
900507	Hearing accessible
900508	Roll-in shower
900509	Grab bars in bathroom

The standard accessibility features will be returned as an integer array. If an accessibility feature does not exist in the table above, then the Connectivity Partner may provide their own values in the "custom" field as a string array. Return "custom":[ ] if no custom list exists. We encourage you to avoid custom accesibility features, as this may hinder international rollout, and not allow display of standard accessibility icons for travelers.

Example: {"standard": [900504, 900505], "custom": [ ]}

room_smoking_policy

string

Provide when all flags below are true:

room_type_details

Options:

smoking
non_smoking

We also capture hotel_smoking_policy in HotelDetails. The options specified here should not invalidate information at the Hotel level. In the case of a mismatch, Tripadvisor will not display this information.

RatePlans

Field	Type	Description
rate_plans	RatePlan map	Affected when all flags below are true: multiple_room_rates A map from rate plan keys to rate plans. At minimum, there must exist a rate plan entry for every unique rate_plan_key used in room_rates RoomRate objects.

Field Type Description

persistent_rate_plan_code string This code identifies unique rate plans. We expect that this code persists across future availability calls. The combination of persistent_rate_plan_code and partner_hotel_code must be unique.

name

string

The name of this rate plan. For example, "Best Available Rate".

description

string

Provide when all flags below are true:

rate_plan_details
text

Longer rate description. This will be displayed to end users, and should be in the language indicated by the language parameter.

Language specific requirements will be applied. For example, if a room description in English consists of only numbers and symbols, or is shorter than 4 characters, it may be blocked. See supported HTML tags.

photos

Photo array

Provide when all flags below are true:

rate_plan_details
photos

List of photos representing the rate plan.

Image file type should be able to render on modern web browsers (JPG, PNG, GIF) (TIFF is not supported). Photos should support https.

rate_amenities

object

Provide when all flags below are true:

rate_plan_details

Array of number codes where each code corresponds to a rate amenity. Each code corresponds to an amenity for the OpenTravel Hotel Amenity Code List. A map of the standard room amenities is listed under the Supported Amenities section. Use this list to specify amenities that are specific to the rate plan, such as "Executive Club Lounge Access", "English Breakfast Included," etc.

The standard amenities will be returned as an integer array. If an amenity does not exist in the Supported Amenities list, then the Connectivity Partner may provide their own values.

Example:
{ "standard": [1,2,5], "custom": ["myamenity1", "myamenity2"] }

cancellation_policy

object

Provide when all flags below are true:

rate_plan_details

The cancellation policy:

Free cancellation until 2017-06-15 00:00:00Z.
From 2017-06-15 00:00:00 GMT to 2017-06-20 00:00:00 GMT, there is a cancellation fee of 50.00 USD.
After 2017-06-20 00:00:00 GMT, there is a fee of 25.00% of stay and a fee of one night's stay.

is represented in the API as:

"cancellation_policy": {
  "cancellation_summary": {
    "refundable": "full",
    "cancellation_deadline": "2017-06-15T00:00:00Z"
    "unstructured_cancellation_text": "Free cancellation until 2017-06-15. From 2017-06-15 00:00:00 GMT to 2017-06-20 00:00:00 GMT, there is a cancellation fee of 50.00 USD. After 2017-06-20 00:00:00 GMT, there is a fee of 25.00% of stay and a fee of one night's stay."
  },
  "cancellation_rules": [
    {
      "start_datetime": "2017-06-15T00:00:00Z",
      "end_datetime": "2017-06-20T00:00:00Z",
      "fixed_fee": {
        "fee": {
          "amount": 50.00,
          "currency": "USD"
        },
        "taxes_included": true
      }
    },
    {
      "start_datetime": "2017-06-20T00:00:00Z",
      "percent_fee": {
        "amount": 0.25
      },
      "night_fee": {
        "num_nights": 1.0
      }
    }
  ]
}

Name

Type

Description

cancellation_summary

array of objects

A summary of the fee schedule associated with cancellation.

refundable

string

This field is mandatory. Must be treated as dynamic and change over time according to the cancellation policy and deadline. In addition to this refundable information, cancellation_rules will enable Tripadvisor to display useful information to your customers, including "policy_info" text that is currently displayed to travelers.

Must be one of:

none - "no refund provided if cancelled"
partial - "After time of booking there is a charge less than the total reservation amount required for cancellation--the difference is then refunded"
full - "There exists a time between time of booking and time of arrival where the reservation may be cancelled without any charge to the user. Reservations whose free cancellation expires within N days of time of arrival may still be marked fully refundable unless time of booking is within N days of time of arrival"

Note: These fields are case sensitive and should be set as displayed above, they should not be for example 'Full' or 'None'.

Use cases can be found here.

cancellation_deadline

string

Required if refundable is set to full. The date and time after which it is not free to cancel a reservation. Must be in ISO8601 date-time format, which includes time zone, e.g. YYYY-MM-DDT00:00:00+00:00.

unstructured_cancellation_text

string

Provide when all flags below are true:

rate_plan_details (Same as parent)
text

Text describing the cancellation policy for the room. Should be in the language indicated by the language parameter.

cancellation_rules

array of objects

A detailed fee schedule associated with cancellation represented as rules. For each rule, At least one of 'fixed_fee', 'percent_fee', or 'night_fee' must be non-null. If more than one is non-null, it will be interpreted as multiple fees with different types taking effect at the same time.

An empty cancellation rule array will be interpreted as no information provided.

Name

Type

Description

start_datetime

string

The time which the cancellation rule takes effect. If null, no start time will be used. Must be in ISO8601 date-time format, which includes time zone, e.g. YYYY-MM-DDT00:00:00+00:00.

end_datetime

string

The time which the cancellation rule is no longer in effect. If null, no end time will be used. Must be in ISO8601 date-time format, which includes time zone, e.g. YYYY-MM-DDT00:00:00+00:00.

fixed_fee

number

Fixed fee charged in the given currency

Name	Type	Description
fee	number	Value in a given currency.
amount	number	The numeric value.
currency	string	ISO 4217 currency code.
taxes_included	boolean	If true, taxes are included in given amount. (Note, if there are no taxes charged, this should also be set to true)

percent_fee

number

Percent of booking that will be charged as a fee.

Name	Type	Description
amount	number	Percent value.

night_fee

boolean

Number of nights of booking that will be charged as a fee using the average nightly rate.

Name	Type	Description
num_nights	number	Number of nights

meal_plan

object

Provide when all flags below are true:

rate_plan_details

Choose from available OpenTravel codes for meal plans (MPT):

1	All inclusive
2	American
3	Bed & breakfast
4	Buffet breakfast
5	Caribbean breakfast
6	Continental breakfast
7	English breakfast
8	European plan
9	Family plan
10	Full board
11	Full breakfast
12	Half board / modified American plan
14	Room only
15	Self catering
17	Dinner bed and breakfast plan
18	Family American
19	Breakfast
20	Modified
21	Lunch
22	Dinner
23	Breakfast & lunch

The standard meal_plan will be returned as an integer array. If a meal_plan does not exist in the table above, then the Connectivity Partner may provide their own values in the "custom" field as a string array. Return "custom":[ ] if no custom list exists.

Example: { "standard": [1,2], "custom": ["All you can eat", "Special breakfast"] }

Example: {"standard": [2, 4], "custom": [ ]}

RoomRates

Field	Type	Description
room_rates	RoomRates map	Affected when all flags below are true: multiple_room_rates A map from room rate keys to room rates.

Field	Type	Description
persistent_room_rate_code	string	This code identifies unique room rates. We expect that this code persists across future availability calls. The combination of persistent_room_rate_code and partner_hotel_code must be unique.
room_type_key	string	Key referencing the applicable RoomType. This key must exist in the response's room_types map in order for this to be considered a valid response.
rate_plan_key	Price object	Key referencing the applicable RatePlan. This key must exist in the response's rate_plan map in order for this to be considered a valid response.
line_items	LineItem array	Affected when all flags below are true: real_time_pricing An object containing the detailed breakdown of charges. See below.
payment_policy	string	Provide when all flags below are true: room_rate_details text How will the partner use the credit or debit card information, e.g. charged immediately or hold. Large text field.
rooms_remaining	integer	Provide when all flags below are true: room_rate_details The number of rooms remaining / available at a given hotel for a given roomtype at a given price. This number should be >0.
other_policy	string	Provide when all flags below are true: room_rate_details text Miscellaneous policies.
url	string	The URL of the hotel on the partner site. This URL should go to a page that will show the price quoted and allow a user to book the room. Make this URL as specific as possible. This URL must be accessible with a GET request. If possible, the URL should go to a webpage in the language specified by the language parameter in the availability request.
partner_data	number, string or object	This data will not be interpreted by Tripadvisor, but will be sent back to the partner as-is when we attempt a booking. For example, this field might be used to store a partner 'rate key,’ ‘room key,’ and/or ‘product key.’ It can consist of arbitrary nested JSON, or a single string or number.

LineItems

An array of LineItem objects will contain a separate LineItem for rate, tax, and fee types with each corresponding sub_type.

Field

Type

Description

price

Price object

When partner_booking_data is set to false (hotel or expanded availability), at least one of requested_currency_price or currency_of_charge_price should be populated. When partner_booking_data is set to true (booking availability) and in /booking_submit, currency_of_charge_price should also be populated. requested_currency_price should also be returned if this was included in previous calls.

Field

Type

Description

requested_currency_price

string

Value in a given currency. requested_currency_price - Should be populated with the price in the currency sent in the request. You may also populated this field if you cannot determine that the price you have is in the currency of charge.

Field	Description
amount	The numeric value.
currency	ISO 4217 currency code

currency_of_charge_price

string

Value in a given currency. currency_of_charge_price - Should be populated with the price in the currency of charge. If you cannot determine the currency of charge, do not populate this field.

Field	Description
amount	The numeric value.
currency	ISO 4217 currency code

type

string

Describes the charge. Must be one of these values:

rate
tax
fee

sub_type

string

Describes the sub type of charge. Must be one of these values:

Code	Value	Common Examples of Line Items Which Fall Under This Type
tax_city	City taxes are defined as taxes applied by a local city or municipality, collected from the traveler at the time of their stay. These taxes may be flat rate or % based.	City Tax Tourism Tax Municipality Tax
fee_resort	Resort fees are mandatory additional charges (separate from the base rate) collected by the hotel at time of stay for resort-type accommodations	Resort Fee Amenity Fee
fee_transfer	Transfer fees are mandatory fees charged by the hotel for transportation from the guest's point of arrival to the hotel itself.	Transfer Fee Transfer Charge Connection Fee
tax_environmental	Environmental tax (sometimes called a green tax) are taxes or fees paid at the hotel at time of stay for impact to the local environment.	Environmental Tax Environmental Fee Green Tax
tax_vat	VAT or GST tax	VAT GST
tax_other	Other Taxes: Inclusive of any taxes or fees that do not fall into any of the above five subtypes
fee_other	Other Fees: Inclusive of any fees that do not fall into any of the above five subtypes

paid_at_checkout

boolean

True if the charge will be paid at the time of stay, false if it will be paid at time of booking.

Error

If the error object is present, please include as many complete attributes in the response as available.

Field

Type

Description

error

Error object

error_code

number

One of these error codes:

1	Unknown Error
2	Cannot Parse Request
3	Invalid Hotel ID. If partner_hotel_code is unknown, return this.
4	Timeout requested. Stops requests for the specified time.
5	Recoverable Error. Equivalent to http 503.

message

string

String describing the error. Used for debugging. Maximum length is 1000 characters.

timeout

number

Number of seconds we should stop sending requests for use with Error Code 4

Example Response:

{
  "api_version": 8,
  "language": "en_US",
  "availability_request": {
    "api_version": 8,
    "start_date": "2017-11-07",
    "end_date": "2017-11-08",
    "party": [
      {
        "adults": 2,
        "children": []
      }
    ],
    "language": "en_US",
    "currency": "USD",
    "user_country": "US",
    "device_type": "Desktop",
    "query_key": "6167a22d1f87d2028bf60a8e5e27afa7_191_1360299600000_2_2",
    "availability_id": "a2fd740a-ad02-476d-b314-925a125509be",
    "requested_payload": {
      "categories": {
        "room_type_details": false,
        "rate_plan_details": false,
        "room_rate_details": false,
        "hotel_details": false
      },
      "category_modifiers": {
        "partner_booking_data": false,
        "real_time_pricing": false,
        "multiple_room_rates": false,
        "photos": false,
        "text": false
      }
    },
    "hotels": [
      {
        "ta_hotel_id": 1,
        "partner_hotel_code": "HotelTest"
      }
    ]
  },
  "response_payload": {
    "categories": {
      "room_type_details": false,
      "rate_plan_details": false,
      "room_rate_details": false,
      "hotel_details": false
    },
    "category_modifiers": {
      "partner_booking_data": false,
      "real_time_pricing": false,
      "multiple_room_rates": false,
      "photos": false,
      "text": false
    }
  },
  "hotels": {
    "HotelTest": {
      "response_type": "error",
      "error": {
        "error_code": "3",
        "message": "Invalid hotel ID",
      }
    }
  }
}

Multiple Rooms

This example demonstrates how to work with multiple parties and multiple rooms.

The availability response is exactly the same whether a single room (single object in the ' party' array) or multiple rooms (multiple objects in the ' party' array) are in the availability request.

There are, however, some considerations as follows.

Using this as an example party array in the request: [{"adults": 3},{"adults": 2}], you can follow these guidelines when constructing the response:

When we request multiple rooms you should send all rooms that can accommodate the largest party.
In this case, you should respond with all available rooms that can accommodate 3 adults or more.
You should not send rooms that can accommodate only 2 adults or less.
You should also send only the room types that have available a number of rooms equal or greater than the number of parties. In this case there are two parties.
The prices should be the total for the number of days and party. We will then divide it and come up with the price per night and per guest.

Another example party array might look as follows: [{"adults": 1},{"adults": 2},{"adults": 4}]
You should return all the room types that can accommodate the maximum number of adults (in this case 4) and have available at least the same number as the number of rooms requested (in this case 3).

Suppose that a hotel has a room type called “Double suite” that can accommodate 4 adults and a room type called “Large Double suite” that can accommodate 6. Both these room types could be returned in the response if the hotel has at least 3 rooms available of each.

All room types that can accommodate 1 or 2 adults maximum have to be excluded, and all room types that have less than 3 rooms available also have to be excluded.

No availability

So for no availability, Tripadvisor would expect to see:

...
"response_type": "unavailable"
...

Free Cancellation and Pay At Stay

The below describes the implementation of 'Free Cancellation' and 'Pay At Stay' merchandizing shown on Tripadvisor Hotel Availability search. Please note that the information below is only applicable for Hotel Availability response. Merchandizing will only be shown if your cheapest rate is free to cancel and/or pay at stay. There is currently no merchandizing for non-refundable or partially-refundable rates. Information must be correct on the partner's landing page. Partners should only support this feature if it has minimal to no impact on their response time.

Free Cancellation

To be eligible for 'Free Cancellation' merchandizing your Hotel Availability response should return cancellation_policy in RatePlans. Not all objects in cancellation_policy are required, to reduce complexity it is recommended that you only send the following:

cancellation_policy

object

"cancellation_policy": {
  "cancellation_summary": {
    "refundable": "full",
    "cancellation_deadline": "2019-06-15T00:00:00Z"
  },

Name

Type

Description

cancellation_summary

array of objects

A summary of the fee schedule associated with cancellation.

refundable

string

This field is mandatory. Must be treated as dynamic and change over time according to the cancellation policy and deadline.

Must be one of:

none - "no refund provided if cancelled"
full - "There exists a time between time of booking and time of arrival where the reservation may be cancelled without any charge to the user. Reservations whose free cancellation expires within N days of time of arrival may still be marked fully refundable unless time of booking is within N days of time of arrival"

Note: These fields are case sensitive and should be set as displayed above, they should not be for example 'Full' or 'None'.

cancellation_deadline

string

Pay at Stay

To be eligible for 'Pay At Stay' merchandizing your Hotel Availability response should return "paid_at_checkout" : true for all LineItems:

            "line_items": [
              {
                "price": {
                  "requested_currency_price": {
                    "amount": 220,
                    "currency": "USD"
                  }
                },
                "type": "rate",
                "paid_at_checkout": true,
                },
              {
                "price": {
                  "requested_currency_price": {
                    "amount": 20,
                    "currency": "USD"
                  }
                },
                "type": "tax",
                "sub_type": "tax_city",
                "paid_at_checkout": true,
                }
            ]
          },