Despegar HotelAvailability API
The HotelAvailability API from Despegar — 1 operation(s) for hotelavailability.
OpenAPI Specification
openapi: 3.0.3
info:
title: Activities Availability HotelAvailability API
version: 1.0.0
description: 'API for activities: tickets, modalities, availability, prebook, payments, and booking. Authentication via API Key.'
servers:
- url: https://api-dev.despegar.com/v3/activities-api
description: Sandbox
- url: https://apis-uat.despegar.com/v3/activities-api
description: UAT
- url: https://api.despegar.com/v3/activities-api
description: Production
security:
- ApiKeyAuth: []
tags:
- name: HotelAvailability
paths:
/hotels-api/availability:
get:
summary: Search
description: Search for available hotels based on input criteria.
parameters:
- in: query
name: country_code
schema:
type: string
required: false
description: The country code of the traveler's point of sale, in ISO 3166-1 alpha-2 format. This should represent the country where the shopping transaction is taking place.
example: br
- in: query
name: checkin_date
schema:
type: string
format: date
required: true
description: Refers to the hotel check-in date and must be in the format YYYY-MM-DD.
example: '2026-11-14'
- in: query
name: checkout_date
schema:
type: string
format: date
required: true
description: Refers to the hotel check-out date and must be in the format YYYY-MM-DD.
example: '2026-11-16'
- in: query
name: currency
schema:
type: string
required: true
description: Refers to the currency, which must be filled with three alphabetical digits. (E.g. "USD", "ARS")
example: BRL
- in: query
name: hotels
schema:
type: string
required: true
description: List of hotel IDs, separated by commas (max. 100).
- in: query
name: distribution
schema:
type: string
required: true
description: 'Passenger distribution. Each room’s passengers should be written as number_of_adults-children_ages. Children-age goes up to 17 years old. Rooms should be separated by “!”. E.g.: Means room 1 with 2 adults and room 2 with 2 adults and a 10-year-old child.'
examples:
example1:
value: 2!2-10
example2:
value: 2!2-8-5
- in: query
name: language
schema:
type: string
enum:
- EN
- ES
- PT
description: Refers to the language, which must be filled with two alphabetical digits.
example: PT
- in: query
name: ttl
schema:
type: integer
description: Maximum time allowed for the connection. Minimum = 3000 ms, Maximum = 6200 ms.
- in: query
name: refundable_only
schema:
type: boolean
description: If set to ‘true’, only refundable hotel rates will be quoted.
responses:
'200':
description: Availability response
content:
application/json:
schema:
type: object
properties:
items:
type: array
items:
type: object
properties:
id:
type: string
description: hotel id
hotel_info:
type: object
description: This structure is of type dictionary and returns hotel information.
properties:
name:
type: string
description: hotel name
type:
type: string
stars:
type: integer
description: star rating
location:
type: object
description: an object that contains latitude and longitude values for the hotel location
properties:
latitude:
type: number
longitude:
type: number
roompacks:
type: array
items:
type: object
properties:
id:
type: string
meal_plan:
type: object
description: Meal plan corresponding to the roompack (e.g., room only, breakfast included, all-inclusive, etc.).
properties:
id:
type: string
rooms:
type: array
items:
type: object
properties:
name:
type: string
description: room name
reference:
type: integer
description: index of room elements contained in the roompack choice (first index == 1)
bed_options:
type: array
items:
type: string
description: ' list with all bedding options for the room'
room_type_id:
type: string
description: room id. These id should be used to map static content about the room
max_capacity:
type: integer
description: maximum pax capacity of the room
cancellation_policy:
type: object
description: This structure is of type list and can return one or several rules regarding cancellation policies of the roompack
properties:
status:
type: string
description: Represents the cancellation policy status at the moment the request is made
enum:
- non_refundable
- partially_refundable
- fully_refundable
hours_before_penalty:
type: integer
description: hours prior to check in which status applies in case of cancelling in those conditions
cancellation_policy_rules:
type: array
description: This structure is of type list and can return one or several rules regarding cancellation policies of the roompack. The penalty may be applied per night or as a percentage. Based on the information provided by the partner, the refund amount is determined. If no penalty is specified for that range, it is considered that no penalty applies.
items:
type: object
properties:
type:
type: string
description: rule type
penalty:
type: object
description: contains the percentage of the total amount of the reservation that should be considered as charge in case of cancelling in theses conditions
properties:
percentage:
type: number
night_count:
type: integer
anticipation:
type: object
description: timeframe where the rules apply. it is a dictionary with “from” and “to” values measured in hours to check in.
properties:
from:
type: integer
to:
type: integer
price_detail:
type: object
properties:
currency:
type: string
description: currency in which values will be expressed
total:
type: number
description: total value of the roompack (subtotal + taxes). It does not include charges to be paid at destination
taxes:
type: number
description: taxes corresponding to the roompack price
taxes_detail:
type: array
items:
type: object
properties:
code:
type: string
amount:
type: number
description: list with code and amount pairs
charge_at_destination:
type: number
charge_at_destination_detail:
type: array
items:
type: object
properties:
code:
type: string
description: 'This field can have different possible values, which are:'
enum:
- 'TT: Turism fee'
- 'TA: Additional fee'
- 'RF: Resort fee'
- 'TM: Bellboy fee'
- 'EF: Environmental fee'
- 'DO: Damage deposit (refundable)'
- 'TL: Cleaning fee'
- 'DS: Security deposit'
- 'ISS: Tax over service'
- 'TS: Service charge'
- 'TE: Energy fee'
- 'CT: City Tax'
- 'SH: Hotel insurance'
amount:
type: string
agency_commission:
type: object
description: Applicable only to commissionable models.
properties:
amount:
type: number
percentage:
type: number
binding_public_rate_enabled:
type: boolean
description: if set to true, “amount” value is the mínimum price that the partner should sell the item
binding_public_rate_value:
type: number
promo:
type: object
properties:
type:
type: string
saving:
type: object
description: Details of the promotional savings associated with the product.
properties:
type:
type: string
percentage:
type: number
tags:
type: array
description: Used to identify products associated with a promotion.
example:
items:
- id: 259462
hotel_info:
name: Bogotá Plaza Hotel
stars: 5
roompacks:
- id: '35809'
meal_plan:
id: BRB
rooms:
- name: Standard Room
max_capacity: 3
bed_options:
- id: '1'
description: 1 King Bed
cancellation_policy:
status: fully_refundable
price_detail:
currency: USD
total: 300
taxes: 50
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
code:
type: string
message:
type: string
'401':
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
code:
type: string
message:
type: string
'403':
description: Forbidden
content:
application/json:
schema:
type: object
properties:
code:
type: string
message:
type: string
'404':
description: Not Found
content:
application/json:
schema:
type: object
properties:
code:
type: string
message:
type: string
'429':
description: Too Many Requests
content:
application/json:
schema:
type: object
properties:
code:
type: string
message:
type: string
'500':
description: Internal Server Error
content:
application/json:
schema:
type: object
properties:
code:
type: string
message:
type: string
tags:
- HotelAvailability
operationId: searchAvailability
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-apikey
BearerAuth:
type: http
scheme: bearer
x-readme: {}