Returns availability in a format suitable for rendering monthly or yearly calendars.
/availability/{propertycode}/flexible-calendar
This API method is computationally expensive. Heavy use of caching is required.
Violations will result in API account ban.
For performance reasons, the following restrictions apply:
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.
| 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=10 | First month of results |
| nights | integer | 1+ | YES | 1 | &nights=2 | Length of stay |
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
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.
| NAME | TYPE | RANGE / SET | REQUIRED | DEFAULT | EXAMPLE | NOTES |
|---|---|---|---|---|---|---|
| startDate | date (ISO 8601) | from today to (today + 3 years) |
YES | – | &startDate=2024-10-29 | First result on this date |
| endDate | date (ISO 8601) |
from (checkin + 1) to (checkin + 1 year) |
YES | – | &endDate=2024-11-29 | Stop processing at this date. |
| nights | integer | 1+ | YES | 1 | &nights=7 | Length of stay and step interval |
The following parameters can be used in any mode.
| 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.
| 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 |
| 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 |
{
"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: "10"
},
{
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.
}
]
}
}
