> ## Documentation Index
> Fetch the complete documentation index at: https://docs.axisdata.net/llms.txt
> Use this file to discover all available pages before exploring further.

# OTA_HotelAvailRQ

The OTA\_HotelAvailRQ (Hotel Availability Request) is an XML message used in the hospitality industry to request hotel availability information. It is part of the OpenTravel Alliance (OTA) specification, which provides standardized messaging formats for travel-related transactions.

<Tip>Already know OTA messages? Jump straight into testing.</Tip>

<Card title="OTA_HotelAvailRQ API call" icon="magnifying-glass" href="/api-reference/endpoint/hotel/availability" arrow="true" horizontal>
  Skip & Hit the Playground.
</Card>

## Purpose

This message is used to:

* Search for available hotel rooms based on specific criteria.
* Request rate information for available accommodations.
* Query inventory across multiple properties or a single hotel.
* Filter results based on guest requirements and preferences.

## Structure - Root Element

```xml theme={null}
<OTA_HotelAvailRQ>
```

**Key Attributes:**

* `Version`: Specification version (e.g., "1.0")
* `EchoToken`: Unique identifier for tracking request/response pairs
* `PrimaryLangID`: Primary language code (ISO 639)
* `xmlns`: "[http://www.opentravel.org/OTA/2003/05](http://www.opentravel.org/OTA/2003/05)"
* MaxResponses: Limits number of bookable options returned. Default is 1500.

## Structure - Core Elements

### POS (Point of Sale)

Identifies the requesting party and contains credentials. Check [Access to our Systems](../authentication/access#partner-identification)

```xml theme={null}
  <POS>
    <Source>
      <RequestorID Instance="MF002" ID_Context="AxisData" ID="TEST" Type="22"/>
    </Source>
    <Source>
      <RequestorID Type="88" ID="TEST" MessagePassword="testpass"/>
    </Source>
  </POS>
```

The `Instance` attribute value in the `RequestorID` node filters the search results:

**Basic Filters**

| Switch  | Behavior                                                                              |
| :------ | :------------------------------------------------------------------------------------ |
| `MF0x2` | Returns only the **cheapest room/board/rateplan** per hotel                           |
| `MF0x1` | Returns cheapest **contracting group** option (e.g., OWN1)                            |
| `MF0x3` | Returns **4 refund types**: fully refundable, non-refundable, semi-flexible, flexible |
| `MF0x4` | Returns **2 refund types**: fully refundable + cheapest of the other three            |
| `MF0xx` | Returns **all available combinations** (e.g., MF005)                                  |

**Other Filters**

`MF2xx` – Flexible Date Search:

* Search over a period (e.g., 3 months) for a fixed stay duration.
* Use `Duration="P7D"` and `StartDateWindow DOW="x"` to restrict arrival days.

`MF1xx` – Calendar View:

* Returns cheapest price per arrival date for a hotel.
* Can be restricted by DOW (e.g., only Fridays → DOW = 16).

### AvailRequestSegments

Container for one or more availability request segments.

```xml theme={null}
    <AvailRequestSegment InfoSource="12">
      <StayDateRange End="2026-07-24" Start="2026-07-17"/>
      <RoomStayCandidates>
        <RoomStayCandidate>
          <GuestCounts>
            <GuestCount Age="30" Count="2" AgeQualifyingCode="10"/>
          </GuestCounts>
       </RoomStayCandidate>
      </RoomStayCandidates>
      <HotelSearchCriteria>
        <Criterion ExactMatch="true">
          <HotelRef HotelCode="AESPMI5L46"/>
        </Criterion>
      </HotelSearchCriteria>
    </AvailRequestSegment>
```

#### InfoSource Attribute

Controls the enrichment of the response.

| Value  | Enrichment Type           |
| :----- | :------------------------ |
| `0`    | No enrichment             |
| `1`    | HotelStays only           |
| `2`    | Areas only                |
| `3`    | Amenities only            |
| `4`    | RoomDescription only      |
| `5`    | BoardDescription only     |
| `1234` | Full enrichment (default) |

#### StayDateRange Element

* `Start`: Check-in date (YYYY-MM-DD)
* `End`: Check-out date (YYYY-MM-DD)
* `Duration`: Used in flexible searches and calendar view (e.g., "P3N" for 3 nights)
* `StayDateRange/StartDateWindow` -> `DOW`: Restrict arrival days (e.g "Mon")

#### RoomStayCandidate Element

Defines Guest requirements into the `GuestCount` element, following these rules:

* **Adults**: `AgeQualifyingCode="10"`
* **Children**: `AgeQualifyingCode="8"` (must specify age)
* **Infants**: `AgeQualifyingCode="7"` (must specify age)
* **Conversion Logic**:
  * Children exceeding max age → treated as adults
  * Infants exceeding min child age → treated as children
  * Same logic applies in both search and booking requests

#### Criterion Element

It can be used to receive results by areas or per hotel exact matching.

**Area Search**

```xml theme={null}
	<Criterion>
	  <RefPoint CodeContext="Country">Spain</RefPoint>
	  <RefPoint CodeContext="Region">Mallorca</RefPoint>
	</Criterion>
```

Country and Region need to be included. Multiple resorts can be included in one request.

You can receive a full list of Areas with OTA\_HotelAvailRQ, see [Complete examples](#complete-examples) "Area List".

**Hotel Search**

```xml theme={null}
	<Criterion ExactMatch="true">
	  <HotelRef HotelCode="AESPMI5L46"/>
	</Criterion>
```

## Additional Features

### Multi-Room Logic

* Up to **5 rooms** per request
* Each room candidate is matched to available rooms
* Remaining units tracked via `NumberOfUnits`
* Combinations must be validated client-side based on availability
* If no suitable room is found for a candidate, a warning is returned

### Search by Hotel Name

* Minimum 3 characters required
* Returns hotels with matching names

### Upfront Filtering

* Filters can be applied before search:
  * Board type (`MealPlanCodes`)
  * Room type (`RoomClassificationCode`)
  * Star rating (`Award Rating`)
  * Specific room code (`RoomType`)

## Complete Examples

<CodeGroup>
  ```xml Location expandable theme={null}
  <OTA_HotelAvailRQ xmlns="http://www.opentravel.org/OTA/2003/05" MaxResponses="200" EchoToken="1" Version="2008.1">
    <POS>
      <Source>
        <RequestorID Instance="MF002" ID_Context="AxisData" ID="TEST" Type="22"/>
      </Source>
      <Source>
        <RequestorID Type="88" ID="TEST" MessagePassword="testpass"/>
      </Source>
    </POS>
    <AvailRequestSegments>
      <AvailRequestSegment InfoSource="12">
        <StayDateRange End="2026-07-24" Start="2026-07-17"/>
        <RoomStayCandidates>
          <RoomStayCandidate>
            <GuestCounts>
              <GuestCount Count="2" AgeQualifyingCode="10"/>
            </GuestCounts>
          </RoomStayCandidate>
        </RoomStayCandidates>
        <HotelSearchCriteria>
          <Criterion>
            <RefPoint CodeContext="Country">Spain</RefPoint>
            <RefPoint CodeContext="Region">Mallorca</RefPoint>
          </Criterion>
        </HotelSearchCriteria>
      </AvailRequestSegment>
    </AvailRequestSegments>
  </OTA_HotelAvailRQ>
  ```

  ```xml Hotel expandable  theme={null}
  <OTA_HotelAvailRQ xmlns="http://www.opentravel.org/OTA/2003/05" MaxResponses="200" Version="2008.1">
    <POS>
      <Source>
        <RequestorID Instance="MF005" ID_Context="AxisData" ID="TEST" Type="22"/>
      </Source>
      <Source>
        <RequestorID Type="88" ID="TEST" MessagePassword="testpass"/>
      </Source>
    </POS>
    <AvailRequestSegments>
      <AvailRequestSegment InfoSource="12">
        <StayDateRange End="2026-07-24" Start="2026-07-17"/>
        <RoomStayCandidates>
          <RoomStayCandidate>
            <GuestCounts>
              <GuestCount Age="30" Count="2" AgeQualifyingCode="10"/>
            </GuestCounts>
         </RoomStayCandidate>
        </RoomStayCandidates>
        <HotelSearchCriteria>
          <Criterion ExactMatch="true">
            <HotelRef HotelCode="AESPMI5L46"/>
          </Criterion>
        </HotelSearchCriteria>
      </AvailRequestSegment>
    </AvailRequestSegments>
  </OTA_HotelAvailRQ>
  ```

  ```xml Hotel List expandable  theme={null}
  <OTA_HotelAvailRQ xmlns="http://www.opentravel.org/OTA/2003/05" MaxResponses="200" Version="2008.1">
    <POS>
      <Source>
        <RequestorID Instance="MF005" ID_Context="AxisData" ID="TEST" Type="22"/>
      </Source>
      <Source>
        <RequestorID Type="88" ID="TEST" MessagePassword="testpass"/>
      </Source>
    </POS>
    <AvailRequestSegments>
      <AvailRequestSegment InfoSource="12">
        <StayDateRange End="2026-07-24" Start="2026-07-17"/>
        <RoomStayCandidates>
          <RoomStayCandidate>
            <GuestCounts>
              <GuestCount Age="30" Count="2" AgeQualifyingCode="10"/>
            </GuestCounts>
          </RoomStayCandidate>
        </RoomStayCandidates>
        <HotelSearchCriteria>
          <Criterion ExactMatch="true">
            <HotelRef HotelCode="AESPMI5L46"/>
          </Criterion>
        </HotelSearchCriteria>
      </AvailRequestSegment>
      <AvailRequestSegment InfoSource="12">
        <StayDateRange End="2026-07-24" Start="2026-07-17"/>
        <RoomStayCandidates>
          <RoomStayCandidate>
            <GuestCounts>
              <GuestCount Age="30" Count="2" AgeQualifyingCode="10"/>
            </GuestCounts>
          </RoomStayCandidate>
        </RoomStayCandidates>
        <HotelSearchCriteria>
          <Criterion ExactMatch="true">
            <HotelRef HotelCode="AESPMI1234"/>
          </Criterion>
        </HotelSearchCriteria>
      </AvailRequestSegment>
      <AvailRequestSegment InfoSource="12">
        <StayDateRange End="2026-07-24" Start="2026-07-17"/>
        <RoomStayCandidates>
          <RoomStayCandidate>
            <GuestCounts>
              <GuestCount Age="30" Count="2" AgeQualifyingCode="10"/>
            </GuestCounts>
          </RoomStayCandidate>
        </RoomStayCandidates>
        <HotelSearchCriteria>
          <Criterion ExactMatch="true">
            <HotelRef HotelCode="AESPMI5678"/>
          </Criterion>
        </HotelSearchCriteria>
      </AvailRequestSegment>
    </AvailRequestSegments>
  </OTA_HotelAvailRQ>
  ```

  ```xml Efficient List expandable  theme={null}
  <OTA_HotelAvailRQ xmlns="http://www.opentravel.org/OTA/2003/05" MaxResponses="200" Version="2008.1">
    <POS>
      <Source>
        <RequestorID Instance="MF002" ID_Context="AxisData" ID="TEST" Type="22"/>
      </Source>
      <Source>
        <RequestorID Type="88" ID="TEST" MessagePassword="testpass"/>
      </Source>
    </POS>
    <AvailRequestSegments>
      <AvailRequestSegment InfoSource="12">
        <StayDateRange End="2026-07-24" Start="2026-07-17"/>
        <RoomStayCandidates>
          <RoomStayCandidate>
            <GuestCounts>
              <GuestCount Age="30" Count="2" AgeQualifyingCode="10"/>
  		  </GuestCounts>
          </RoomStayCandidate>
        </RoomStayCandidates>
        <HotelSearchCriteria>
          <Criterion ExactMatch="true">
            <HotelRef HotelCode="AMTSTR1UQ4"/>
            <HotelRef HotelCode="AMTSTR139E"/>
            <HotelRef HotelCode="AMTSTR13D0"/>
          </Criterion>
        </HotelSearchCriteria>
      </AvailRequestSegment>
    </AvailRequestSegments>
  </OTA_HotelAvailRQ>
  ```

  ```xml Multiroom expandable  theme={null}
  <OTA_HotelAvailRQ xmlns="http://www.opentravel.org/OTA/2003/05" MaxResponses="200" Version="2008.1">
    <POS>
      <Source>
        <RequestorID Instance="MF002" ID_Context="AxisData" ID="TEST" Type="22"/>
      </Source>
      <Source>
        <RequestorID Type="88" ID="TEST" MessagePassword="testpass"/>
      </Source>
    </POS>
    <AvailRequestSegments>
      <AvailRequestSegment InfoSource="0">
        <StayDateRange End="2026-07-24" Start="2026-07-17"/>
        <RoomStayCandidates>
          <RoomStayCandidate Quantity="1" RPH="111">
            <GuestCounts>
              <GuestCount AgeQualifyingCode="10" Count="1"/>
            </GuestCounts>
          </RoomStayCandidate>
          <RoomStayCandidate Quantity="1" RPH="222">
            <GuestCounts>
              <GuestCount AgeQualifyingCode="10" Count="2"/>
            </GuestCounts>
          </RoomStayCandidate>
        </RoomStayCandidates>
        <HotelSearchCriteria>
          <Criterion ExactMatch="true">
            <HotelRef HotelCode="AESPMI5L46"/>
          </Criterion>
        </HotelSearchCriteria>
      </AvailRequestSegment>
    </AvailRequestSegments>
  </OTA_HotelAvailRQ>
  ```

  ```xml CalendarView expandable  theme={null}
  <OTA_HotelAvailRQ xmlns="http://www.opentravel.org/OTA/2003/05" MaxResponses="200" Version="2008.1">
    <POS>
      <Source>
        <RequestorID Instance="MF102" ID_Context="AxisData" ID="TEST " Type="22"/>
      </Source>
      <Source>
        <RequestorID Type="88" ID="TEST" MessagePassword="testpass"/>
      </Source>
    </POS>
    <AvailRequestSegments>
      <AvailRequestSegment InfoSource="0">
        <StayDateRange End="2026-07-31" Start="2026-07-01" Duration="P7D">
          <StartDateWindow DOW="Mon"/>
        </StayDateRange>
        <RoomStayCandidates>
          <RoomStayCandidate RPH="1">
            <GuestCounts>
              <GuestCount Count="2" AgeQualifyingCode="10"/>
            </GuestCounts>
          </RoomStayCandidate>
          <RoomStayCandidate RPH="2">
            <GuestCounts>
              <GuestCount Count="1" AgeQualifyingCode="8"/>
            </GuestCounts>
          </RoomStayCandidate>
        </RoomStayCandidates>
        <HotelSearchCriteria>
          <Criterion ExactMatch = "true">
              <HotelRef HotelCode = "AESPMI5L46"></HotelRef>
          </Criterion>
        </HotelSearchCriteria>
      </AvailRequestSegment>
    </AvailRequestSegments>
  </OTA_HotelAvailRQ>
  ```

  ```xml Areas expandable  theme={null}
  <OTA_HotelAvailRQ xmlns="http://www.opentravel.org/OTA/2003/05" Version="2008.1">
    <POS>
      <Source>
        <RequestorID Instance="MF005" ID_Context="AxisData" ID="TEST" Type="22"/>
      </Source>
      <Source>
        <RequestorID Type="88" ID="TEST" MessagePassword="testpass"/>
      </Source>
    </POS>
    <AvailRequestSegments>
      <AvailRequestSegment ResponseType="AreaList"/>
    </AvailRequestSegments>
  </OTA_HotelAvailRQ>
  ```
</CodeGroup>

## Common Use Cases

* **Destination Search Request**: Searches hotels based on geographical definitions like country and region.
* **Hotel Search Request**: Queries availability for a specific hotel using its unique code.
* **Hotel List Request**: Searches availability for a list of hotels, often used in mapped or curated portfolios.
* **Efficient Hotel List Request**: Optimized version of hotel list search for performance and reduced data volume.
* **Multi-Room Search Request**: Allows querying availability for multiple rooms in a single request, with occupancy and quantity details.
* **Calendar View Request**: Returns the cheapest price per arrival date for a given hotel or destination over a time range and a defined length of stay.
* **Area List Request**: Retrieves available geographical areas based on the distributor's portfolio.

## Best Practices

1. **Always include EchoToken** - Essential for matching requests with responses.
2. **Specify TimeStamp** - Helps with debugging and tracking.
3. **Use ISO date formats** - YYYY-MM-DD for dates.
4. **Include guest counts** - Ensures accurate availability and pricing.
5. **Validate hotel codes** - Confirm codes before sending requests.
6. **Handle multiple rooms** - Use Quantity attribute when booking multiple rooms.
7. **Time Zones**: Be aware that timestamps should include timezone information
8. **Error Handling**: Implement proper error handling for the response messages

## Playground

<Card title="OTA_HotelAvailRQ API call" icon="magnifying-glass" href="/api-reference/endpoint/hotel/availability" arrow="true" horizontal>
  Try our API playground in real time.
</Card>

<Tip>Use the desired request at the playground and receive responses from our test environment API!  </Tip>