OTA_HotelAvailRQ

​

Purpose

• 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

<OTA_HotelAvailRQ>

• 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”
• MaxResponses: Limits number of bookable options returned. Default is 1500.

​

Structure - Core Elements

​

POS (Point of Sale)

  <POS>
    <Source>
      <RequestorID Instance="MF002" ID_Context="AxisData" ID="TST1" Type="22"/>
    </Source>
    <Source>
      <RequestorID Type="88" ID="TST1" MessagePassword="TST1password?"/>
    </Source>
  </POS>

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

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

​

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="AMTSES08UI"/>
        </Criterion>
      </HotelSearchCriteria>
    </AvailRequestSegment>

​

InfoSource Attribute

​

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

• Adults: AgeQualifyingCode="10"
• Children: AgeQualifyingCode="8" (must specify age)
• Infants: AgeQualifyingCode="7"
• 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

	<Criterion>
	  <RefPoint CodeContext="Country">Spain</RefPoint>
	  <RefPoint CodeContext="Region">Mallorca</RefPoint>
	</Criterion>

	<Criterion ExactMatch="true">
	  <HotelRef HotelCode="AMTSES08UI"/>
	</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

<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="TST1" Type="22"/>
    </Source>
    <Source>
      <RequestorID Type="88" ID="TST1" MessagePassword="TST1password?"/>
    </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>

​

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