Introduction

In 2022, we introduced Search API in JSON format to get faster API responses with less verbose input and greater flexibility in customizing requests and responses using extra parameters. However, partners still needed multiple CIDs to get offers for different rate fences.

Now we are enhancing it further with capability that allows partners to access all the eligible rate fences through a single CID, reducing integration time and operational complexity.

Availability Search API

The Availability Search API provides rates and availability for all room types at specified hotels based on your search criteria and any additional parameters you may need (e.g., period of stay, number of passengers, currency).

Authorization / Header

Every request must include an Authorization Header containing your siteid and apikey separated by a colon. This header is mandatory for all API requests.

By adopting this new format, you can enjoy quicker responses and more tailored search results, enhancing your overall experience.

Authorization: 1234567: 00000000-0000-0000-0000-000000000000

Key: VALUE
Content-Type: application/json
Authorization: siteId:apikey

Live calls

Partners will be using the below request to get best possible offers when they request offers for their live user traffic.

Search API(Live calls) - Request Example

{
  "liveOffersContext": {
    "userContext": {
      "channel": "mobile-web",
      "userGroup": "logged-in",
      "userCountry": "US" 
    },
    "saleContext": {
      "packageType": "non-packaged",
      "distributionType": "direct",
    } 
  },
  "criteria": {
    "propertyIds": [12157],
    "checkIn": "2025-02-14",
    "checkOut": "2025-02-16",
    "rooms": 1,
    "adults": 2,
    "children": 2,
    "childrenAges": [12, 18],
    "language": "en-us",
    "currency": "USD",
  },
  "features": {
    "ratesPerFence": 5,              
    "extra": ["Content", "RateDetail", "SurchargeDetail"]
  }
}

Parameter for Search API-Request Schema (Live calls)

Element	Attribute	Description
liveOffersContext		An object that contains two sub-objects, userContext and saleContext, to represent the search criteria when a partner requests offers in Live Offers mode. Either allOffersContext or liveOffersContext must be present in the request, but not both. If both fields are provided, or neither is included, the system should return a descriptive error.
liveOffersContext	userContext * Object	An object containing three parameters that define the end-user segment the partner wants to target for sales. Following parameters to be defined. Refer to “required Field” column to check whether filed is mandatory or optional
liveOfferContext.userContext	channel* Enum • mobile-web • desktop-web • mobile-app	A string enum used by the partner to specify the channels or platforms for which they want to request offers. Single value supported. The value provided by the partner for this field must be selected from the list of supported values (shown). If an invalid value is submitted—including incorrect case sensitivity—the system should return an error specifying which value is not allowed. This field must always be present, and empty string is not supported.
liveOfferContext.userContext	userGroup* Enum • logged-out • logged-in • premium	A string enum by the partner to specify the user group for which they want to request offers. The value provided by the partner for this field must be selected from the list of supported values (shown). If an invalid value is submitted—including incorrect case sensitivity—the system should return an error specifying which value is not allowed. This field must always be present, and empty string is not supported.
liveOfferContext.userContext	userCountry* String	A string indicating the end-user country for which the partner wants to retrieve offers. A string indicating countries in ISO2 format. We will support only one userCountry, in case multiple userCountry are requested, the request will fail.
liveOffersContext	saleContext* Object	An object containing two parameters that define the offer segment the partner wants to target for sales. All two parameters must be defined.
liveOfferContext.saleContext	packageType* Enum • packaged • non-packaged	A string enum by the partner to specify whether they want offers for packaged sales, non-packaged sales, or offers that support both. The value provided by the partner for this field must be selected from the list of supported values. If an invalid value is submitted—including incorrect case sensitivity—the system should return an error specifying which value is not allowed. This field must always be present, and empty string is not supported.
liveOfferContext.saleContext	distributionType* Enum • direct • forward	A string enum by the partner to specify whether they want offers for packaged sales, non-packaged sales, or offers that support both. The value provided by the partner for this field must be selected from the list of supported values. If an invalid value is submitted—including incorrect case sensitivity—the system should return an error specifying which value is not allowed. This field must always be present, and empty string is not supported.
criteria*	propertyIds* Array[integer]	Agoda Hotel IDs. Supports maximum 100 hotels per request. Please refer to “ratesPerFence” for details.
criteria*	checkIn* Date	YYYY-MM-DD. checkIn date must be hotel local timezone. It needs to be greater than, equal to (or less than one day from) today’s date (to cover property time zone difference). Bookings are supported only up to 365 days in advance from the current date
criteria*	checkOut* Date	YYYY-MM-DD. checkOut date must be greater than checkIn date.
criteria*	rooms* Integer	Number of Rooms
criteria*	adults* Integer	Number of Adults
criteria*	children* Integer	Number of children
criteria*	childrenAges Array[integer]	The age list of children (minimum 0, maximum 17). To be passed only when criteria.children > 0 and is required to pass the same "childrenAges" throughout searchRequest, bookingRequest & bookingResult. If 2 children with ages of 5 and 8, then childrenAges = [5,8]. Empty array like "childrenAges": [] is NOT allowed. Extra beds and meals are not guaranteed for stay for free children.
criteria*	language* String	Please refer to Appendix: Language part for language codes
criteria*	currency* String	Please refer to Appendix: Currency part for currency codes
features	ratesPerFence Integer	Number of best rate(s) available for a property. per fence. The value of ratesPerFence depends on the number of hotels included in the request: - For Single hotel search ratesPerFence supports values from 1 to 100 (max). - For 2–30 HIDs in one search ratesPerFence supports values from 1 to 25 (max). ]() - For 31–100 HIDs in one search ratesPerFence supports a maximum value of 1.
features	extra Array[string]	Optional parameters can be added to request additional details in the search response. For partners using the fulfillment model, please do not include "metaSearch" as it is not designed for this mode. enum - "content" - "dailyRate" - "metaSearch" - "benefitDetail" - "cancellationDetail" - "promotionDetail" - "rateDetail" - "surchargeDetail" - "taxDetail"

Cache Calls

In the cache calls, partners can fetch the offers for all the eligible fences. Since offers for all the eligible fence will be returned, partners are not required to pass all values of ‘offerContext’ and ‘saleContext’.

Search API(Cache calls) - Request Example

{
  "allOffersContext": {
    "userContext": {
      "userCountries": ["US"] ,
    }
  },
 "criteria": {
    "propertyIds": [12157],
    "checkIn": "2025-02-14",
    "checkOut": "2025-02-16",
    "rooms": 1,
    "adults": 2,
    "children": 2,
    "childrenAges": [12, 18],
    "language": "en-us",
    "currency": "USD",
  },
  "features": {
    "ratesPerFence": 5,
    "extra": ["Content", "RateDetail", "SurchargeDetail"]
  }
}

Parameter for Search API-Request Schema (Cache calls)

Element	Attribute	Description
allOffersContext		An object that contains sub-object userContext to represent the search criteria when a partner requests offers in All Offers mode. Either allOffersContext or liveOffersContext must be present in the request, but not both. If both fields are provided, or if neither is included, the system should return a descriptive error.
allOffersContext	userContext*	An object containing one parameter that defines the end-user segment the partner wants to target for sales. Following parameter to be defined. Refer to “required Field” column to check whether filed is mandatory or optional
allOffersContext.userContext	userCountries* Array[String]	An array of UPPERCASE strings indicating the end-user countries for which the partner wants to retrieve offers. • An array of strings indicating countries in ISO2 format. • For now, this array supports only a single value. If more than one value is provided, the request should fail with an error.
criteria*	propertyIds* Array[Integer]	Agoda Hotel IDs. Supports maximum 100 hotels per request. Please refer to ratesPerFence for details.
criteria*	checkIn* Date	YYYY-MM-DD. checkIn date must be hotel local timezone. It needs to be greater than, equal to (or less than one day from) today’s date (to cover property time zone difference). Bookings are supported only up to 365 days in advance from the current date
criteria*	checkOut* Date	YYYY-MM-DD. checkOut date must be greater than checkIn date.
criteria*	rooms* Integer	Number of Rooms
criteria*	adults* Integer	Number of Adults
criteria*	children* Integer	Number of children
criteria*	childrenAges Array[Integer]	The age list of children (minimum 0, maximum 17). To be passed only when criteria.children > 0 and is required to pass the same childrenAges throughout searchRequest, bookingRequest & bookingResult. If 2 children with ages of 5 and 6, then childrenAges = [5,6]. Empty array like "childrenAges": [] is Not allowed. Extra beds and meals are not guaranteed for stay-for-free children.
criteria*	language* String	Please refer to Appendix: Language part for language codes
criteria*	currency* String	Please refer to Appendix: Currency part for currency codes
features	ratesPerFence Integer	Number of best rate(s) available for a property. per fence. The value of ratesPerFence depends on the number of hotels included in the request: - For Single hotel search ratesPerFence supports values from 1 to 100 (max). - For 2–30 HIDs in one search ratesPerFence supports values from 1 to 25 (max). ]() - For 31–100 HIDs in one search ratesPerFence supports a maximum value of 1.)
features	extra Array[String]	Optional parameters can be added to request additional details in the search response. For partners using the fulfillment model, please do not include "metaSearch" as it is not designed for this mode. enum - "content" - "dailyRate" - "metaSearch" - "benefitDetail" - "cancellationDetail" - "promotionDetail" - "rateDetail" - "surchargeDetail" - "taxDetail"

Parameter for Search API – Response Sample

{
   "searchId":615201261069120000,
   "properties":[
      {
         "propertyId":266948,
         "propertyUtcOffset":"+07:00",
         "rooms":[
            {
               "roomId":10487365,
               "blockId":"block_idv3",
               "offerToken":"offer_token",
               "roomName":"Beach Villa",
               "parentRoomName":"Beach Villa",
               "translatedRoomName":"Beach Villa",
               "blockIdBackup":"06e47455-1563-92f7-d065-c371f7b92d0c",
               "parentRoomId":3134583,
               "ratePlanId":617128,
               "freeWifi":false,
               "remainingRooms":38,
               "normalBedding":2,
               "extraBeds":0,
               "freeBreakfast":true,
               "freeCancellation":true,
               "totalPayment":{
                  "exclusive":83.96,
                  "inclusive":107.14,
                  "tax":15.46,
                  "fees":7.72,
                  "taxDueSupplier":0
               },
               "roomTypeNOtGuaranteed":false,
               "paymentModel":"Merchant",
               "rate":{
                  "currency":"USD",
                  "exclusive":74.56,
                  "inclusive":95.14,
                  "tax":13.8,
                  "fees":6.78,
                  "method":"PRPN"
               },
               "perRoomPerNightRate":{
                  "currency":"USD",
                  "exclusive":74.56,
                  "inclusive":95.14,
                  "tax":13.8,
                  "fees":6.78
               },
               "dailyRate":[
                  {
                     "date":"2024-05-30",
                     "exclusive":74.56,
                     "inclusive":95.14,
                     "tax":13.8,
                     "fees":6.78,
                     "method":"PN"
                  }
               ],
               "promotionDetail":{
                  "promotionId":196413638,
                  "codeEligible":false,
                  "description":"Limited Time Offer. Price includes 40% discount!",
                  "savingAmount":108.2
               },
               "surcharges":[
                  {
                     "id":255,
                     "method":"PB",
                     "charge":"Excluded",
                     "margin":"n",
                     "name":"Roundtrip Speed Boat Transfer Fee",
                     "rate":{
                        "currency":"USD",
                        "exclusive":420,
                        "inclusive":420,
                        "tax":0,
                        "fees":0
                     }
                  },
                  {
                     "id":278,
                     "method":"PB",
                     "charge":"Mandatory",
                     "margin":"n",
                     "name":"Green Tax",
                     "rate":{
                        "currency":"USD",
                        "exclusive":9.4,
                        "inclusive":12,
                        "tax":1.66,
                        "fees":0.94
                     }
                  }
               ],
               "taxBreakdown":[
                  {
                     "id":"1",
                     "typeValue":"Tax",
                     "taxDescription":"Sales tax",
                     "translatedTaxDescription":"Sales tax",
                     "method":"PRPN",
                     "currency":"USD",
                     "base":"N",
                     "taxable":"N",
                     "percent":16,
                     "amount":13.8
                  },
                  {
                     "id":"2",
                     "typeValue":"Fee",
                     "taxDescription":"Service charge (taxable)",
                     "translatedTaxDescription":"Service charge (taxable)",
                     "method":"PRPN",
                     "currency":"USD",
                     "base":"N",
                     "taxable":"Y",
                     "percent":10,
                     "amount":6.78
                  }
               ],
               "cancellationPolicy":{
                  "code":"1D1N_1N",
                  "cancellationText":"Risk-free booking! Cancel before 2024-05-29 and you'll pay nothing! Any cancellation received within 1 day prior to the arrival date will incur the first night's charge. Failure to arrive at your hotel or property will be treated as a NO-Show and will incur the first night's charge (Hotel policy).",
                  "translatedCancellationText":"Risk-free booking! Cancel before 2024-05-29 and you'll pay nothing! Any cancellation received within 1 day prior to the arrival date will incur the first night's charge. Failure to arrive at your hotel or property will be treated as a NO-Show and will incur the first night's charge (Hotel policy).",
                  "parameter":[
                     {
                        "days":2,
                        "charge":"N",
                        "value":0
                     },
                     {
                        "days":1,
                        "charge":"N",
                        "value":1
                     },
                     {
                        "days":0,
                        "charge":"N",
                        "value":1
                     }
                  ],
                  "date":[
                     {
                        "before":"2024-05-29T00:00:00",
                        "rate":{
                           "exclusive":0,
                           "inclusive":0,
                           "tax":0,
                           "fees":0
                        }
                     },
                     {
                        "before":"2024-05-30T00:00:00",
                        "rate":{
                           "exclusive":74.56,
                           "inclusive":95.14,
                           "tax":13.8,
                           "fees":6.78
                        }
                     },
                     {
                        "onward":"2024-05-30T00:00:00",
                        "rate":{
                           "exclusive":74.56,
                           "inclusive":95.14,
                           "tax":13.8,
                           "fees":6.78
                        }
                     }
                  ]
               },
               "benefits":[
                  {
                     "id":1,
                     "benefitName":"Breakfast",
                     "translatedBenefitName":"Breakfast"
                  },
                  {
                     "id":10,
                     "benefitName":"Welcome drink",
                     "translatedBenefitName":"Welcome drink"
                  },
                  {
                     "id":34,
                     "benefitName":"Express check-in",
                     "translatedBenefitName":"Express check-in"
                  },
                  {
                     "id":95,
                     "benefitName":"Free WiFi",
                     "translatedBenefitName":"Free WiFi"
                  },
                  {
                     "id":230,
                     "benefitName":"Drinking water",
                     "translatedBenefitName":"Drinking water"
                  },
                  {
                     "id":115,
                     "benefitName":"Free fitness center access",
                     "translatedBenefitName":"Free fitness center access"
                  }
               ],
               "offerContext":{
                  "userContext":{
                     "channels":[
                        "mobile-web",
                        "mobile-app"
                     ],
                     "userGroups":[
                        "logged-out",
                        "logged-in",
                        "premium"
                     ]
                  },
                  "saleContext":{
                     "packageTypes":[
                        "non-packaged"
                     ],
                     "distributionTypes":[
                        "forward",
                        "direct"
                     ]
                  }
               }
            }
         ]
      }
   ]
}
}

Parameter for Search API – Response Schema

Element	Attribute	Description
searchId*		The unique ID that this search received in our system
properties*	propertyId* integer	Agoda's hotel ID
	propertyName string	Hotel name, This field can only be returned when sending "content" in "extra"
	translatedPropertyName string	Translated hotel name, This field can only be returned when sending "content" in "extra"
	propertyUtcOffset string	Utc Timezone of the Property
properties->rooms*	roomId* long	The ID of the room type
	blockId* string(max 500 bytes)	New unique identifier for each room, provide as a unique key for partner’s caching. Please use this one instead of blockIdBackup.Possible characters for blockID includes: • Uppercase letters: A-Z • Lowercase letters: a-z • Digits: 0-9 • Plus (+) • Slash (/) • Underscore (_) • Equals sign (=) • Dash (-)
	offerToken* string	It carries fence-specific information needed to process the offer
	roomName string	Room Name, This field can only be returned when sending "content" in "extra"
	parentRoomName string	Parent room name, This field can only be returned when sending "content" in "extra"
	translatedRoomName string	Room name translated (As per language you perform in the request), This field can only be returned when sending "content" in "extra"
	blockIdBackup string	Old version of blockId, in XML format response.
	parentRoomId* long	The ID of the parent room type
	ratePlanId* long	Used to identify the Agoda rate plan
	freeWifi boolean	True if Free Wifi available, This field can only be returned when sending "content" in "extra"
	remainingRooms integer	The rooms (allotment) remaining under same Room ID. This field can only be returned when sending "rateDetail" in 'extra'
	normalBedding integer	Number of occupancies with normal bedding. This field can only be returned when sending 'rateDetail' in 'extra'
	extraBeds integer	Number of extra beds. This field can only be returned when sending 'rateDetail' in 'extra'
	freeBreakfast* boolean	True if breakfast included for this rate
	freeCancellation* boolean	True if there is Free cancellation for booking in this room
	freeCancellationDate DateTime	Free cancellation date in the format YYYY-MM- DD. This field can only be returned when sending "metaSearch" in "extra"
	landingUrl string	The landing page URL that you use if the customer clicks through. This field can only be returned when sending "metaSearch" in "extra"
	roomTypeNotGuaranteed boolean	True if it is Run of House room type. This field can only be returned when sending ‘rateDetail’ in 'extra'
	payAtHotel Boolean	True if there is the pay at hotel is available for this booking in this room.This field can only be returned when sending "metaSearch" in "extra"
	paymentModel string	Possible values for paymentModel field are: - Agency: Booking will be charged at hotel, - Merchant: Pre-paid, - MerchantCommission: Pre-paid This field can only be returned when sending "rateDetail" in "extra"
	bookNowPayLaterDate string	Later date on which the payment is to be made in BNPL
properties -> rooms ->totalPayment	exclusive Number	Exclusive rate breakdown per booking, excluding taxes but includes room charge and mandatory surcharges
	inclusive Number	Rate breakdown per booking, including room charge and mandatory surcharge
	tax Number	Tax breakdown per booking
	fees Number	Fees breakdown per booking
	estimatedCommission Number	Estimated commission that partner may get. Please contact technical team to get this column.
	taxDueSupplier Number	Agoda owes supplier as tax
properties->rooms->rate*	currency string	Requested currency. Details are on Currency Part (Appendix)
	exclusive* number	The cost per room per night exclusive of tax and service fees
	inclusive* number	The cost per room service charge inclusive of tax and service fees
	tax* number	Tax amount of room value
	fees* number	Fees of room value
	method string	“PRPN”, "PB", "PN" or "PR"
	stayPackageType integer	Used to signifiy special offer. Not applicable for all partners.
properties->rooms->perRoomPerNightRate	currency string	Requested currency. Details are on Currency Part (Appendix)
	exclusive* number	The cost per room per night exclusive of tax and service fees
	inclusive* number	The cost per room service charge inclusive of tax and service fees
	tax* number	Tax amount of room value
	fees* number	Fees of room value
	stayPackageType integer	Used to signify special offer. Not applicable for all partners.
properties->rooms->rate->ratePlan (Not applicable for all partners.)	name string	Name of the special rate channel
	description string	Description of the special rate channel, max character length is 2000
	inclusions string	Inclusions that are applicable for the special rate channel, max character length is 2000
	exclusions string	Exclusions that are applicable for the special rate channel, max character length is 2000
	checkInTime string	Check-In time at hotel that are applicable for the special rate channel
	checkoutTime string	Check-out time at hotel that are applicable for the special rate channel
properties->rooms->rate->ratePlan->checkInTime(Not applicable for all partners.)	startTime string	Start time of check-in for the special rate channel. Returned only if applicable.
	endTime string	End time of check-in for the special rate channel. Returned only if applicable.
properties->rooms->rate->ratePlan->checkoutTime(Not applicable for all partners.)	startTime string	Start time of check-out for the special rate channel. Returned only if applicable.
	endTime string	Start time of check-out for the special rate channel. Returned only if applicable.
properties->rooms->dailyRate	date* DateTime	YYYY-MM-DD
	exclusive* number	Rate breakdown per night without discount
	tax* number	Tax breakdown per night without discount
	fee* number	Fees breakdown per night without discount
	inclusive number	Rate breakdown per night without discount
	method string	Always "PN"
properties -> rooms -> promotionDetail	promotionId Integer	Promotion ID
	codeEligible Boolean	True if special promotion campaign applied to this room/rate
	description String	Promotion description
	savingAmount Number	Promotion saved amount
properties -> rooms -> surcharges	id Integer	Surcharge ID
	method String	Always "PB"
	charge String	Possible charge values as follows: - Mandatory – Surcharges will be charged in addition to room price at time of booking creation - Excluded – Surcharges are not charged at time of booking creation; customers will pay the surcharges at a hotel directly
	margin Number	There are two possible values for "margin" as follows: y=Margin applied n=No surcharge margin
	name String	Surcharge name
	rate-> currency String	Surcharge currency (As per search request)
	rate-> exclusive Number	Surcharge exclusive amount
	rate-> inclusive Number	Surcharge inclusive amount
	rate-> tax Number	Surcharge tax amount
	rate-> fees Number	Surcharge fees amount
properties->rooms[]->room->taxBreakdown	id* string	Tax ID
	typeValue* string	Possible types are: “Tax” or “Fee”
	taxDescription* string	Tax or Fee description
	translatedTaxDescription* string	Translated tax description
	method* string	Possible method values as follows: PAPB=Per Adult Per Booking PAPD=Per Adult Per Day PAPN=Per Adult Per Night PB=Per Booking PCPB=Per Child Per Booking PCPD=Per Child Per Day PCPN=Per Child Per Night PGPB=Per Guest Per Booking PGPD=Per Guest Per Day PGPN=Per Guest Per Night PN=Per Night PRPB=Per Room Per Booking PRPN=Per Room Per Night
	base* string	There are possible values for ‘base’ as follows: M=Tax over Margin N=Tax over Net
	taxable* string	Possible taxable values are Y=Tax apply over fee N=Tax doesn’t apply over fee
	percent* number	Tax or fee percentage
	currency* string	Tax or fee amount of its currency
	amount* number	Tax or fee amount of its currency
properties ->rooms -> cancellationPolicy	code String	Cancellation policy in code format. E.g. 1D1N_100P
	cancellationText String	Cancellation policy in text format
	translatedCancellationText String	Cancellation policy in translated text format Note: If it is an external provider, this Policy translated will not be able to offer.
properties ->rooms -> cancellationPolicy -> parameter	days Integer	Number of days prior to check-in date that cancellation fee will be applied. Except for: 365 Days with 100 Percent=the booking is non-refundable.
	charge String	There are two possible values for "charge" as follows: N=Night P=Percent
	value Integer	Charge value
properties ->rooms cancellationPolicy -> date	before timestamp	Datetime in hotel local time, YYYY-MM-DDTHH:MM:SS
properties ->rooms cancellationPolicy -> date	onward timestamp	Datetime in hotel local time, YYYY-MM-DDTHH:MM:SS
properties -> cancellationPolicy -> date -> rate	exclusive Number	Exclusive cancellation fee
	inclusive Number	Total amount of cancellation fee
	tax Number	Cancellation tax amount
	fees Number	Cancellation fees amount
properties->rooms->benefits	id* long	Benefit ID
	benefitName* string	Benefit name Please check how to identify benefit quantity in our best practice page.
	translatedBenefitName* string	Benefit name translated
properties->rooms->feeWaivers(For CA hotels only)	feeWaivers string	Total amount of fee waiver in percentage, 100P, 0P etc.
	expiry string	Expiry time in hours format, 24H, 48H etc.
	leadTime string	Total lead time in hours format, 24H, 48H etc.
properties->rooms->offerContext*	userContext* Object	Parent Objects hold information specific on the user segment that each offer can be exposed to.
properties->rooms->offerContext->userContext*	channels* Array<Enum>	On which channels these offers can be exposed. (We are calling it channel, not platform, because in future there will be more enums here like wholesale.) Enum values: desktop-web mobile-web mobile-app
	userGroups* Array<Enum>	To which user groups these offers can be exposed. Enum values: logged-out logged-in premium
	userCountry* Object	Parent object holding information specific to the country segment that each offer can be exposed to.
properties->rooms->offerContext->saleContext*	packageTypes* Array<Enum>	Can be sold only with package offers or any. Enum values: packaged non-packaged
properties->rooms->offerContext->saleContext*	distributionTypes* Array<Enum>	Can be sold for direct distribution or forward distribution. Enum values: direct forward Can be ignored in first phase; added for future use cases.