Ground transportation availability and booking by IATA code, GPS coordinates, or Hotelbeds custom codes, covering airport, hotel, and point-to-point transfers, plus transfer content such as routes and vehicle types.
openapi: 3.0.1
info:
title: Hotelbeds APItude API
description: >-
Specification of the Hotelbeds (HBX Group) APItude API suite. Covers the Hotel
Booking API (availability, checkrates, bookings), the Hotel Content API (static
hotel and destination data), the Activities API, the Transfers API, and the
Hotel Cache API. All requests authenticate with an Api-key header plus an
X-Signature header, a SHA256 hash (in hex) of the API key, shared secret, and
the current Unix timestamp in seconds.
termsOfService: https://www.hotelbeds.com/terms-conditions/
contact:
name: Hotelbeds Developer Support
url: https://developer.hotelbeds.com/support/
version: '1.0'
servers:
- url: https://api.hotelbeds.com
description: Production environment
- url: https://api.test.hotelbeds.com
description: Test / evaluation environment
security:
- ApiKeyAuth: []
SignatureAuth: []
paths:
/hotel-api/1.0/status:
get:
operationId: getStatus
tags:
- Booking
summary: API status check
description: Returns the operational status of the Hotel Booking API.
responses:
'200':
description: API is operational.
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
/hotel-api/1.0/hotels:
post:
operationId: getAvailability
tags:
- Booking
summary: Hotel availability search
description: >-
Requests room availability and rates for a stay, filtered by destination,
hotel codes, geolocation, dates, and occupancies.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AvailabilityRequest'
responses:
'200':
description: Availability results.
content:
application/json:
schema:
$ref: '#/components/schemas/AvailabilityResponse'
/hotel-api/1.0/checkrates:
post:
operationId: checkRates
tags:
- Booking
summary: Check rates
description: >-
Re-validates the price and availability of one or more rates returned by
an availability search before confirming a booking.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CheckRateRequest'
responses:
'200':
description: Confirmed rate details.
content:
application/json:
schema:
$ref: '#/components/schemas/AvailabilityResponse'
/hotel-api/1.0/bookings:
get:
operationId: listBookings
tags:
- Booking
summary: List bookings
description: Retrieves a list of bookings filtered by client reference or dates.
parameters:
- name: start
in: query
schema:
type: integer
- name: end
in: query
schema:
type: integer
responses:
'200':
description: A list of bookings.
content:
application/json:
schema:
$ref: '#/components/schemas/Booking'
post:
operationId: confirmBooking
tags:
- Booking
summary: Confirm a booking
description: Confirms a booking for a rate key validated through checkrates.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BookingRequest'
responses:
'200':
description: The confirmed booking.
content:
application/json:
schema:
$ref: '#/components/schemas/Booking'
/hotel-api/1.0/bookings/{bookingId}:
get:
operationId: getBookingDetail
tags:
- Booking
summary: Booking detail
description: Retrieves the full detail of a single booking by reference.
parameters:
- name: bookingId
in: path
required: true
schema:
type: string
responses:
'200':
description: The requested booking.
content:
application/json:
schema:
$ref: '#/components/schemas/Booking'
delete:
operationId: cancelBooking
tags:
- Booking
summary: Cancel a booking
description: >-
Cancels a booking, or simulates the cancellation when cancellationFlag is
SIMULATION.
parameters:
- name: bookingId
in: path
required: true
schema:
type: string
- name: cancellationFlag
in: query
schema:
type: string
enum:
- CANCELLATION
- SIMULATION
responses:
'200':
description: The cancelled booking.
content:
application/json:
schema:
$ref: '#/components/schemas/Booking'
/hotel-content-api/1.0/hotels:
get:
operationId: getHotelContent
tags:
- Content
summary: Hotel content
description: Returns static content for hotels - descriptions, addresses, images, and facilities.
parameters:
- name: fields
in: query
schema:
type: string
- name: language
in: query
schema:
type: string
- name: from
in: query
schema:
type: integer
- name: to
in: query
schema:
type: integer
responses:
'200':
description: Hotel content results.
content:
application/json:
schema:
$ref: '#/components/schemas/HotelContentResponse'
/hotel-content-api/1.0/locations/countries:
get:
operationId: getCountries
tags:
- Content
summary: Countries
description: Returns the list of countries available in the content database.
parameters:
- name: fields
in: query
schema:
type: string
- name: language
in: query
schema:
type: string
responses:
'200':
description: Country list.
content:
application/json:
schema:
$ref: '#/components/schemas/HotelContentResponse'
/hotel-content-api/1.0/locations/destinations:
get:
operationId: getDestinations
tags:
- Content
summary: Destinations
description: Returns the list of destinations available in the content database.
parameters:
- name: fields
in: query
schema:
type: string
- name: language
in: query
schema:
type: string
responses:
'200':
description: Destination list.
content:
application/json:
schema:
$ref: '#/components/schemas/HotelContentResponse'
/activity-api/3.0/activities/availability:
post:
operationId: getActivityAvailability
tags:
- Activities
summary: Activities availability search
description: Returns real-time availability and pricing for tours and activities.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AvailabilityRequest'
responses:
'200':
description: Activity availability results.
content:
application/json:
schema:
$ref: '#/components/schemas/AvailabilityResponse'
/transfer-api/1.0/availability/{language}/from/{fromType}/{fromCode}/to/{toType}/{toCode}:
get:
operationId: getTransferAvailability
tags:
- Transfers
summary: Transfer availability search
description: >-
Returns available transfers between an origin and destination identified
by IATA code, GPS coordinates, or Hotelbeds custom codes.
parameters:
- name: language
in: path
required: true
schema:
type: string
- name: fromType
in: path
required: true
schema:
type: string
- name: fromCode
in: path
required: true
schema:
type: string
- name: toType
in: path
required: true
schema:
type: string
- name: toCode
in: path
required: true
schema:
type: string
responses:
'200':
description: Transfer availability results.
content:
application/json:
schema:
$ref: '#/components/schemas/AvailabilityResponse'
/hotel-cache-api/1.0/availabilities:
get:
operationId: getCacheFiles
tags:
- Cache
summary: Cache availability files
description: >-
Returns the hourly cache snapshot of all prices and availability as a CSV
file compressed in .zip.
responses:
'200':
description: A zipped CSV cache file.
content:
application/zip:
schema:
type: string
format: binary
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: Api-key
description: Your APItude API key, issued per API suite (Hotel, Activities, Transfers).
SignatureAuth:
type: apiKey
in: header
name: X-Signature
description: >-
SHA256 hash, in hexadecimal, of the concatenation of the API key, the
shared secret, and the current Unix timestamp in seconds.
schemas:
Status:
type: object
properties:
status:
type: string
example: OK
AvailabilityRequest:
type: object
properties:
stay:
type: object
properties:
checkIn:
type: string
format: date
checkOut:
type: string
format: date
occupancies:
type: array
items:
type: object
properties:
rooms:
type: integer
adults:
type: integer
children:
type: integer
destination:
type: object
properties:
code:
type: string
AvailabilityResponse:
type: object
properties:
auditData:
type: object
hotels:
type: object
properties:
total:
type: integer
hotels:
type: array
items:
$ref: '#/components/schemas/Hotel'
Hotel:
type: object
properties:
code:
type: integer
name:
type: string
categoryName:
type: string
destinationName:
type: string
minRate:
type: string
currency:
type: string
CheckRateRequest:
type: object
properties:
rooms:
type: array
items:
type: object
properties:
rateKey:
type: string
BookingRequest:
type: object
properties:
holder:
type: object
properties:
name:
type: string
surname:
type: string
rooms:
type: array
items:
type: object
properties:
rateKey:
type: string
paxes:
type: array
items:
type: object
clientReference:
type: string
Booking:
type: object
properties:
reference:
type: string
clientReference:
type: string
status:
type: string
totalNet:
type: string
currency:
type: string
HotelContentResponse:
type: object
properties:
from:
type: integer
to:
type: integer
total:
type: integer
hotels:
type: array
items:
$ref: '#/components/schemas/Hotel'