Returns availability in a format suitable for rendering monthly or yearly calendars.

Table of Contents
  1. URL Endpoint
  2. Mode 1: Month View
  3. Mode 2: Stepped View
  4. Common Parameters
  5. JSON Response Schema
  6. JSON Response Example

URL Endpoint

/availability/{propertycode}/flexible-calendar

Caching Required

This API method is computationally expensive. Heavy use of caching is required.

Violations will result in API account ban.

Warning

For performance reasons, the following restrictions apply:

  • Month View returns availability information for two months
  • Stepped View returns up to 60 results. Maximum date range cannot exceed 1 year.

Mode 1: Month View

Month view returns two full calendar months with availability results based on specified length of stay.

For example, if you specify nights=3, each result will return status and pricing for check-ins on that date and length of stays of 3 nights.

Parameters

NAME TYPE RANGE / SET REQUIRED DEFAULT EXAMPLE NOTES
year integer 2024 – 2026 YES 1 &year=2024 Year of first month of results
month integer 1 – 12 YES 1 &month=9 First month of results
nights integer 1+ YES 1 &nights=2 Length of stay

Mode 2: Stepped View

Stepped view returns availability results based on intervals.

It begins on startDate and returns availability for specified LOS. Then, number of days equal to LOS are skipped and a new availability result is calculated. Processing stops when endDate is reached

Example Application

Stepped View can be useful in scenarios where a property (e.g. Villa) has a long minimum stay and check-in restrictions and want to display a full calendar year of availability.

For example, let's say there is a minimum stay of 1 week. By specifying &nights=7, &startDate the first available date where check-in is allowed and &endDate a year later (or end of season), this method will return availability status for each week.

Parameters

NAME TYPE RANGE / SET REQUIRED DEFAULT EXAMPLE NOTES
startDate date (ISO 8601) from today
to (today + 3 years)
YES &startDate=2024-09-20 First result on this date
endDate date (ISO 8601) from (checkin + 1)
to (checkin + 1 year)
YES &endDate=2024-10-20 Stop processing at this date.
nights integer 1+ YES 1 &nights=7 Length of stay and step interval

Common Parameters

The following parameters can be used in any mode.

Basic Parameters

NAME TYPE RANGE / SET REQUIRED DEFAULT EXAMPLE NOTES
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 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

JSON Response Schema

{
	"method": "https://rest.reserve-online.net/availability/DEMO/flexible-calendar"
	"http_method": "GET",
	"http_code": 200,
	"error_code": "OK",
	"error_msg": "",
	"params": [
		{
			type: "URL"
			name: "year"
			value: "2024"
		},
		{
			type: "URL"
			name: "month"
			value: "9"
		},
		{
			type: "URL"
			name: "nights"
			value: "1"
		}
	],
	"data":{
		"days":[
			{
				"date":ISO 8601, // Check-in date
				"rm_type":STRING, // Room code
				"rate_id":INTEGER, // Rate id
				"status":STRING, // Availability status. See Availability Status Codes
				"price":MONEY, // Total price of stay. Optional, exists only for status AVL, MAX, MIN, CHKIN, CHKOUT
				"excluded_charges":MONEY, // Total amount of excluded charges. Optional, exists only when "price" exists.
				"discount":MONEY, // Discount amount(already deducted from stay price). Optional, exists only when discount > 0.
				"currency":ISO 4217, // Price currency. Optional, exists only when price is defined.
				"min_stay":INTEGER, // Minimum stay in days. Optional, may be empty.
				"max_stay":INTEGER // Maximum stay in days. Optional, exists only when > 1.
			}
		]
	}
}
	

JSON Response Example