4.4. Inventory: room category information

The Inventory request allows up to four values for the action parameter (depending on the server exposed capabilities):

  • OTA_HotelDescriptiveContentNotif:Inventory indicates the client wishes to define a room category, send its basic description and optionally provide a list of specific rooms for each category (see section Inventory/Basic (push))

  • OTA_HotelDescriptiveInfo:Inventory indicates the client wishes to retrieve the information about room category, basic description and the list of specific rooms (see section Inventory/Basic (pull))

  • OTA_HotelDescriptiveContentNotif:Info indicates the client wishes to send additional descriptive content (see section Inventory/HotelInfo (push))

  • OTA_HotelDescriptiveInfo:Info indicates the client wishes to retrieve the additional descriptive content (see section Inventory/HotelInfo (pull))

4.4.1. Inventory/Basic (push) client request

The parameter request contains an OTA_HotelDescriptiveContentNotifRQ document.

Each document contains one HotelDescriptiveContent element. For the attributes HotelCode and HotelName the rules are the same as for room availability notifications (section 4.1.1). Note that information about only one hotel per message can be transmitted.

Nested inside HotelDescriptiveContent, a FacilityInfo element contains a list of zero or more GuestRoom elements. There are two distinct kinds of GuestRoom elements:

  • the heading one is used to define a room category and its basic description (the category is identified by the attribute Code),

  • the following ones list specific rooms for each category (identified by the attribute Code).

More than one category can be transmitted. That means a category defining sequence of one-heading- GuestRoom-element plus zero or more following- GuestRoom-elements can be repeated for each category.

Sending zero GuestRoom elements (meaning an empty GuestRooms element) will remove all room categories for the given hotel.

Following is the global structure of an example of such a document:

samples/Inventory-OTA_HotelDescriptiveContentNotifRQ.xml - outer part
<OTA_HotelDescriptiveContentNotifRQ
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns="http://www.opentravel.org/OTA/2003/05"
  xsi:schemaLocation="http://www.opentravel.org/OTA/2003/05
                      OTA_HotelDescriptiveContentNotifRQ.xsd"
  Version="8.000">

<HotelDescriptiveContents>
  <HotelDescriptiveContent HotelCode="123" HotelName="Frangart Inn">
    <FacilityInfo>
      <GuestRooms>

        <!-- the heading GuestRoom element is used to define a category
             and its basic description -->

        <GuestRoom Code="DZ" MaxOccupancy="2" MinOccupancy="1" MaxChildOccupancy="1">
          <!-- ... see below ... -->
        </GuestRoom>

        <!-- the follow-up GuestRoom elements list the specific
             rooms in the category -->

        <GuestRoom Code="DZ">
          <TypeRoom RoomID="101"/>
        </GuestRoom>

        <GuestRoom Code="DZ">
          <TypeRoom RoomID="102"/>
        </GuestRoom>

       </GuestRooms>
      </FacilityInfo>
    </HotelDescriptiveContent>
  </HotelDescriptiveContents>

</OTA_HotelDescriptiveContentNotifRQ>

The heading GuestRoom element, used to define a room category and its basic description, contains the following attributes:

  • Code: mandatory, identifies the category.

  • MinOccupancy: mandatory, sets the minimum number of guests allowed for this room category.

  • MaxOccupancy: mandatory, sets the maximum number of guests allowed for this room category.

  • MaxChildOccupancy: optional, must be 0 ≤ MaxChildOccupancy ≤ MaxOccupancy. This attribute can be used to influence the computation of the total cost of the stay in the presence of children (see section 4.5 under "Computing the cost of a stay" for details). Note that this attribute cannot be used to disallow children in a stay. This attribute may only be used if the capability OTA_HotelDescriptiveContentNotif_Inventory_occupancy_children is announced by the server.

  • ID: optional, used for updating room category codes (see remarks at the end of this section)

The heading GuestRoom element also contains the following sub-elements:

  • TypeRoom: mandatory element with the attributes:

    • StandardOccupancy (mandatory),

    • RoomClassificationCode (mandatory) to classify the kind of guest room following the OTA list "Guest Room Info" (GRI) - 42 means just "Room", 13 means "Apartments", "5" means "Pitches", etc…​

    • RoomType (optional) to allow a finer classification of the guest accommodation (see below)

    • Size (optional)

  • Amenities: optional element containing a list of Amenity elements, each indentified by the mandatory attribute RoomAmenityCode following the OTA list "Room Amenity Type" (RMA).

  • MultimediaDescription: one or more elements with an InfoCode attribute with certain values (a subset of the OTA list "Information type" (INF)):

    • exactly one MultimediaDescription element with attribute InfoCode = 25 (Long name) indicating a title must be present,

    • at most one MultimediaDescription element with attribute InfoCode = 1 (Description) may be present and

    • at most one MultimediaDescription element with attribute InfoCode = 23 (Pictures) may be present.

Regarding the optional attribute RoomType, its allowed values are defined by AlpineBits® as follows:

  • For rooms: RoomType value 1 (should only be used when RoomClassificationCode is 42)

  • For apartments: RoomType value 2 (should only be used when RoomClassificationCode is 13)

  • For mobile homes: RoomType value 3 (should only be used when RoomClassificationCode is 13)

  • For bungalows: RoomType value 4 (should only be used when RoomClassificationCode is 13)

  • For holiday homes: RoomType value 5 (should only be used when RoomClassificationCode is 13)

  • For camping grounds (place for vehicles in a camping): RoomType value 6 (should only be used when RoomClassificationCode is 5)

  • For pitches (place for tents in a camping): RoomType value 7 (should only be used when RoomClassificationCode is 5)

  • For camping grounds/pitches (place for either tents or vehicles in a camping): RoomType value 8 (should only be used when RoomClassificationCode is 5)

  • For resting places (beds in shared rooms, like hostels or mountain huts): RoomType value 9 (should only be used when RoomClassificationCode is 42)

Here is an example of such a heading GuestRoom element:

samples/Inventory-OTA_HotelDescriptiveContentNotifRQ.xml - a heading GuestRoom element
<GuestRoom Code="DZ" MaxOccupancy="2" MinOccupancy="1" MaxChildOccupancy="1">

  <!-- RoomClassificationCode = "42" means Room, 13 Apartment, see OTA table GRI -->
  <TypeRoom StandardOccupancy="2" RoomClassificationCode="42"/>

  <Amenities>
    <!-- 26 means Crib, see OTA table RMA -->
    <Amenity RoomAmenityCode="26"/>
  </Amenities>

  <MultimediaDescriptions>

    <MultimediaDescription InfoCode="25">
      <!-- ... -->
    </MultimediaDescription>

    <MultimediaDescription InfoCode="1">
      <!-- ... -->
    </MultimediaDescription>

    <MultimediaDescription InfoCode="23">
      <!-- ... -->
    </MultimediaDescription>

  </MultimediaDescriptions>

</GuestRoom>

The MultimediaDescription elements follow these rules:

  • a MultimediaDescription element with attribute InfoCode = 25 or 1 must contain only a single TextItem element

  • a MultimediaDescription element with attribute InfoCode = 23 contains only ImageItem elements (one or more).

Here is an example:

samples/Inventory-OTA_HotelDescriptiveContentNotifRQ.xml - MultimediaDescription elements
<MultimediaDescriptions>

  <MultimediaDescription InfoCode="25">
    <TextItems>
      <TextItem>
        <Description TextFormat="PlainText" Language="en">
          Double room</Description>
        <Description TextFormat="PlainText" Language="de">
          Doppelzimmer</Description>
        <Description TextFormat="PlainText" Language="it">
          Camera doppia</Description>
      </TextItem>
    </TextItems>
  </MultimediaDescription>

  <MultimediaDescription InfoCode="1">
    <TextItems>
      <TextItem>
        <Description TextFormat="PlainText" Language="en">
          Description of the double room.</Description>
        <Description TextFormat="PlainText" Language="de">
           Doppelzimmer Beschreibung.</Description>
        <Description TextFormat="PlainText" Language="it">
           Descrizione della camera doppia.</Description>
      </TextItem>
    </TextItems>
  </MultimediaDescription>

  <MultimediaDescription InfoCode="23">
    <ImageItems>
      <!-- 6 means guest room, see OTA table PIC -->
      <ImageItem Category="6">
        <ImageFormat CopyrightNotice="Copyright notice 2015">
          <URL>http://www.example.com/image.jpg</URL>
        </ImageFormat>
        <Description TextFormat="PlainText" Language="en">
          Picture of the room</Description>
        <Description TextFormat="PlainText" Language="de">
          Zimmerbild</Description>
        <Description TextFormat="PlainText" Language="it">
          Immagine della stanza</Description>
      </ImageItem>
    </ImageItems>
  </MultimediaDescription>

<MultimediaDescriptions>

TextItems contains a TextItem element, which must contain one or more Description elements, each with the mandatory attributes TextFormat and Language.

The following rules hold:

  • The attribute TextFormat is set to PlainText or HTML and the attribute Language is set to a two-letter lowercase language abbreviation according to ISO 639-1. At most one Text element is allowed for each combination of Language and TextFormat.

  • The presence of a TextItem element with TextFormat set to HTML is intended as rich text alternative of a TextItem element with TextFormat set to PlainText of the same Language and makes the latter mandatory.

  • Please note that an AlpineBits® server is explicitly allowed to filter, shorten or even skip the HTML content, therefore the usage of TextItem elements with TextFormat set to HTML is not recommended but left as an option for implementers that absolutely need it.

ImageItems contains a list of one or more ImageItem elements with mandatory Category attribute following the OTA list "Picture Category Code" (PIC). Typical values are 6 (Guest Room) and 17 (Map) but the whole table is allowed. The ImageItem element contains a single, mandatory ImageFormat element with the optional attribute CopyrightNotice. Inside, a single mandatory element URL, holds the URL where the picture can be retrieved as its value. Zero or more Description elements follow, under the same rules outlined above for descriptions contained in the element TextItem. Images should be processed by the server in the order they are submitted (i.e. the order used to show the pictures the to end users should be consistent with the one sent by the client).

The following GuestRoom element lists all the rooms belonging to a category, as we’ve seen in the first code sample, repeated here:

samples/Inventory-OTA_HotelDescriptiveContentNotifRQ.xml - part showing follow-up GuestRoom elements
        <!-- the follow-up GuestRoom elements list the specific
             rooms in the category -->

        <GuestRoom Code="DZ">
          <TypeRoom RoomID="101"/>
        </GuestRoom>

        <GuestRoom Code="DZ">
          <TypeRoom RoomID="102"/>
        </GuestRoom>

Following GuestRoom elements have a mandatory Code attribute that identifies the category the specific room belongs to. No further attributes are allowed.

They also have a mandatory sub-element TypeRoom with a mandatory attribute RoomID that identifies the specific room. No further elements or attributes are allowed, included (but not limited to) the MultimediaDescription element.

If a server sets the capability OTA_HotelDescriptiveContentNotif_Inventory_use_rooms, a client must send the full list of rooms and the server must store it.

Otherwise, if a server does not set that capability, a client might or might not send the room list. A server that has no use for the room list is then free to discard it upon receiving them, but must do so silently (i.e. without returning errors or warnings).

Some remarks.

Note that AlpineBits® does not support deltas for Inventory/Basic (push) requests. After successfully processing a request, any previously data sent via an Inventory/Basic (push) request (and only the data sent via an Inventory/Basic (push) request) must be removed.

Moreover, all Inventory/HotelInfo, FreeRooms or RatePlans data that refer to any now missing room categories must be considered outdated.

Also note that categories in inventories should refer to physical inventories. They must not be used as logical inventories. For example it is not allowed to introduce an inventory with code suite-x and one withcode suite-x-special-offer for the purpose of modeling two different products from the same inventory (RatePlans will take care of that).

It happens that hotels change room category codes (for whatever reason). It is therefore important that these changes are communicated to the server in order to avoid losing any data linked to the renamed categories. The old code of the room category can be transferred via the attribute ID of the heading GuestRoom elements.

Here is an example:

  <HotelDescriptiveContent HotelCode="123" HotelName="Frangart Inn">
    <FacilityInfo>
      <GuestRooms>

        <!-- "single", formerly known as "EZ" -->

        <GuestRoom Code="single" MaxOccupancy="2" MinOccupancy="1" ID="EZ">
          <TypeRoom StandardOccupancy="2" RoomClassificationCode="42"/>
        </GuestRoom>

        <!-- "double", formerly known as "DZ" -->

        <GuestRoom Code="double" MaxOccupancy="2" MinOccupancy="1" ID="DZ">
          <TypeRoom StandardOccupancy="2" RoomClassificationCode="42"/>
        </GuestRoom>

       </GuestRooms>
      </FacilityInfo>
    </HotelDescriptiveContent>

The server will first look for a category "single". If that’s found, the server will silently ignore the ID attribute and replace the data it had on record for "single".

If "single" is not found, the server will look for a category "EZ". If that’s found, the server must rename it to "single". If "EZ" is not found either, the server will just store the new category "single".

This makes sure that "EZ" is renamed to "single", without causing problems if "EZ" wasn’t known in the first place or in case the renaming has already happened.

The same procedure is to be applied for "DZ" renamed to "double".

4.4.2. Inventory/Basic (push) server response

The server will send a response indicating the outcome of the request. The response is a OTA_HotelDescriptiveContentNotifRS document. Any of the four possible AlpineBits® server response outcomes (success, advisory, warning or error) are allowed.

See Appendix A for details.

4.4.3. Inventory/Basic (pull) client request

The parameter request contains an OTA_HotelDescriptiveInfoRQ document.

Analogous to the Inventory/Basic (push) request, a client can send a pull request to query the basic data the server has stored about a hotel.

Here is such a client request:

samples/Inventory-OTA_HotelDescriptiveInfoRQ-basicpullRQ.xml
<OTA_HotelDescriptiveInfoRQ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                            xmlns="http://www.opentravel.org/OTA/2003/05"
                            Version="3.000">

    <HotelDescriptiveInfos>
        <HotelDescriptiveInfo HotelCode="123" HotelName="Frangart Inn"/>
    </HotelDescriptiveInfos>

</OTA_HotelDescriptiveInfoRQ>

As expected, the document must contain one HotelDescriptiveInfo element with attributes HotelCode and HotelName that follow the same rules as for room availability notifications (section 4.1.1). Again, information about only one hotel per message can be queried.

Please note that the content of the XML message is identical, both for Inventory/Basic (pull) and Inventory/HotelInfo (pull), but the action is used by the server to distinguish the two requests.

4.4.4. Inventory/Basic (pull) server response

The server will send a response indicating the outcome of the request. The response is a OTA_HotelDescriptiveInfoRS document. Any of the four possible AlpineBits® server response outcomes (success, advisory, warning or error) are allowed. See Appendix A for details.

In case of a successful outcome, the Success element is followed by a HotelDescriptiveContent element with the information about the hotel.

Here is such a server response. The complete file is in the developer kit.

samples/Inventory-OTA_HotelDescriptiveInfoRS-basicpullRS.xml - outer part
<OTA_HotelDescriptiveInfoRS xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                            xmlns="http://www.opentravel.org/OTA/2003/05"
                            Version="3.000">

  <Success/>
  <HotelDescriptiveContents>
    <HotelDescriptiveContent HotelCode="123" HotelName="Frangart Inn">

    <!-- ... see file in development kit ... -->

    </HotelDescriptiveContents>
  </HotelDescriptiveContents>

</OTA_HotelDescriptiveInfoRS>

4.4.5. Inventory/HotelInfo (push) client request

The parameter request contains an OTA_HotelDescriptiveContentNotifRQ document.

The purpose of this request is twofold:

  1. A given client could have information that is technically fundamental (data transmitted via Inventory/Basic (push)), but may lack additional content such as inspiring pictures of the rooms. The present Inventory/HotelInfo (push) request introduces the possibility for the server to accept additional descriptive content from one or multiple clients, while still having a single reputable source for the basic information. (Technically speaking a server may accept basic data from multiple clients, but it is highly discouraged to do so to prevent inconsistencies.)

  2. Moreover many AlpineBits® members have expressed the need to transmit all kind of additional master data about hotels, such as (but not limited to):

    • hotel type / category

    • address info

    • contact info

    • short/long descriptions

    • logos, seasonal pictures, gallery pictures

    • hotel amenities

    • check-in / check-out times

    • accepted payment methods / deposit

    • ratings info

    • facilities info

Using the Inventory/HotelInfo (push) request it is therefore possible to send additional data that is allowed by OTA under the HotelDescriptiveContent element.

Each message must contain one HotelDescriptiveContent element with attributes HotelCode and HotelName that follow the same rules as for room availability notifications (section 4.1.1). Again, information about only one hotel per message can be transmitted.

AlpineBits® allows the following child-element right below HotelDescriptiveContent:

  • HotelInfo: can hold any content allowed by OTA,

  • FacilityInfo: is a subset of the FacilityInfo in Inventory/Basic (push) messages:

    • GuestRoom elements may only have a Code attribute and may only contain MultimediaDescription sub-elements;

    • the MultimediaDescription elements must not have the InfoCode attribute and just contain a single ImageItems element with a list of ImageItem elements

  • Policies: can hold any content allowed by OTA,

  • AffiliationInfo: can hold any content allowed by OTA,

  • ContactInfos: is used to transmit URIs where the lodging structure has a presence (like social networks, review aggregators, etc.) and is defined below.

The restriction on FacilityInfo is meant to make sure that Inventory/HotelInfo (push) message are only used to send additional descriptive content for room categories. It is supposed to be used in addition (not instead of) Inventory/Basic (push).

ContactInfos: Point of presence of the lodging structure

Given the rising importance of social networks, reviews aggregator websites and chat/messaging platforms, the following use case has been defined in AlpineBits® for the ContactInfos element and its descendants:

  • at most one ContactInfo may optionally be specified, with the attribute Location that must have value 6 ("Hotel direct contact" according to CON codelist)

  • inside this element, a single URLs must be present, containing one or more URL

  • each URL must have the ID attribute specified as described below, the content of the element must be a valid URI

  • despite its name, the content of URL may be any URI, so besides http(s) urls, also other schemes might be specified. URNs are allowed as well and in this case the schema must be id.

AlpineBits® defines some values for the ID attribute that should be recognized by servers and clients:

  • TRUSTYOU: for the lodging structure’s presence on trustyou.com

  • TRIPADVISOR: for the lodging structure’s presence on tripadvisor.com

  • TWITTER: for the lodging structure’s presence on twitter.com

  • FACEBOOK: for the lodging structure’s presence on facebook.com

  • INSTAGRAM: for the lodging structure’s presence on instagram.com

  • YOUTUBE: for the lodging structure’s presence on youtube.com

Partners are allowed to define further values but the value of the attribute must be all uppercase.

The following example shows a possible use case of this message:

<ContactInfos>
	<ContactInfo Location="6">
		<URLs>
			<URL ID="FACEBOOK">https://www.facebook.com/alpinebits/</URL>
			<URL ID="TWITTER">https://twitter.com/hashtag/alpinebits</URL>
			<URL ID="TRUSTYOU">id:12345678-1nvalid</URL>
			<URL ID="YOUTUBE">https://www.youtube.com/user/AlpineBits</URL>
		</URLs>
	</ContactInfo>
</ContactInfos>

Given the somewhat experimental nature of the Inventory/HotelInfo (push) request type, future versions of AlpineBits® might further restrict or clarify the acceptable sub-elements of HotelDescriptiveContent.

The development kit contains an example in the samples folder that documents only the FacilityInfo element; a non-normative example of a possible usage of all the other nodes mentioned above is available in the samples-contrib folder and is not fully copied here due to the limited space:

samples/Inventory-OTA_HotelDescriptiveContentNotifRQ-hotelinfo.xml - outer part
<OTA_HotelDescriptiveContentNotifRQ
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns="http://www.opentravel.org/OTA/2003/05"
  xsi:schemaLocation="http://www.opentravel.org/OTA/2003/05
                      OTA_HotelDescriptiveContentNotifRQ.xsd"
  Version="8.000">

  <HotelDescriptiveContents>
    <HotelDescriptiveContent HotelCode="123" HotelName="Frangart Inn" >

      <!-- ... see file in development kit ... -->

    </HotelDescriptiveContent>
  </HotelDescriptiveContents>

</OTA_HotelDescriptiveContentNotifRQ>

Note that AlpineBits® does not support deltas for Inventory/HotelInfo (push) requests. Data sent in a Inventory/HotelInfo (push) request replaces all data sent in a previous Inventory/HotelInfo (push) request (although the server will of course not replace any Inventory/Basic (push) data it has on record). If multiple clients are providing Inventory/HotelInfo (push) data, it is up to the server implementation to guarantee the integrity of the data.

If a server receives Inventory/HotelInfo (push) data with additional descriptive content regarding unknown room categories it must react accordingly (i.e. return a warning). However, a message that has additional descriptive regarding only some of the categories the server has on record, will not trigger a warning response. It is very well possible that some room categories do not have additional descriptive content.

4.4.6. Inventory/HotelInfo (push) server response

The server will send a response indicating the outcome of the request. The response is a OTA_HotelDescriptiveContentNotifRS document. Any of the four possible AlpineBits® server response outcomes (success, advisory, warning or error) are allowed.

See Appendix A for details.

4.4.7. Inventory/HotelInfo (pull) client request

The parameter request contains an OTA_HotelDescriptiveInfoRQ document.

Analogous to the Inventory/HotelInfo (push) request, a client can send a pull request to query the additional data the server has stored about a hotel.

Here is such a client request:

samples/Inventory-OTA_HotelDescriptiveInfoRQ-hotelinfo.xml
<OTA_HotelDescriptiveInfoRQ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                            xmlns="http://www.opentravel.org/OTA/2003/05"
                            Version="3.000">

    <HotelDescriptiveInfos>
        <HotelDescriptiveInfo HotelCode="123" HotelName="Frangart Inn"/>
    </HotelDescriptiveInfos>

</OTA_HotelDescriptiveInfoRQ>

As expected, the document must contain one HotelDescriptiveInfo element with attributes HotelCode and HotelName that follow the same rules as for room availability notifications (section 4.1.1). Again, information about only one hotel per message can be queried.

Please note that the content of the XML message is identical both for Inventory/Basic (pull) and Inventory/HotelInfo (pull), but the action is different and used to distinguish the two requests.

4.4.8. Inventory/HotelInfo (pull) server response

The server will send a response indicating the outcome of the request. The response is a OTA_HotelDescriptiveInfoRS document. Any of the four possible AlpineBits® server response outcomes (success, advisory, warning or error) are allowed. See Appendix A for details.

In case of a successful outcome, the Success element is followed by a HotelDescriptiveContent element with the information about the hotel.

The development kit contains an example in the samples folder that documents only the FacilityInfo element; a non-normative example of a possible usage of all the other nodes mentioned above is available in the samples-contrib folder and is not fully copied here due to the limited space:

samples/Inventory-OTA_HotelDescriptiveInfoRS-hotelinfo.xml - outer part
<OTA_HotelDescriptiveInfoRS xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                            xmlns="http://www.opentravel.org/OTA/2003/05"
                            Version="3.000">

  <Success/>
  <HotelDescriptiveContents>
    <HotelDescriptiveContent HotelCode="123" HotelName="Frangart Inn">

    <!-- ... see file in development kit ... -->

    </HotelDescriptiveContents>
  </HotelDescriptiveContents>

</OTA_HotelDescriptiveInfoRS>

4.4.9. Implementation tips and best practice

Please note that section 4.4 has been changed multiple times since its creation. See appendix C for compatibility information.