Despegar.com - Hotels, flights, packages, cars, and more!

## Get Availability and Restrictions

**URL**: ```/v1/hotels/availability/get```

### Goals

To return the availability and restrictions for a date range, either for the given property or for all or any room/rate

### Notes

#### Allotment or Restrictions

Since allotment is defined at the room-level while restrictions are defined
at the room-rate plan-level, an `AvailStatusMessage` element may indicate either 
allotment or restrictions, exclusively.

For allotment, the `AvailStatusMessage` element will include `@BookingLimit` and 
`@BookingLimitMessageType` attributes, and contain a `StatusApplicationControl` element
without `@RatePlanCode` attribute.

For restrictions, the `AvailStatusMessage` element will contain a 
`StatusApplicationControl` element including `@Start`, `@End`, `@RatePlanCode`, 
and `@InvCode` attributes. The `AvailStatusMessage` element will also include 
`LengthsOfStay` and/or `RestrictionStatus` elements.

```xml
<OTA_HotelAvailGetRS xmlns="http://www.despegar.com/hotels/ota/v1/" Version="v1" CorrelationID="123">
    <Success/>
    <AvailStatusMessages HotelCode="282445">
        
        <AvailStatusMessage BookingLimit="0" BookingLimitMessageType="SetLimit">
            <StatusApplicationControl InvCode="74959" Start="2020-01-01" End="2020-01-02"/>
        </AvailStatusMessage>
        
        <AvailStatusMessage>
            <StatusApplicationControl InvCode="74959" RatePlanCode="27" Start="2020-01-01" End="2020-01-02"/>
            <LengthsOfStay>
                <LengthOfStay MinMaxMessageType="MinLOS" Time="2" TimeUnit="Day"/>
            </LengthsOfStay>
            <RestrictionStatus MaxAdvancedBookingOffset="P10D" Restriction="Departure"/>
        </AvailStatusMessage>
    </AvailStatusMessages>
</OTA_HotelAvailGetRS>
```

#### <a name="booking-limit-meaning"></a>Meaning of the @BookingLimit Attribute

The value of the `@BookingLimit` attribute represents the total flexible allotment for a 
room, which is not the same as the inventory available to sell.

Please refer to [Get Inventory](/portal/documentation/get-inventory) for more details on this value.

#### <a name="interpretation"></a>Interpretation of <abbr title="Close to Arrival">CTA</abbr> / <abbr title="Close to Departure">CTD</abbr> / Stop-Sell

Due to the way the OTA specification is modeled, there is a particular interpretation 
of the values in the `RestrictionStatus` element that needs to be performed by 
the client.

When processing a `RestrictionStatus` element, the `@Restriction` attribute indicates 
whether CTA or CTD is set, and the `@Status` attribute indicates whether stop-sell 
is set.

Since there is only one `@Restriction` attribute in a `RestrictionStatus` element, 
and there is only one `RestrictionStatus` element in an `AvailStatusMessage` 
element, the API will issue two `AvailStatusMessage` elements when both CTA and CTD 
are set. The second element will only include `StatusApplicationControl` and 
`RestrictionStatus`. Both instances of `RestrictionStatus` will contain
the same value for `@Status`.

Mind that **the semantic when setting restrictions is [different](/portal/documentation/update-avail-restr#interpretation)**.

##### Examples Responses

All the examples set <abbr title="Length of Stay">LOS</abbr> to show how other restrictions work together.

* CTA is set.

```xml
<OTA_HotelAvailGetRS xmlns="http://www.despegar.com/hotels/ota/v1/" Version="v1" CorrelationID="123">
    <Success/>
    <AvailStatusMessages HotelCode="282445">
        <AvailStatusMessage>
            <StatusApplicationControl InvCode="74959" RatePlanCode="27" Start="2020-01-01" End="2020-01-02"/>
            <LengthsOfStay>
                <LengthOfStay MinMaxMessageType="MinLOS" Time="2" TimeUnit="Day"/>
            </LengthsOfStay>
            <RestrictionStatus Restriction="Arrival" Status="Open"/>
        </AvailStatusMessage>
    </AvailStatusMessages>
</OTA_HotelAvailGetRS>
```

* CTA and CTD are set.

```xml
<OTA_HotelAvailGetRS xmlns="http://www.despegar.com/hotels/ota/v1/" Version="v1" CorrelationID="123">
    <Success/>
    <AvailStatusMessages HotelCode="282445">
        <AvailStatusMessage>
            <StatusApplicationControl InvCode="74959" RatePlanCode="27" Start="2020-01-01" End="2020-01-02"/>
            <LengthsOfStay>
                <LengthOfStay MinMaxMessageType="MinLOS" Time="2" TimeUnit="Day"/>
            </LengthsOfStay>
            <RestrictionStatus Restriction="Arrival" Status="Open"/>
        </AvailStatusMessage>
        <AvailStatusMessage>
            <StatusApplicationControl InvCode="74959" RatePlanCode="27" Start="2020-01-01" End="2020-01-02"/>
            <RestrictionStatus Restriction="Departure" Status="Open"/>
        </AvailStatusMessage>
    </AvailStatusMessages>
</OTA_HotelAvailGetRS>
```

* CTA, CTD, and stop-sell are set.

```xml
<OTA_HotelAvailGetRS xmlns="http://www.despegar.com/hotels/ota/v1/" Version="v1" CorrelationID="123">
    <Success/>
    <AvailStatusMessages HotelCode="282445">
        <AvailStatusMessage>
            <StatusApplicationControl InvCode="74959" RatePlanCode="27" Start="2020-01-01" End="2020-01-02"/>
            <LengthsOfStay>
                <LengthOfStay MinMaxMessageType="MinLOS" Time="2" TimeUnit="Day"/>
            </LengthsOfStay>
            <RestrictionStatus Restriction="Arrival" Status="Close"/>
        </AvailStatusMessage>
        <AvailStatusMessage>
            <StatusApplicationControl InvCode="74959" RatePlanCode="27" Start="2020-01-01" End="2020-01-02"/>
            <RestrictionStatus Restriction="Departure" Status="Close"/>
        </AvailStatusMessage>
    </AvailStatusMessages>
</OTA_HotelAvailGetRS>
```

#### Filtering by Room or Rate Plan

The output can be restricted to selected rooms or rate plans.

```xml
<OTA_HotelAvailGetRQ xmlns="http://www.despegar.com/hotels/ota/v1/" Version="1.000">
    <HotelAvailRequests>
        <HotelAvailRequest>
        	<RoomTypeCandidates>
        		<RoomTypeCandidate RoomTypeCode="74961"/>
        	</RoomTypeCandidates>
        	<RatePlanCandidates>
        		<RatePlanCandidate RatePlanCode="27"/>
        	</RatePlanCandidates>
            <HotelRef HotelCode="282445" />
        </HotelAvailRequest>
    </HotelAvailRequests>
</OTA_HotelAvailGetRQ>
```

### Message Detail

#### Input: OTA_HotelAvailGetRQ

| Element                                                    | Number | Description      |
|:-----------------------------------------------------------|:-------|:-----------------|
| OTA_HotelAvailGetRQ                                        |   1    | Root element |
| OTA_ HotelAvailGetRQ / HotelAvailRequests                  |   1    | |
| HotelAvailRequests / HotelAvailRequest                     |  1..n  | |
| HotelAvailRequest / RoomTypeCandidates                     |  0..1  | |
| HotelAvailRequest / RoomTypeCandidates / RoomTypeCandidate |  1..n  | |
| @RoomTypeCode                                              |   1    | Filter results by this room. |
| HotelAvailRequest / RatePlanCandidates                     |  0..1  | |
| HotelAvailRequest / RatePlanCandidates / RatePlanCandidate |  1..n  | |
| @RatePlanCode                                              |   1    | Filter results by this rate plan. |
| HotelAvailRequest / HotelRef                               |  0..1  | |
| @HotelCode                                                 |   1    | The code of the hotel to query the room/rate. |
| HotelAvailRequest / DataRange                              |  0..1  | A date or date range for the search criteria. |
| @Start                                                     |   1    | Data request start date (inclusive). |
| @End                                                       |   1    | Data request end date (exclusive). |

#### Output: OTA_HotelAvailGetRS

| Element                                       | Number | Description      |
|:----------------------------------------------|:-------|:-----------------|
| OTA_HotelAvailGetRS                           |   1    | Root element |
| @Version                                      |   1    | Service version |
| OTA_HotelAvailGetRS / Success                 |  0..1  | It is present if the request has been processed successfully. The error node is not present if this node appears. |
| OTA_HotelAvailGetRS / Errors                  |  0..1  | Contains an error list in case the request was not processed correctly. |
| Errors / Error                                |  1..n  | If there is an error node then there has to exist at least one error node. The element will contain the error text. |
| @Type                                         |   1    | Error type |
| @Code                                         |  0..1  | Error code |
| OTA_HotelAvailGetRS / AvailStatusMessages     |   1    | Contains the room/rate messages. |
| @HotelCode                                    |   1    | The code of the hotel to be queried. |
| AvailStatusMessages / AvailStatusMessage      |  1..n  | Each contains the room/rate. |
| @BookingLimit                                 |  0..1  | Number of inventory units that are available for sale. Flexible quota. |
| AvailStatusMessage / StatusApplicationControl |   1    | |
| @RatePlanCode                                 |   1    | Identifier code of the rate plan. |
| @InvCode                                      |   1    | Room identifier code. |
| @Start                                        |   1    | Data request start date (inclusive).|
| @End                                          |   1    | Data request end date (exclusive).|
| LengthsOfStay / LengthOfStay                  |  0..1  | Used to inform the length of stay. |
| @MinMaxMessageType                            |   1    | Used to indicate the minimum and maximum LOS that applies. Possible values: <ul><li> SetMinLOS: Define the minimum length of stay. </li><li> Define the maximum length of stay. </li></ul>|
| @TimeUnit                                     |   1    | Time unit used to apply this status message to other inventory. Values: year, month, week, day, hour, minute, second. We only use **day**.|
| AvailStatusMessages / RestrictionStatus       |  0..1  | Indicates restrictions like stop-sell, CTA, CTD, and min/max cut-off dates. |
| @MinAdvancedBookingOffset                     |  0..1  | Also known as the minimum cut-off date. This value is **read-only**. |
| @MaxAdvancedBookingOffset                     |  0..1  | Also known as the maximum cut-off date. This value is **read-only**. |
| @Status                                       |   1    | Possible values: <ul><li> Close: Inventory not available for sale. </li><li> Open: Inventory available for sale. </li></ul>This attribute works alone and is independent from `@Restriction` (If its opened or closed).|
| @Restriction                                  |  0..1  | Possible values: <ul><li> Arrival - Applies only for the day of arrival </li><li> Departure - Applies only for the day of departure </li></ul>If this attribute is present, it means that the restriction it states is applied, otherwise it's disabled.|