Perform an availability request for a single property

Table of Contents
  1. URL Endpoint
  2. Method Parameters
  3. JSON Response Schema
  4. JSON Response Example

URL Endpoint

/availability/{propertycode}

Method Parameters

Basic parameters

NAME TYPE RANGE / SET REQUIRED DEFAULT EXAMPLE NOTES
checkin date (ISO 8601) from today
to (today + 3 years)
YES &checkin=2024-02-29  
checkout date (ISO 8601) from (checkin + 1)
to (checkin + 30)
NO* checkin + 1 day &checkout=2024-03-07 When used, number of nights is automatically calculated. Limitations apply (see nights).
nights integer 1 – 30 NO* 1 &nights=2  
adults integer 1 – max capacity NO 2 &adults=2 The value is PER ROOM. Maximum value is automatically calculated based on the property's maximum possible room capacity.
children integer 0 – (max capacity-1) NO 0 &children=1 The value is PER ROOM. Maximum value equals (maximum capacity - 1).
infants integer 0 – (max capacity-1) NO 0 &infants=1 The value is PER ROOM. Maximum value equals (maximum capacity - 1).
rooms integer 1 – 5 NO 1 &rooms=2  
party JSON string NO** - One room: &party=[{"adults": 2}]

Two rooms with mixed occupancies: &party=[{"adults":2, "children":[2,6]},{"adults":3}]
Array of JSON objects representing number of adults and children.
"adults": (REQUIRED - integer) The number of adults staying in the room.
"children": (OPTIONAL - array of integers) The ages of any children staying in the room.

* Use either checkout or nights, never both. checkout parameter takes precedence if both present.

** Use either party or rooms + adults + children + infants, never both. party parameter takes precedence if both present.


Filters

NAME TYPE RANGE / SET REQUIRED DEFAULT EXAMPLE NOTES
room string varchar(4000) NO &room=DBL
&room=DBL,TRP,SUITE
Room code or comma delimited list of room codes. Only returns availability for specified room type(s)
rate integer NO &rate=448033 Only returns availability for specified rate
board integer 1 – 23 NO &board=19
&board=3,19,21
Returns rates with specified board

Advanced parameters

NAME TYPE RANGE / SET REQUIRED DEFAULT EXAMPLE NOTES
remote_country string ISO 3166-1-alpha-2 NO &remote_country=US Specifies remote user's country.
Use ip address geolocation.
Required for working with markets.
remote_ip string Dot-decimal notation NO &remote_ip=94.71.170.105 Specifies remote user's ip address.
Alternative to country.
Required for working with markets.
Only IPv4 supported.
device string MOBILE
DESKTOP
NO* &device=MOBILE Specified user device.
Used to unlock special pricing policies.
bk_code string varchar(255) NO &bk_code=SPECIALRATES Returns private rates that are enabled by specified booking code
voucher string varchar(255) NO &voucher=VCH123 Unlocks special offers
offer_id integer 1+ NO &offer_id=214365 Returns only rates participating in this offer.
Offer IDs can be retrieved with the Offer Search API
breakdown boolean   NO false &breakdown=1 Returns rate's price daily breakdown.
offline boolean   NO false &offline=1 Returns all rates, even those not available.
payments boolean   NO true for Travel Agents, false for all the others &payments=1 Returns payments & cancellation_fees fields.
taxes boolean   NO false &taxes=1 Returns tax breakdown.

You can use remote_country or remote_ip. If you use both, remote_country takes precedence and remote_ip is ignored.

JSON Response Schema

{
	"method": "http://rest.reserve-online.net/availability/DEMO",
	"http_method": "GET",
	"http_code": 200,
	"error_code": "OK",
	"error_msg": "",
	"params": [
		{
			"type": "URL",
			"name": "checkin",
			"value": "2024-02-29"
		},
		{
			"type": "URL",
			"name": "checkout",
			"value": "2024-03-07"
		}
	],
	"data": {
		"code":STRING, // Property code 
		"name":STRING, // Property name
		"currency":ISO 4217, // Rate currency ISO code
		"url": {
			"website":URL, // Property website url (empty if not defined)
			"info":URL, // API URL for property info request
			"engine":URL, // Property booking engine url (empty if not defined)
			"photo":URL, // Property photo url - Small size (empty if not defined)
			"photoM":URL, // Property photo url - Medium size (empty if not defined)
			"photoL":URL // Property photo url - Large size (empty if not defined)
		},
		"location": {
			"lat":DECIMAL, // Property latitude (empty if not defined)
			"lon":DECIMAL // Property longitude (empty if not defined)
		},
		"rates": [ // List of rates
			{
				"id":INTEGER, // Rate ID
				"type":STRING, // Room type code
				"room":STRING, // Room type name
				"rate":STRING, // Rate name
				"rate_desc":STRING, // Rate description
				"payment_policy":STRING, // Rate payment policy description
				"payment_policy_id":INTEGER, // Rate payment policy id (for internal use)
				"cancellation_policy":STRING, // Rate cancellation policy description
				"cancellation_policy_id":INTEGER, // Rate cancellation policy id (for internal use)
				"cancellation_penalty":STRING, // Rate cancellation penalty description
				"remaining":INTEGER, // Remaining available rooms
				"cancellation_expiry":ISO 8601, // Free cancellation expiry date timestamp (empty if no free cancellation is set)
				"board":INTEGER // Board ID (empty if not defined). See Board Types
				"url": {
					"engine":URL, // Booking engine availability url with the specified parameters 
					"rate":URL, // API URL for rate info request  
					"room":URL, // API URL for room info request 
					"photo":URL, // Photo url - Small size (empty if not defined)
					"photoM":URL, // Photo url - Medium size (empty if not defined)
					"photoL":URL // Photo url - Large size (empty if not defined)
				},
				"pricing": {
					"stay":MONEY, // Room price (exclusive of extras and taxes)
					"extras":MONEY, // Extras amount
					"taxes":MONEY, // Taxes amount
					"excluded_charges":MONEY, // Excluded charges amount
					"price":MONEY, // Total rate price. This is the final price in case of booking.
					"discount":MONEY, // Discount amount. Indicates if the rate is an offer. Appears only for Hotelier API accounts
					"margin":MONEY, // Difference between retail and NET price. Appears only for Travel Agent/Corporate accounts
				},
				(Appears only for Travel Agent/Corporate accounts. Can be used as a threshold to determine your markup.
				A NET rate may not always be derived from a retail rate. In this case, the retail price is the same as the NET price.)
				"retail": {
					"stay":MONEY, // Retail room price (exclusive of extras and taxes)
					"extras":MONEY, // Retail extras amount
					"taxes":MONEY, // Retail taxes amount
					"excluded_charges":MONEY, // Retail excluded charges amount
					"price":MONEY, // Retail total rate price
					"discount":MONEY, // Retail discount amount. Indicates if the rate is an offer.
				},
				"payments": [
					{
						"due":ISO 8601, // Payment due date 
						"amount":MONEY // Amount to be paid until the above date
					}
				],
				"cancellation_fees": [
					{
						"after":ISO 8601, // Cancellation fee is applied if the reservation is cancelled after this date
						"fee":MONEY // Cancellation fee amount that applies after the above date
					}
				],
				"days": [ // Pricing per day breakdown (exists only when breakdown=1 parameter is used)
					{
						"date":ISO 8601, // Date in ISO 8601 format
						"min_stay":INTEGER, // Minimum stay in days. Optional, exists only when > 1.
						"max_stay":INTEGER // Maximum stay in days. Optional, exists only when defined.
						"checkin":BOOLEAN, // 1=Check-in is allowed, 0=Check-in not allowed (optional, default=1)
						"status":STRING, // Availability status other than "AVL", appears only if for offline=1. See Availability Status Codes
						"remaining":INTEGER, // Remaining available rooms
						"price":MONEY, // Room final price 
						"initial":MONEY, // Room initial price 
						"discount":MONEY, // Price discount 
					}
				],
				"taxes": [ // Tax breakdown (exists only when taxes=1 parameter is used)
					{
						"tax_id":INTEGER, // Tax ID. Use the data.taxes array to get details about each tax.
						"value":MONEY // Total amount for this tax
					}
				],
				(status & status_descr appear only when offline=1 parameter is used)
				"status":STRING, // Availability status code. See Availability Status Codes
				"status_descr": STRING, // Availability status title. See Availability Status Codes
				"labels": [ // Optional. Exists only if labels are defined for the rate.
					{
						"code":STRING, // Enumerated value. See Rate Labels. More new values may be added at any time.
						"title":STRING // Simple label description
					}
				]
			}
		],
		"taxes": [ // Tax information lookup table (exists only when taxes=1 parameter is used)
			{
				"tax_id":INTEGER,
				"order":INTEGER,
				"description":STRING,
				"included":INTEGER, // 1=Included in price, 0=Applied on top of the final price, -1=Collected separately/payable at property
				"per_room":BOOLEAN, // 1=True, 0=False
				"per_day":BOOLEAN, // 1=True, 0=False
				"per_adult":BOOLEAN, // 1=True, 0=False
				"per_child":BOOLEAN, // 1=True, 0=False
				"per_infant":BOOLEAN, // 1=True, 0=False
				"fromd":ISO 8601,
				"tod":ISO 8601,
				"type":STRING, // ABS=Flat Amount, MU_PER=Percentage
				"value":MONEY // Unit value, may reflect percentage or flat amount
			}
		]
	}
}
	

JSON Response Example

In the example below the request was submitted with offline=1. This is why rates with statuses other than AVL were returned (e.g. SS = Stop Sales and RATE = Pricing Missing). See more in the Availability Status table