Hotel Search

Note:
Few attributes in below sample response are supplier specific, hence there can be possibility these attributes will not appear in the response. We recommend you to parse these fields as mentioned in the sample responses.

Hotel Search By City (API service end point)

/api/v1/hotel/search

This service is used to search for available hotels for a booking in a specific city for a date range.
It will return room-wise the cheapest rate
If you search for 2 rooms (1^st room - 1 Adult and 2^nd room - 2 Adults) then you will receive the cheapest room detail for each room you search and you can identify room options based on roomIndex value.
If roomIndex is 1 then it belongs to the 1^st room and If roomIndex is 2 then it belongs to the 2^nd room.

Important Notes

Currently, we support max. 2 children per room.
Child age(s) are compulsory when a search request includes a child.
Guest Nationality is mandatory. Hotel prices might vary for the same Search Request with different Guest Nationality.

Hotel Search By City (Request)

Tags	Attribute	Description
meta	meta (Object)
HotelSearchCriteria	(JsonObject)	Hotel Search Criteria details will come under this attribute
	country* (String)	Search Country Name
	city* (String)	Search City Name
	checkIn* (Date)	Check-in date
	checkOut* (Date)	Check-out date
	travelerNationality* (String)	Traveller nationality - EG: INDIA,IN
	travelerCountryOfResidence* (String)	Traveller country of residence - EG: INDIA,IN
	culture* (String)	culture

rooms	rooms* (JsonArray)
room	(JsonObject)*	Room search criteria will come under this attribute
	roomIndex* (String)	room Index is unique key for each room. This index should be used for entire search to book flow.
	adult* (Integer)	Adult count
	child* (Integer)	child Count
	childAge* (String)	must mention the child ages array if children are available

filters	(JsonObject)	Hotel Filters
filter	minStarRating* (Integer)	Minimum star rating
	availableHotelsOnly* (Boolean)	If available on request
	payAtHotelRates* (Boolean)	If pay at hotel available

taxDetails	(JsonObject)	Include Tax information.In general Tax detail are not mandatory. However If 'Yatra' API is mapped to an API client then they have to send TaxDetails in Search Request.
taxDetail	taxName (String)	Tax Name
	regNo (String)	Tax registration number
	companyName (String)	Company name
	emailId (String)	Company emailId
	phoneNo (String)	Company phone number
	address (String)	Company address

Hotel Search By City (Request)
{
"meta": {
    "additionalProperties": [
      {
        "key": "timeStamp",
        "value": "YYYY-MM-DD HH:MM:SST",
        "description": "description"
      }
    ]
  },
  "country": "India",
  "city": "Mumbai",
  "checkIn": "YYYY-MM-DD",
  "checkOut": "YYYY-MM-DD",
  "rooms": [
    {
      "roomIndex": 1,
      "adult": 1,
      "child": 2,
      "childAge": [
        5,
        4
      ]
    }
  ],
  "travelerNationality": "INDIA,IN",
  "travelerCountryOfResidence": "INDIA,IN",
  "culture": "en",
  "filters": {
    "minStarRating": 2,
    "availableHotelsOnly": true,
    "payAtHotelRates": false
  },
  "taxDetails": {
    "taxName": "GST",
    "regNo": "08AADCB2923M1ZL",
    "companyName": "BAJAJ AUTO LIMITED",
    "emailId": "balairline@bajajauto.co.in",
    "phoneNo": "9928000021",
    "address": "A-47 VRINDAVAN VIHAR KINGS ROAD Jaipur AJMER ROAD Rajasthan 302019"
  }
}

Hotel Search By ID (API service end point)

/api/v1/hotel/search-by-id

This service is used to do hotel search by ID for a date range.
Difference between hotel search by city and hotel search by ID are as below :

No.	Hotel Search By City	Hotel Search By ID
01	Search is done for a group of hotels located in the requested city	Search is done for a particular hotel
02	Ideal for city wide hotel search	Ideal when searching hotel name using the autocomplete API which provides the required hotelIDs. (Note: The autocomplete API is under planning).

Apart from the differences, rest of the things are common between the two.

Important Notes

The hotel search by ID is a part of hotel search by name using autocomplete API & it's under planning.
Currently, the hotel search by ID will work only with GIATA hotelId. So the hotelId needs to be a valid integer value.
Once the autocomplete API feature is released, then it will be using uniquely generated hotelId.
Currently, we have limited suppliers which support the hotel search by ID [HotelBeds, DOTW].
Currently, we support maximum 1 hotelId in the hotelIdList.
As part of the future scope, the hotelIdList is capable of removing duplicates and then searching.
The result count for the hotel search by ID will be same as the number of hotelId passed in the hotelIdList only during a valid search scenario.
NOTE: Apart from "country" and "city" tags rest all the request parameters are same as hotel search by city.

Hotel Search By ID (Request)

Tags	Attribute	Description
hotelIdList	hotelIdList* (JsonArray)	The hotelIdList Eg: ["103015"] Currently supported only 1 ID per search for limited suppliers.

Hotel Search By ID (Request)
{
    "hotelIdList": ["103015"],
    "checkIn": "2023-12-24",
    "checkOut": "2023-12-26",
    "rooms": [
        {
            "adult": 1,
            "child":  0,
            "roomIndex": 1,
            "childAge": []
        }
    ],
    "travelerCountryOfResidence": "INDIA,IN",
    "travelerNationality": "INDIA,IN",
    "culture": "en",
    "additionalProperties": [],
    "filters": {
        "currency": "INR",
        "minStarRating": 0,
        "availableHotelsOnly": true,
        "payAtHotelRates": false
    },
    "taxDetails": {
        "taxName": "GST",
        "regNo": "08AADCB2923M1ZL",
        "companyName": "BAJAJ AUTO LIMITED",
        "emailId": "balairline@bajajauto.co.in",
        "phoneNo": "9928000021",
        "address": "A-47 VRINDAVAN VIHAR KINGS ROAD Jaipur AJMER ROAD Rajasthan 302019"
    }
}

Hotel Search Response

Tags	Attribute	Description
meta	meta (Object)
	success (String)	Response status will be return Ex: "true"
	statusCode (Boolean)	Response statusCode will be return Ex: "1"
	statusMessage (String)	Response statusMessage will be return Ex: "SUCCESS"
	actionType (String)	This attribute will indicate that client request type such as Hotel search , Prov book and Book etc... . This is for information purpose.
	conversationId (String)	conversationId a unique identifier of current conversation .
commonData	(JsonObject)
commonData	searchKey* (String)	This attribute contains a unique search key.
commonData	productCode* (String)	Product code for hotels - H
commonData	culture* (String)	en
data	hotels(JsonArray)	This encloses hotel information.
data	hotelKey* (String)	Unique Key for each Hotel. This should be used foe search to booking flow.
propertyInfo	(JsonObject)	This encloses property information
propertyInfo	hotelName (String)	Hotel Name
propertyInfo	propertyType (String)	Property Type Eg: (Hotel/Apartment)
propertyInfo	address (String)	Hotel address
propertyInfo	location (String)	Hotel location details Eg: Andheri East
propertyInfo	longitude (String)	55.291822
propertyInfo	latitude (String)	25.250688
propertyInfo	phoneNumber (String)	Hotel phone number
propertyInfo	userRating (String)	hotel user rating
propertyInfo	starRating (String)	hotel star rating
propertyInfo	imageUrl (String)	hotel image URL link
facilities	(JsonArray)	This encloses hotel facility information
facility	(JsonObject)
facility	type (String)	Facility type Eg: services
facility	name (String)	Facility name
facility	description (String)	Facility description Not released yet

rooms	(JsonArray) *	This encloses room information
room	(JsonObject)
room	roomKey* (String)	This attribute contains the room's unique id. Room Key is unique key for each room. This Key should be used for entire search to book flow
room	roomIndex* (String)	represents the room number , Room Index is unique key for each room. This index should be used for entire search to book flow.
room	roomId* (String)	This attribute contains the room id. 38_1
room	roomTypeName * (String)	Room type Eg: Deluxe Room
room	roomTypeDesc * (String)	Room type description
room	bedType (String)	bed type provided in the room Eg: Double
room	roomView (String)	room view description Eg: mountain view
room	maxOccupancy (Integer)	Max occupancy of a room.
room	sizeMeasurement (String)	size of the room.
room	rateNotes (String)	Eg: please Note That Three Bedroom Residence is Located In The Residence Building (This information is very important)

passengerData	(JsonObject)
passengerData	isEmailId (Boolean)	If the value of the attribute is true then send email id details in the booking request
passengerData	isPAN (Boolean)	If the value of the attribute is true then send pan details in the booking request.
passengerData	isPassport (Boolean)	If the value of the attribute is true then send passport details in the booking request.
passengerData	isPhoneNo (Boolean)	If the value of the attribute is true then send phone number details in the booking request.

roomImages	(JsonObject)
images	(JsonArray)
image	(JsonObject)
image	order (Integer)	Image order number
image	type (String)	Image type
image	description (String)	Image description
image	path (String)	image file URL.

ratePlan	(JsonObject) *
ratePlan	availableStatus * (String)	availability status of the room
ratePlan	cancelPolicyIndicator (String)	The cancel policy indicators Eg: refundable
ratePlan	code * (String)	This attribute contains the room contract details
ratePlan	isPackage (String)	Shows if the room rate is a package.
ratePlan	rateType (String)	Contains rate type Eg: Retail/Corporate
ratePlan	gstAssured (Boolean)	This indicated that available room hotel is GST assured and you can make request for GST invoices
ratePlan	lastCancellationDate (Date)	Indicates last cancellation date
ratePlan	fixedCombo (Boolean)	Shows room selection is combined or flexible.

roomRate	(JsonObject)
roomRate	currency* (String)	Contains selling currency room price
roomRate	netAmount* (Double)	Selling price of a room.
supplierAdditionalFareInfo	(JsonObject)	Not released yet
supplierAdditionalFareInfo	currency (String)	Not released yet
supplierAdditionalFareInfo	discount (Double)	Not released yet
supplierAdditionalFareInfo	publishedFare (Double)	Not released yet
supplierAdditionalFareInfo	commissionEarned (Double)	Not released yet
supplierAdditionalFareInfo	offeredFare (Double)	Not released yet
supplierAdditionalFareInfo	tdsOnCommission (Double)	Not released yet
supplierAdditionalFareInfo	serviceFee (Double)	Not released yet

customerAdditionalFareInfo	(JsonObject)	Not released yet
customerAdditionalFareInfo	transactionFeeEarned (Double)	Not released yet
customerAdditionalFareInfo	tdsOnCommission (Double)	Not released yet
customerAdditionalFareInfo	commissionEarned (Double)	Not released yet
customerAdditionalFareInfo	markupEarned (Double)	Not released yet
customerAdditionalFareInfo	discount (Double)	Not released yet
customerAdditionalFareInfo	vat (Double)	Not released yet
customerAdditionalFareInfo	cgst (Double)	Not released yet
customerAdditionalFareInfo	sgst (Double)	Not released yet
customerAdditionalFareInfo	igst (Double)	Not released yet

taxes	(JsonArray)
tax	(JsonObject)
tax	name (String)	Tax name
tax	amount (Double)	Tax amount
tax	included (Boolean)	Shows if the tax is included in the room rate or not.

rates	(JsonArray) *
rate	(JsonObject)
rate	name * (String)	Name of the rate Eg: daily rates
rate	amount * (String)	Rate amount
rate	from * (Date)	Start date of room rate.
rate	to * (Date)	End date of room rate.
rate	rateIndex * (String)	Rate number

offers	(JsonArray)
offer	(JsonObject)
offer	code (String)	Offer Code
offer	name (String)	Offer name
offer	from (Date)	Start date from that date offer will apply
offer	to (Date)	End date where the offer will expire
offer	amount (Double)	Offer amount
offer	included (Boolean)	indicate that the offer is applied or not

supplements	(JsonArray)
supplement	(JsonObject)
supplement	supplementKey (String)	ABFJKHEJHBMNSDFH
supplement	type (String)	Supplement Type
supplement	name (String)	Supplement name
supplement	from (Date)	Start date from that date supplement will apply
supplement	to (Date)	End date that the supplement will expire
supplement	amount (Double)	supplement charges
supplement	included (Boolean)	indicate that the supplement is applied or not to given room
supplement	currency (String)	supplement charges currency

financialInfo	(JsonObject)
financialInfo	tmc (String)	This tag contains supplier owner name. tmc - Travel Management Company. Eg: VE
financialInfo	supplier (String)	Name of the supplier
payment	(JsonObject)
payment	paymentTypes (String)	Payment types Eg: CARD,CR
payment	paymentNetwork (String)	Payment Network Codes Not released yet

hotel search response
{
  "meta": {
    "success": true,
    "statusCode": "",
    "statusMessage": "",
    "additionalProperties": [
      {
        "key": "timeStamp",
        "value": "YYYY-MM-DD HH:MM:SST",
        "description": "description"
      },
      {
        "key": "serverKey",
        "value": "Server01",
        "description": "description"
      }
    ],
    "actionType": "Hotel search",
    "conversationId": "fe22cb8d-67e9-4c29-92af-e44dffdcb9a9"
  },
  "warnings": [
    {
      "code": "validation_required",
      "documentationUrl": "api-doc/docs/troubleshoot/api-error-codes/index.html",
      "message": "Check In Time' can't be blank",
      "value": "Check In Time might be changed"
    }
  ],
  "errors": [
    {
      "code": "validation_required",
      "documentationUrl": "api-doc/docs/troubleshoot/api-error-codes/index.html",
      "message": "Field 'City' can't be blank",
      "value": "Field 'City' can't be blank",
      "source": {
        "field": "City",
        "pointer": "/HotelSearchCriteria/city"
      },
      "title": "Required field",
      "type": "validation_error"
    }
  ],
  "commonData": {
    "searchKey": "260d6c37-ab74-4331-9fdc-a9d42a5b55a6",
    "culture": "en"
  },
  "data": [
    {
      "hotelKey": "fb0920a8-70b8-433a-a8e2-a8e32efeae5640htr00000000",
      "propertyInfo": {
        "hotelName": "citymaxHotelBurDubai",
        "propertyType": "hotel",
        "address": "dubaiDubai116121UnitedArabEmirates",
        "location": "miraRoadEast",
        "latitude": "25.250688",
        "imageUrl": "url",
        "longitude": "55.291822",
        "starRating": "3.0",
        "userRating": "4.0",
        "phoneNumber": "44078000",
        "facilities": [
          {
            "type": "services",
            "name": "shower",
            "description": "shower"
          }
        ]
      },
      "rooms": [
        {
          "roomKey": "fb0920a8-70b8-433a-a8e2-a8e32efeae5640htr00000001rcmb00000000",
          "roomIndex": "1",
          "roomId": "38_1",
          "roomTypeName": "standard",
          "roomTypeDesc": "standard",
          "bedType": "double",
          "roomView": "mountainView",
          "maxOccupancy": 2,
          "sizeMeasurement": "275Sqm",
          "passengerMandetoryData": {
            "isEmailId": true,
            "isPAN": true,
            "isPassport": true,
            "isPhoneNo": true
          },
          "roomImages": {
            "image": [
              {
                "order": 1,
                "type": "Room",
                "description": "Room",
                "path": "http://photos.hotelbeds.com/giata/42/428622/428622a_hb_ro_137.jpg"
              },
              {
                "order": 2,
                "type": "Room",
                "description": "Room",
                "path": "http://photos.hotelbeds.com/giata/42/428622/428622a_hb_ro_138.jpg"
              }
            ]
          },
          "ratePlan": {
            "availableStatus": "available",
            "cancelPolicyIndicator": "refundable",
            "code": "76-1360717",
            "isPackage": false,
            "rateType": "retail",
            "gstAssured": false,
            "lastCancellationDate": "YYYY-MM-DD",
            "fixedCombo": false,
            "meal": "roomOnly",
            "supplierCode": "1",
            "inclusions": [
              "Free Wifi",
              "Free pool"
            ],
            "additionalProperties": [
              {
                "key": "key1",
                "value": "value1",
                "description": "description"
              },
              {
                "key": "key1",
                "value": "value1",
                "description": "description"
              }
            ]
          },
          "roomRate": {
            "supplierAdditionalFareInfo": {
              "currency": "AED",
              "discount": 0,
              "publishedFare": 5184,
              "commissionEarned": 74.36,
              "offeredFare": 5109.64,
              "tdsOnCommission": 3.72,
              "serviceFee": 0,
              "additionalProperties": [
                {
                  "key": "key1",
                  "value": "value1",
                  "description": "description"
                },
                {
                  "key": "key1",
                  "value": "value1",
                  "description": "description"
                }
              ]
            },
            "customerAdditionalFareInfo": {
              "transactionFeeEarned": 5184,
              "tdsOnCommission": 3.72,
              "commissionEarned": 74.36,
              "markupEarned": 20,
              "discount": 0,
              "vat": 0,
              "cgst": 0,
              "sgst": 0,
              "igst": 0,
              "additionalProperties": [
                {
                  "key": "key1",
                  "value": "value1",
                  "description": "description"
                },
                {
                  "key": "key1",
                  "value": "value1",
                  "description": "description"
                }
              ]
            },
            "taxes": [
              {
                "name": "VAT on NT & TF",
                "amount": 54.45,
                "included": true
              }
            ],
            "rates": [
              {
                "name": "daily rates",
                "amount": 1889.635,
                "from": "YYYY-MM-DD",
                "rateIndex": "1",
                "to": "YYYY-MM-DD"
              }
            ],
            "currency": "INR",
            "netAmount": 1889.635,
            "additionalProperties": [
              {
                "key": "key1",
                "value": "value1",
                "description": "description"
              },
              {
                "key": "key1",
                "value": "value1",
                "description": "description"
              }
            ]
          },
          "offers": [
            {
              "code": "9002",
              "name": "earlyBookingDiscount",
              "from": "YYYY-MM-DD",
              "to": "YYYY-MM-DD",
              "amount": 19.86,
              "included": true,
              "additionalProperties": [
                {
                  "key": "key1",
                  "value": "value1",
                  "description": "description"
                },
                {
                  "key": "key1",
                  "value": "value1",
                  "description": "description"
                }
              ]
            }
          ],
          "supplements": [
            {
              "supplementKey": "ABFJKHEJHBMNSDFH",
              "type": "mandatory",
              "name": "testSupplement-1",
              "from": "YYYY-MM-DD",
              "to": "YYYY-MM-DD",
              "amount": 10,
              "included": true,
              "currency": "usd",
              "additionalProperties": [
                {
                  "key": "key1",
                  "value": "value1",
                  "description": "description"
                },
                {
                  "key": "key1",
                  "value": "value1",
                  "description": "description"
                }
              ]
            },
            {
              "supplementKey": "ABFJKHEJHBMNSDFV",
              "type": "optional",
              "name": "testSupplement-1",
              "from": "YYYY-MM-DD",
              "to": "YYYY-MM-DD",
              "amount": 10,
              "included": false,
              "currency": "usd",
              "additionalProperties": [
                {
                  "key": "key1",
                  "value": "value1",
                  "description": "description"
                },
                {
                  "key": "key1",
                  "value": "value1",
                  "description": "description"
                }
              ]
            }
          ],
          "rateNotes": "Please note that Three Bedroom Residence is located in The Residence Building.",
          "financialInfo": {
            "tmc": "VE",
            "supplier": "Hotelbed",
            "payment": {
              "paymentTypes": "CARD,CR",
              "paymentNetwork": "DS,CA,DC,VI,AX"
            },
            "additionalProperties": [
              {
                "key": "key1",
                "value": "value1",
                "description": "description"
              },
              {
                "key": "key1",
                "value": "value1",
                "description": "description"
              }
            ]
          },
          "additionalProperties": [
            {
              "key": "key1",
              "value": "value1",
              "description": "description"
            },
            {
              "key": "key1",
              "value": "value1",
              "description": "description"
            }
          ]
        }
      ]
    }
  ]
}

Hotel search request with minimum parameters

You can use below request message as well for the search. It has only minimum required parameters.

Hotel search request with minimum parameters
{
    "country": "United Arab Emirates",
    "city": "Dubai",
    "checkIn": "2022-10-25",
    "checkOut": "2022-10-26",
    "rooms": [
        {
            "adult": 1,
            "child": 1,
            "roomIndex": 1
        },
        {
            "adult": 1,
            "child": 0,
            "roomIndex": 2
        }
    ],
    "travelerCountryOfResidence": "INDIA,IN",
    "travelerNationality": "INDIA,IN",
    "culture": "en" 
}