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

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 2018 – 2020 YES 1 &year=2018 Year of first month of results
month integer 1 – 12 YES 1 &month=12 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 + 2 years)
YES &fromd=2018-12-10 First result on this date
endDate date (ISO 8601) from (checkin + 1)
to (checkin + 1 year)
YES &tod=2019-01-10 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).

Filters

NAME TYPE RANGE / SET REQUIRED DEFAULT EXAMPLE NOTES
room string varchar(6) NO &room=DBL Only returns availability for specified room type
rate integer NO &rate=1000 Only returns availability for specified rate
board integer 1 – 23 NO &board=19 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.
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: "2018"
		},
		{
			type: "URL"
			name: "month"
			value: "12"
		},
		{
			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
				"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.
			}
		]
	}
}