Retrieve Hotelpage actualizes bookable rates and book_hash values for a single chosen hotel, and Prebook revalidates availability and price for the selected rate (with an optional price_increase_percent bound) before booking.
openapi: 3.0.1
info:
title: RateHawk / ETG API (WorldOta APIv3)
description: >-
B2B hotel and travel booking API operated by Emerging Travel Group (ETG)
and exposed to partners as the RateHawk API. The Partner API (pAPI) v3
covers hotel search (SERP by region, hotels, and geo), hotelpage rate
actualization, prebook, the asynchronous order booking flow (form, finish,
finish status), order information, cancellation, and static hotel content.
All endpoints are HTTP POST that accept and return JSON and authenticate
with HTTP Basic using a key id (username) and key (password).
termsOfService: https://www.ratehawk.com/
contact:
name: ETG API Support
url: https://docs.emergingtravel.com/
version: '3.0'
servers:
- url: https://api.worldota.net/api/b2b/v3
description: Production
- url: https://api-sandbox.worldota.net/api/b2b/v3
description: Sandbox / test
security:
- basicAuth: []
tags:
- name: Hotel Search
- name: Prebook
- name: Booking
- name: Orders
- name: Hotel Content
- name: Cancellation
paths:
/overview/:
get:
operationId: getOverview
tags:
- Orders
summary: Endpoints overview
description: >-
Returns the list of all endpoints available for your contract and
their settings.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/BaseResponse'
/search/serp/region/:
post:
operationId: searchRegion
tags:
- Hotel Search
summary: Search Engine Results Page by region
description: >-
Preliminary search (SERP) for hotels with available accommodation
within a region that matches the given search conditions.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RegionSearchRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SearchResponse'
/search/serp/hotels/:
post:
operationId: searchHotels
tags:
- Hotel Search
summary: Search Engine Results Page by hotel IDs
description: >-
Preliminary search (SERP) for a specific set of hotels by their
identifiers matching the given search conditions.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/HotelsSearchRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SearchResponse'
/search/serp/geo/:
post:
operationId: searchGeo
tags:
- Hotel Search
summary: Search Engine Results Page by geo coordinates
description: >-
Preliminary search (SERP) for hotels within a radius of the given
latitude and longitude.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/GeoSearchRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SearchResponse'
/search/hp/:
post:
operationId: searchHotelPage
tags:
- Hotel Search
summary: Retrieve hotelpage
description: >-
Hotel rates actualization for a single hotel. Should be requested only
after the user has chosen the hotel; returns the up-to-date set of
bookable rates with their book_hash values.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/HotelPageRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SearchResponse'
/hotel/prebook/:
post:
operationId: hotelPrebook
tags:
- Prebook
summary: Prebook rate from hotelpage step
description: >-
Updates the availability and price of the requested rate and attempts
to find a comparable or similar rate if the original is unavailable.
Use price_increase_percent to bound how much higher the new price may
be than the original.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PrebookRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/BaseResponse'
/hotel/order/booking/form/:
post:
operationId: orderBookingForm
tags:
- Booking
summary: Create booking process (order booking form)
description: >-
Creates a new reservation process from a prebooked rate's book_hash.
The process of reserving a rate includes several stages depending on
whether 3-D Secure and/or fraud checks are required.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/OrderBookingFormRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/BaseResponse'
/hotel/order/booking/finish/:
post:
operationId: orderBookingFinish
tags:
- Booking
summary: Order booking finish
description: >-
Completes the reservation. The reservation is carried out
asynchronously: the partner launches the process via this call and
then repeatedly polls Order Booking Finish Status.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/OrderBookingFinishRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/BaseResponse'
/hotel/order/booking/finish/status/:
post:
operationId: orderBookingFinishStatus
tags:
- Booking
summary: Order booking finish status
description: >-
Status check for the asynchronous order completion process. Poll this
endpoint until processing changes to ok or a final failure status.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/OrderBookingFinishStatusRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/BaseResponse'
/hotel/order/info/:
post:
operationId: orderInfo
tags:
- Orders
summary: Order information
description: >-
Retrieves a created order's information by the partner's booking
identifier. Relevant only for reservations that were successfully
created.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/OrderInfoRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/BaseResponse'
/hotel/order/cancel/:
post:
operationId: orderCancel
tags:
- Cancellation
summary: Order cancellation
description: >-
Cancels a booking by the partner's booking identifier. Relevant for
reservations with completed / rejected status; allows cancellation of
non-refundable bookings with applicable charges.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/OrderCancelRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/BaseResponse'
/hotel/info/:
post:
operationId: hotelInfo
tags:
- Hotel Content
summary: Hotel data search (static content)
description: >-
Static hotel content lookup by hotel identifier, including address,
amenities, descriptions, images, metapolicy, room groups, and star
rating. Used to fill gaps not present in the hotel data dump.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/HotelInfoRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/HotelInfoResponse'
/hotel/info/dump/:
post:
operationId: hotelInfoDump
tags:
- Hotel Content
summary: Hotel data dump
description: >-
Returns a URL to the archive of all available ETG hotels' static data
for one language. The dump is regenerated daily.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/HotelInfoDumpRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/BaseResponse'
components:
securitySchemes:
basicAuth:
type: http
scheme: basic
description: >-
HTTP Basic authentication. The username is the API key id and the
password is the API key (uuid). Both are issued per contract for the
test (sandbox) and production environments.
schemas:
GuestsGroup:
type: object
required:
- adults
properties:
adults:
type: integer
children:
type: array
items:
type: integer
BaseSearchRequest:
type: object
required:
- checkin
- checkout
- guests
properties:
checkin:
type: string
format: date
checkout:
type: string
format: date
currency:
type: string
residency:
type: string
language:
type: string
timeout:
type: integer
guests:
type: array
items:
$ref: '#/components/schemas/GuestsGroup'
RegionSearchRequest:
allOf:
- $ref: '#/components/schemas/BaseSearchRequest'
- type: object
required:
- region_id
properties:
region_id:
type: integer
HotelsSearchRequest:
allOf:
- $ref: '#/components/schemas/BaseSearchRequest'
- type: object
required:
- ids
properties:
ids:
type: array
items:
type: string
GeoSearchRequest:
allOf:
- $ref: '#/components/schemas/BaseSearchRequest'
- type: object
required:
- latitude
- longitude
- radius
properties:
latitude:
type: number
format: float
longitude:
type: number
format: float
radius:
type: integer
HotelPageRequest:
allOf:
- $ref: '#/components/schemas/BaseSearchRequest'
- type: object
required:
- id
properties:
id:
type: string
description: Hotel identifier.
PrebookRequest:
type: object
required:
- hash
properties:
hash:
type: string
description: book_hash of the rate selected on the hotelpage step.
price_increase_percent:
type: integer
description: >-
Maximum percent the actualized price may exceed the original price.
OrderBookingFormRequest:
type: object
required:
- partner_order_id
- book_hash
properties:
partner_order_id:
type: string
description: Unique partner booking identifier.
book_hash:
type: string
language:
type: string
user_ip:
type: string
OrderBookingFinishRequest:
type: object
required:
- partner_order_id
- user
- rooms
- payment_type
properties:
partner_order_id:
type: string
language:
type: string
user:
type: object
properties:
email:
type: string
phone:
type: string
comment:
type: string
rooms:
type: array
items:
type: object
properties:
guests:
type: array
items:
type: object
properties:
first_name:
type: string
last_name:
type: string
payment_type:
type: object
properties:
type:
type: string
amount:
type: string
currency_code:
type: string
OrderBookingFinishStatusRequest:
type: object
required:
- partner_order_id
properties:
partner_order_id:
type: string
OrderInfoRequest:
type: object
properties:
ordering:
type: object
pagination:
type: object
search:
type: object
properties:
partner_order_ids:
type: array
items:
type: string
OrderCancelRequest:
type: object
required:
- partner_order_id
properties:
partner_order_id:
type: string
minLength: 1
maxLength: 256
description: Unique partner booking identifier.
HotelInfoRequest:
type: object
required:
- id
- language
properties:
id:
type: string
language:
type: string
HotelInfoDumpRequest:
type: object
required:
- language
properties:
language:
type: string
inventory:
type: string
Region:
type: object
properties:
id:
type: integer
name:
type: string
country_code:
type: string
iata:
type: string
type:
type: string
HotelInfoData:
type: object
properties:
id:
type: string
name:
type: string
address:
type: string
latitude:
type: number
longitude:
type: number
star_rating:
type: integer
kind:
type: string
images:
type: array
items:
type: string
region:
$ref: '#/components/schemas/Region'
is_closed:
type: boolean
HotelInfoResponse:
type: object
properties:
status:
type: string
error:
type: string
nullable: true
data:
$ref: '#/components/schemas/HotelInfoData'
SearchResponse:
type: object
properties:
status:
type: string
error:
type: string
nullable: true
data:
type: object
properties:
hotels:
type: array
items:
type: object
properties:
id:
type: string
rates:
type: array
items:
type: object
total_hotels:
type: integer
BaseResponse:
type: object
properties:
status:
type: string
description: ok or error.
error:
type: string
nullable: true
debug:
type: object
nullable: true
data:
type: object
nullable: true