Search Special Offer

All requests will need to be sent in a SYNCHRONOUS mode; any requests send in an ASYNCHRONOUS mode will return an error.

The Search Special Offer provides the client with static data relating to any special offers that might be available for various periods and properties. The API will provide a list of these offers held within the GTA system.

This search can be used by clients on Participation Levels 0.

Example XML Search Special Offer Request

The XML message below gives a sample of the expected elements needed by the API to execute a Search Special Offer Request for hotels.

 

<?xml version="1.0" encoding="UTF-8"?>
<Request>
  <Source>
<RequestorID Client="123456" EMailAddress="clientName@client.co.uk" Password="clientPassword" />
    <RequestorPreferences Language="en">
		  <RequestMode>SYNCHRONOUS</RequestMode>
    </RequestorPreferences>
  </Source>
	<RequestDetails>
		<SearchSpecialOfferRequest ItemType="hotel" >
       <PassengerNationality>GB</PassengerNationality>
       <Offer>FNT</Offer>
       <Country>IT</Country>
       <City>ROM</City>
       <Item>AMB</Item>
       <TravelDates>
          <FromDate>2006-06-01</FromDate>
          <ToDate>2006-06-30</ToDate>
       </TravelDates>
<EffectiveDate>2006-05-01</EffectiveDate>
     </SearchSpecialOfferRequest>	
   </RequestDetails>
</Request>

Source parameters

Please refer to the API Architecture document.

Search Special Offer attributes/parameters

A Search Special Offer request can contain optional attributes/parameters to filter the Special Offers  returned.  The following lists the attributes/parameters that can be specified: -

Attribute

Description

ItemType

Mandatory. Identifies the type of item being processed. Currently only “hotel” is available.

 

Parameter

Description

PassengerNationality

ISO 3166 format, 2 letters

Mandatory. Used to determine the country of residence of the passenger.

Offer

Optional. Used to specify the offer code for which the information is required.

Country

ISO 3166 format, 2 letters

Mandatory if city parameter is not specified. Used to specify the country for which destination the information is required. 

City

Mandatory if country parameter is not specified. Used to specify the GTA city code for the item.

Item

Optional. Used to specify the GTA code for the item.

TravelDates

Optional. Used to specify the travel dates.

  • FromDate – The start date for the range
  • ToDate – the end date of the range

EffectiveDate

Optional. Used to specify the effective dates (creation date of the booking).

Example XML Search Special Offer response

The XML message below gives a sample of that given by the API in response to a Search Special Offers Request.

 

<?xml version="1.0" encoding="UTF-8"?>
<Response ResponseReference="REF_8-1147434504577">
    <ResponseDetails Language="en">
        <SearchSpecialOfferResponse ItemType="hotel">
            <ItemSpecialOffer>
                 <City Code="MIL"><![CDATA[Milan]]></City>
                 <Item Code="ALE"><![CDATA[ALEXANDER]]></Item>
                 <SpecialOffers>
                     <SpecialOffer>
                         <Offer Code="FNT"><![CDATA[Free Night(s)]]></Offer>
                         <TravelDates>
                             <FromDate>2006-05-30</FromDate>
                             <ToDate>2006-08-30</ToDate>
                         </TravelDates>
                         <OfferType>A</OfferType>
                         <EffectiveDates>
                             <FromDate>2006-04-25</FromDate>
                             <ToDate>9999-12-31</ToDate>
                         </EffectiveDates>
                         <StayForNights>3</StayForNights>
                         <PayForNights>2</PayForNights>
                         <DiscountPercentage>0</DiscountPercentage>
                         <MaximumNightsFree>999</MaximumNightsFree>
                         <AllowedArrivalDates>1234567</AllowedArrivalDates>
                         <ValidStayDates>1234567</ValidStayDates>
                         <ApplicableOfferNights>1234567</ApplicableOfferNights>
                      </SpecialOffer>
                      <SpecialOffer>
                          <Offer Code="FNT"><![CDATA[Free Night(s)]]></Offer>
                          <TravelDates>
                             <FromDate>2006-04-10</FromDate>
                             <ToDate>2006-05-30</ToDate>
                          </TravelDates>
                          <OfferType>I</OfferType>
                          <EffectiveDates>
                             <FromDate>2006-04-06</FromDate>
                             <ToDate>9999-12-31</ToDate>
                          </EffectiveDates>

 

Table 1. Search Special Offer Response – flat structure (Participation Level 0).

 

<?xml version="1.0" encoding="UTF-8"?>
<Response ResponseReference="REF_8-1147434504577">
    <ResponseDetails Language="en">
        <SearchSpecialOfferResponse ItemType="hotel">
            <ItemSpecialOffer>
                 <City Code="MIL"><![CDATA[Milan]]></City>
                 <Item Code="ALE"><![CDATA[ALEXANDER]]></Item>
                   <RoomCategories>
                    <RoomCategory Id="002:918:30621:S30802:47511:148755”>
                        <Description><![CDATA[Standard Triple]]></Description>
                     <SpecialOffers>
                     <SpecialOffer>
                         <Offer Code="FNT"><![CDATA[Free Night(s)]]></Offer>
                         <TravelDates>
                             <FromDate>2006-05-30</FromDate>
                             <ToDate>2006-08-30</ToDate>
                         </TravelDates>
                         <OfferType>A</OfferType>
                         <EffectiveDates>
                             <FromDate>2006-04-25</FromDate>
                             <ToDate>9999-12-31</ToDate>
                         </EffectiveDates>
                         <StayForNights>3</StayForNights>
                         <PayForNights>2</PayForNights>
                         <DiscountPercentage>0</DiscountPercentage>
                         <MaximumNightsFree>999</MaximumNightsFree>
                         <AllowedArrivalDates>1234567</AllowedArrivalDates>
                         <ValidStayDates>1234567</ValidStayDates>
                         <ApplicableOfferNights>1234567</ApplicableOfferNights>
                      </SpecialOffer>
                       </SpecialOffers>
                    </RoomCategory>
                   <RoomCategory Id="002:918:30621:S30802:47511:148754”>
                        <Description><![CDATA[Standard Double]]></Description>
                           <SpecialOffers>
                      <SpecialOffer>
                          <Offer Code="FNT"><![CDATA[Free Night(s)]]></Offer>
                          <TravelDates>
                             <FromDate>2006-04-10</FromDate>
                             <ToDate>2006-05-30</ToDate>
                          </TravelDates>
                          <OfferType>I</OfferType>
                          <EffectiveDates>
                             <FromDate>2006-04-06</FromDate>
                             <ToDate>9999-12-31</ToDate>
                          </EffectiveDates>
                          <StayForNights>5</StayForNights>
                          <PayForNights>4</PayForNights>
                          <DiscountPercentage>0</DiscountPercentage>
                          <MaximumNightsFree>1</MaximumNightsFree>
                          <AllowedArrivalDates>1234567</AllowedArrivalDates>
                          <ValidStayDates>1234567</ValidStayDates>
                          <ApplicableOfferNights>1234567</ApplicableOfferNights>
                          <ClosedDates>
                             <ClosedDate>2006-07-01</ClosedDate>
                             <ClosedDate>2006-05-30</ClosedDate>
                          </ClosedDates>
                       </SpecialOffer>
                    </SpecialOffers>
                   </RoomCategory>
                </RoomCategories>
                </ItemSpecialOffer>
            </SearchSpecialOfferResponse>
    </ResponseDetails>
</Response>

 

Table 2. Search Special Offer Response – With room categories (Participation Level 2 or above).

Search Special Offer response parameters

Attribute

Description

ItemType

Identifies the type of item being processed. Currently only “hotel” is available.

A Search Special Offer response will return the following for each item found for the request parameters: - 

Parameter

Description

ItemSpecialOffer

ItemSpecialOffersinformation (see corresponding section).

  Item Special Offer parameters

An Item Special Offer parameter can contain the following parameters: -

Parameter

Description

City

The city name in the language requested (if available).

 

Attribute

Description

 

Code

The unique city code held by GTA.

 

Item

The item name.

 

Attribute

Description

 

Code

The unique item code held by GTA.

 

Parameter

Description

RoomCategories

A collection of one or more RoomCategory

parameters.

RoomCategory

Specifies the room category details.

 

Attribute

Description

 

Id

Specifies the category ID. 

Parameter

Description

Description

Short description of the room category. 

 

SpecialOffers

A list of one or more special offers held for this item (see corresponding section).

 Special Offer parameters

Parameter

Description

Offer

The offer name in the language requested (if available).

 

Attribute

Description

 

Code

The unique offer code held by GTA.

 

Parameter

Description

SpecialOffer

A list of  one or more special offers held for this item.

TravelDates

Specifies the travel dates.

  • FromDate – The start date for the range
  • ToDate – the end date of the range

OfferType

Specifies the type of the offer

  • A - Offer is based on arrival dates
  • I - Offer is inclusive, entire stay must fall within specified travel dates

EffectiveDates

Specifies the effective dates (creation date of the booking).

  • FromDate – The start date for the range
  • ToDate – The end date of the range

StayForNights

Specifies the minimum number of nights that the customer must stay at the hotel in order for the offer to apply.

PayForNights

Specifies the number of nights that will be charged if the customer stays for the minimum number of nights specified within the <StayForNights> element.

DiscountPercentage

Specifies the discount (in percentage) that applies if the offer is not for an entirely free night.

MaximumNightsFree

Specifies the maximum number of times this offer can be applied to a single booking.

AllowedArrivalDates

Specifies the days of the week that the client must arrive in order to receive the offer.

ValidStayDates

Specifies the days of the week that the client can stay at the property in order to receive the offer.

BookBefore

Specifies the date before which the booking must be made in order to qualify for the offer.

BookWithin

Specifies the number of days within which the booking must be made in order to qualify for the offer.

ApplicableOfferNights

Specifies whether all days of the week are applicable for the offer or whether only specific days of the week are applicable for the offer.

1 – Monday

2 – Tuesday

3 – Wednesday

4 – Thursday

5 – Friday

6 – Saturday

7 – Sunday

FS – Full Stay

CN – Cheapest Night

ClosedDates

A list of  one or more dates for which the offer is not available.

ClosedDate

Specifies the dates the offer is not available.

 

Docs Navigation