쿼리 및 힌트 XML 참조

이 섹션에서는 Google XML 기반 힌트 요청 메시지, 힌트 응답 메시지, 쿼리 메시지에 관한 참조를 제공합니다.

<Hint> (힌트 응답 메시지)

힌트 응답 메시지의 루트 요소입니다. 힌트 응답 메시지는 재가격이 책정되어야 하는 호텔 또는 숙박 일정 조합을 지정합니다. Google의 힌트 요청 메시지에 대한 응답입니다.

힌트 응답 메시지는 Google이 서버로부터 힌트 응답을 마지막으로 수신한 이후 가격이 변경된 호텔만 지정해야 합니다.

힌트 응답 메시지는 다음 방법 중 하나를 사용하여 Google에서 가격을 다시 책정해야 하는 호텔 및 숙박 일정을 지정합니다.

  • 정확한 숙박 일정: 체크인 날짜와 숙박 기간의 조합입니다.

  • 체크인 기간: 첫 번째 체크인 날짜부터 마지막 체크인 날짜까지의 체크인 기간을 지정합니다.

  • 숙박 기간 범위 (또는 숙박 일정 범위)

이러한 각 메서드에는 힌트 응답 메시지의 구문이 다릅니다.

자세한 내용은 힌트 응답 메시지를 참고하세요.

구문

<Hint> 요소는 힌트 응답 메시지의 유형에 따라 다른 문법을 사용합니다.

정확한 경로

다음은 힌트 응답 메시지의 정확한 경로의 문법을 보여줍니다.

<!-- Exact Itinerary Hint Response -->
<?xml version="1.0" encoding="UTF-8"?>
<Hint>
  <Item>
    <Property>hotel_ID</Property>
    ...
    <Stay>
      <CheckInDate>checkin_date</CheckInDate>
      <LengthOfStay>number_of_nights</LengthOfStay>
    </Stay>
  </Item>
  ...
</Hint>

체크인 범위

다음은 힌트 응답 메시지의 체크인 범위의 문법을 보여줍니다.

<!-- Check-in Ranges Hint Response -->
<?xml version="1.0" encoding="UTF-8"?>
<Hint>
  <Item>
    <!-- At least one is required -->
    <Property>hotel_ID</Property>
    [...]

    <!-- Required -->
    <FirstDate>first_checkin_date</FirstDate>
    <!-- Required -->
    <LastDate>last_checkin_date</LastDate>
  </Item>
  ...
</Hint>

숙박 기간 범위

다음은 힌트 응답 메시지에서 기간 숙박의 문법을 보여줍니다.

<!-- Ranged Stay Hint Response -->
<?xml version="1.0" encoding="UTF-8"?>
<Hint>
  <Item>
    <!-- At least one is required -->
    <Property>1458700</Property>
    <Property>5418701</Property>
    <StaysIncludingRange>
      <!-- Required -->
      <FirstDate>2025-04-28</FirstDate>
      <!-- Optional -->
      <LastDate>2025-04-29</LastDate>
    </StaysIncludingRange>
  </Item>
  ...
</Hint>

속성

<Hint> 요소에는 선택적 속성인 id가 포함됩니다. 제공되면 이 <Hint>를 기반으로 전송된 <Query> 메시지에 hintId 속성으로 포함됩니다.

하위 요소

<Hint> 요소에는 다음과 같은 하위 요소가 있습니다.

하위 요소 필수 여부 유형 힌트 응답 유형 설명
<CheckInDate> Required Date 정확한 경로 숙박 일정의 체크인 날짜입니다.
<FirstDate> Required Date 체크인 기간 및 범위 있는 숙박 일정 체크인 기간 또는 연속 숙박 힌트 응답 메시지의 기간의 첫 번째 날짜입니다. 날짜는 양 끝값 모두 포함됩니다.
<Item> Required Object 전체 업데이트할 호텔/숙박 일정의 컨테이너입니다.
<LastDate> Required* Date 체크인 기간 및 범위 있는 숙박 일정

체크인 기간 또는 기간별 숙박 힌트 응답 메시지의 기간 마지막 날짜입니다. 날짜는 양 끝값 모두 포함됩니다.

* 이 요소는 연속 숙박의 경우 선택사항입니다.
<LengthOfStay> Required integer 정확한 일정 숙박 일정의 숙박 일수로, 양의 정수로 표현됩니다.
<Property> Required string 전체

호텔 목록과 동일한 ID를 사용하는 호텔의 ID입니다. 단일 <Item> 블록에서 지정할 수 있는 <Property> 요소 수는 힌트 응답 메시지의 유형에 따라 결정됩니다.

  • 정확한 숙박 일정: 최대 100개의 호텔
  • 체크인 범위: <QueryControl> 메시지에서 <MultipleItineraries>을 "checkin_range" 로 설정하면 2개 이상
  • 연속 숙박: <QueryControl> 메시지에서 <MultipleItineraries>를 "affected_dates" 로 설정하면 2개 이상
<Stay> Required Object 정확한 경로 정확한 경로 힌트 응답 메시지의 <CheckinDate> 및 <LengthOfStay> 요소를 위한 컨테이너입니다. 각 <Item>에는 <Stay> 하나만 포함할 수 있습니다.
<StaysIncludingRange> Required Object 범위별 여행 일정 기간별 숙박 힌트 응답 메시지의 <FirstDate> 및 <LastDate> 요소를 위한 컨테이너입니다.

예

정확한 경로

다음 예에서는 단일 속성에 대한 여러 개의 숙박 일정을 힌트 응답 메시지로 정의합니다.

<!-- Exact Itinerary Hint Response -->
<?xml version="1.0" encoding="UTF-8"?>
<Hint>
  <Item>
    <Property>12345</Property>
    <Stay>
      <CheckInDate>2018-07-03</CheckInDate>
      <LengthOfStay>3</LengthOfStay>
    </Stay>
  </Item>
  <Item>
    <Property>12345</Property>
    <Stay>
      <CheckInDate>2018-07-03</CheckInDate>
      <LengthOfStay>4</LengthOfStay>
    </Stay>
  </Item>
</Hint>

체크인 범위

다음 예에서는 가격이 변경되어 다시 가져와야 하는 호텔 2곳을 지정합니다. Google은 7월 3일과 7월 6일 사이에 숙박 시설 12345와 67890의 모든 숙박 일정을 가져옵니다.

<!-- Check-in Ranges Hint Response -->
<?xml version="1.0" encoding="UTF-8"?>
<Hint>
  <Item>
    <Property>12345</Property>
    <Property>67890</Property>
    <FirstDate>2018-07-03</FirstDate>
    <LastDate>2018-07-06</LastDate>
  </Item>
</Hint>

숙박 기간 범위

다음 예에서는 숙박 기간 범위의 두 가지 사용 사례를 보여줍니다. 하나는 숙박 기간 범위이고 다른 하나는 1박입니다.

<!-- Ranged Stay Hint Response -->
<?xml version="1.0" encoding="UTF-8"?>
<Hint>
  <!-- Google fetches prices for all itineraries (first and last date are set) -->
  <Item>
    <Property>12345</Property>
    <StaysIncludingRange>
      <FirstDate>2018-07-03</FirstDate>
      <LastDate>2018-07-06</LastDate>
    </StaysIncludingRange>
  </Item>

  <!-- Google fetches prices for a single night (first date only) -->
  <Item>
    <Property>67890</Property>
    <StaysIncludingRange>
      <FirstDate>2018-07-03</FirstDate>
    </StaysIncludingRange>
  </Item>
</Hint>

이러한 각 예에 대해 Google은 <Query>로 응답하며, 그러면 지정된 호텔/숙박 일정의 가격 업데이트가 포함된 <Transaction>로 응답해야 합니다.

<HintRequest>

힌트 요청 메시지의 루트 요소입니다. Google은 서버에 힌트 요청 메시지를 전송하고, Google이 서버로부터 마지막으로 힌트 응답을 수신한 이후 가격이 변경된 호텔 및 숙박 일정을 지정하는 응답을 기대합니다.

가격이 변경되면 Google은 표시된 호텔 및 숙박 일정의 업데이트된 가격 데이터를 가져오는 <Query>를 전송합니다.

자세한 내용은 힌트 요청 메시지를 참고하세요.

구문

<HintRequest> 요소는 다음 구문을 사용합니다.

구문

<?xml version="1.0" encoding="UTF-8"?>
<HintRequest>
  <LastFetchTime>last_fetch_time</LastFetchTime>
</HintRequest>

속성

<HintRequest> 요소에 속성이 없습니다.

하위 요소

<HintRequest> 요소에는 다음과 같은 하위 요소가 있습니다.

하위 요소 유형 설명
<LastFetchTime> DateTime Google에서 힌트 요청 메시지에 대한 힌트 응답 메시지를 마지막으로 수신한 시간입니다.

이 시간이 서버에서 가격을 마지막으로 업데이트한 시간보다 오래된 경우 변경된 호텔을 지정하는 힌트 응답 메시지로 응답해야 합니다.

최근에 가져오기에 성공한 적이 없는 경우 대기열이 많아 더 심각한 문제가 발생하지 않도록 고정 간격 값으로 설정됩니다. 현재 고정 간격 값은 1, 000초이지만 변경될 수 있습니다.

자세한 내용은 힌트 응답 메시지를 참고하세요.

예

다음 예는 힌트 요청 메시지를 보여줍니다.

힌트 요청 메시지

다음 예는 힌트 요청 메시지를 보여줍니다.

<?xml version="1.0" encoding="UTF-8"?>
<HintRequest id="ABCDEF" timestamp="2018-06-07T16:20:00Z">
  <LastFetchTime>2018-03-25T00:04:09Z</LastFetchTime>
</HintRequest>

<Query>

Query 메시지의 루트 요소입니다. Query 메시지는 Google에서 가격 또는 메타데이터 업데이트를 요청하는 메시지입니다. 이 값은 가져오기 및 변동된 가격 게재 모드 모두에서 사용됩니다.

가격 쿼리 메시지

가격 쿼리 메시지는 가격을 제공하는 숙박 시설 및 숙박 일정 조합을 지정합니다.

서버가 가격 쿼리 메시지를 수신하면 요청된 가격 정보가 포함된 <Transaction> 메시지로 응답해야 합니다.

자세한 내용은 가격 책정 개요를 참고하세요.

Query 메시지에는 세 가지 특별한 유형이 있습니다.

  • 실시간 가격: Google은 실시간 가격 업데이트를 요청하는 특정 사용자 요청에 응답합니다. 파트너가 Live pricing query 메시지를 수신하면 요청된 가격 정보가 <Result> 요소에 포함된 <Transaction> 메시지로 응답해야 합니다.

  • 문맥 가격 책정: Google은 이전에 인기가 높았던 문맥을 기반으로 가격 캐시를 업데이트합니다. With context query 메시지를 수신하면 요청된 가격 정보가 <Result> 요소에 포함된 <Transaction> 메시지로 응답해야 합니다.

  • 메타데이터: Google에서 지정된 호텔의 객실 및 객실 패키지에 대한 메타데이터 업데이트를 요청합니다. Metadata Query 메시지를 수신하면 <PropertyDataSet> 요소에서 객실 및 객실 패키지에 관한 데이터를 지정하는 <Transaction> 메시지로 응답해야 합니다. 자세한 내용은 룸 번들 메타데이터를 참고하세요.

구문

<Query> 요소는 다음 구문을 사용합니다.

가격 쿼리

<?xml version="1.0" encoding="UTF-8"?>
<Query>
  <Checkin>YYYY-MM-DD</Checkin>
  <Nights>number_of_nights</Nights>
  <PropertyList>
    <Property>hotel_id</Property>
    ...
  </PropertyList>
</Query>

실시간 가격

<?xml version="1.0" encoding="UTF-8"?>
<Query latencySensitive="true_or_false">
  <Checkin>YYYY-MM-DD</Checkin>
  <Nights>number_of_nights</Nights>
  <!-- Only for Check-in Date Range pricing queries (Changed Pricing) -->
  <FirstDate>YYYY-MM-DD</FirstDate>
  <LastDate>YYYY-MM-DD</LastDate>
  <!-- Only for Ranged Stay pricing queries (Changed Pricing) -->
  <AffectedNights>number_of_nights</AffectedNights>
  <PropertyList>
    <Property>hotel_id</Property>
    ...
  </PropertyList>
  <!-- See documentation below for <Context> -->
  <Context>
   ...
  </Context>
</Query>

컨텍스트 포함

<?xml version="1.0" encoding="UTF-8"?>
<Query>
  <Checkin>YYYY-MM-DD</Checkin>
  <Nights>number_of_nights</Nights>
  <!-- Only for Check-in Date Range pricing queries (Changed Pricing) -->
  <FirstDate>YYYY-MM-DD</FirstDate>
  <LastDate>YYYY-MM-DD</LastDate>
  <!-- Only for Ranged Stay pricing queries (Changed Pricing) -->
  <AffectedNights>number_of_nights</AffectedNights>
  <PropertyContextList>
    <PropertyContext>
      <Property>hotel_id</Property>
      ...
      <!-- See documentation below for <Context> -->
      <Context>
      ...
      </Context>
    </PropertyContext>
  </PropertyContextList>
</Query>

메타데이터

<HotelInfoProperties>
  <Property>property_ID</Property>
  ...
</HotelInfoProperties>

속성

<Query> 요소는 latencySensitive 속성 하나를 포함할 수 있습니다.

latencySensitive 속성은 선택사항입니다. 이 속성이 제공되고 true로 설정되면 쿼리가 Live Pricing Query임을 나타냅니다. Google에서 latencySensitive 속성을 사용하여 쿼리를 전송하도록 하려면 기술계정 관리자 (TAM)에게 문의하세요.

하위 요소

<Query> 요소에는 다음과 같은 하위 요소가 있습니다.

하위 요소 검색어 유형 유형 설명
<AffectedNights> Pricing integer 숙박 기간 범위의 밤 수입니다. 이 요소는 가격 변경과 함께 사용되는 숙박 기간 가격 쿼리에만 사용됩니다.
<Checkin> Pricing Date 특정 가격 변경 날짜입니다.
<Context> Pricing (Live Pricing Queries only) <Context> 실시간 가격 쿼리의 경우 쿼리가 실행되는 특정 매개변수를 지정합니다. 하위 요소는 다음과 같습니다.
  • <Occupancy>: 총 게스트 수입니다.
  • <OccupancyDetails>: 투숙객 유형(예: 성인 또는 어린이)
  • <UserCountry>: 사용자가 있는 국가
  • <UserDevice>: 투숙객이 호텔을 검색하는 데 사용한 기기 유형입니다(예: "mobile, tablet, desktop).

<Context> 요소는 단일 요청에서 반복될 수 있으므로 다양한 숙박 인원에 대한 쿼리를 실행할 수 있습니다. 하위 요소 목록, 문법, 예시는 <Context>를 참고하세요.
<FirstDate> Pricing Date 가격이 적용되는 다양한 숙박 일정의 시작일입니다. 이 요소는 가격 변경과 함께 사용되는 체크인 기간 가격 쿼리에만 사용됩니다.
<HotelInfoProperties> Metadata string Google에서 메타데이터 Query 메시지의 방 및 Room Bundle 메타데이터를 업데이트하려는 속성 1개 이상 이 요소는 호텔 숙박 시설 ID를 지정하는 <Property> 요소를 하나 이상 포함할 수 있습니다.
<LastDate> Pricing Date 가격이 적용되는 일정의 종료일입니다. 이 요소는 가져오기 + 힌트와 함께 사용되는 체크인 기간 가격 쿼리에만 사용됩니다.
<Nights> Pricing integer 특정 숙박 일정의 숙박 일수(최대 30일)입니다.
<PropertyList> Pricing Object

가격 업데이트가 필요한 호텔의 ID 1개 이상

<Property> 요소에서 각 호텔을 정의합니다. 값은 호텔 목록의 호텔 ID와 일치하는 문자열입니다. 예:

<PropertyList>
  <Property>pid1</Property>
  <Property>pid2</Property>
</PropertyList>

예

가격 쿼리

다음 예는 2023년 5월 23일부터 3박 동안 이용 가능한 호텔에 대한 가격 업데이트를 요청하는 가격 쿼리 메시지를 보여줍니다.

<?xml version="1.0" encoding="UTF-8"?>
<Query>
  <Checkin>2023-05-23</Checkin>
  <Nights>3</Nights>
  <PropertyList>
    <Property>pid5</Property>
    <Property>pid8</Property>
    <Property>pid13</Property>
    <Property>pid21</Property>
  </PropertyList>
</Query>

실시간 가격 쿼리

다음 예는 응답 시간 제한이 500밀리초인 실시간 가격 쿼리를 보여줍니다.

<?xml version="1.0" encoding="UTF-8"?>
<Query latencySensitive="true">
  <Checkin>2017-06-07</Checkin>
  <Nights>5</Nights>
  <DeadlineMs>500</DeadlineMs>
  <PropertyList>
    <Property>8675309</Property>
  </PropertyList>
  <Context>
    <Occupancy>4</Occupancy>
    <OccupancyDetails>
      <NumAdults>2</NumAdults>
      <Children>
        <Child age="8"/>
        <Child age="5"/>
      </Children>
    </OccupancyDetails>
    <UserCountry>US</UserCountry>
    <UserDevice>mobile</UserDevice>
  </Context>
</Query>

컨텍스트 쿼리 사용

<?xml version="1.0" encoding="UTF-8"?>
<Query>
  <Checkin>2023-05-23</Checkin>
  <Nights>2</Nights>
  <PropertyContextList>
    <PropertyContext>
      <Property>8675309</Property>
      <!-- In the future, occupancy and device might be specified -->
      <Context><UserCountry>US</UserCountry></Context>
      <Context><UserCountry>GB</UserCountry></Context>
    </PropertyContext>
    <PropertyContext>
      <Property>8675310</Property>
      <Property>8675311</Property>
      <Context><UserCountry>CA</UserCountry></Context>
    </PropertyContext>
  </PropertyContextList>
</Query>

메타데이터 쿼리

<?xml version="1.0" encoding="UTF-8"?>
<Query>
  <HotelInfoProperties>
    <Property>pid5</Property>
    <Property>pid8</Property>
    <Property>pid13</Property>
    <Property>pid21</Property>
  </HotelInfoProperties>
</Query>

숙박 기간 및 체크인 날짜 범위 가격 쿼리를 비롯한 추가 예시는 Query 메시지 예를 참고하세요.

<Context>

<Context> 요소는 투숙객 수 및 유형, 사용자 국가, 사용자 기기 등 Live pricing query에 관한 정보를 설명합니다.

여러 개의 <Context>는 서로 다른 사용자 국가 또는 사용자 기기에서 사용되지 않습니다. 여러 <Context>를 사용하여 여러 숙박 인원을 쿼리하는 경우 각 숙박 인원 가격을 해당 숙박 시설 또는 숙박 일정의 추가 객실 패키지로 제공합니다. 각 숙박 시설 또는 숙박 일정에는 여러 숙박 인원에 대한 가격이 포함된 단일 <Result> 블록이 있어야 합니다.

<Context> 쿼리의 응답 세부정보는 <OccupancyDetails>를 참고하세요.

구문

<Context> 요소는 다음 구문을 사용합니다.

구문

<?xml version="1.0" encoding="UTF-8"?>
<Query latencySensitive="true_or_false">
  <Checkin>date</Checkin>
  <Nights>number_of_nights</Nights>
  <DeadlineMs>number_of_milliseconds</DeadlineMs>
  <PropertyList>
    <Property>property_ID</Property>
  </PropertyList>
  <Context>
    <Occupancy>total_number_of_guests</Occupancy>
    <OccupancyDetails>
      <NumAdults>number_of_adults</NumAdults>
      <Children>
        <Child age=age_of_one_child_guest/>
        <Child age=age_of_one_child_guest/>
      </Children>
    </OccupancyDetails>
    <UserCountry>end_user_country</UserCountry>
    <UserDevice>user_device_type</UserDevice>
  </Context>
</Query>

하위 요소

<Context> 요소에는 다음과 같은 하위 요소가 있습니다.

하위 요소 쿼리 유형 유형 설명
<Occupancy> Pricing integer 총 투숙객 수를 지정합니다.

필수는 아니지만 <Occupancy>를 사용한 쿼리로 인해 각 <Occupancy>에 대해 정의된 적절한 객실 패키지가 포함된 거래 메시지가 생성됩니다. 하지만 객실 패키지를 사용할 수 없는 경우 <Occupancy> 요소를 지정하는 것이 좋습니다.

참고:<Occupancy>가 쿼리에 항상 표시되는 것은 아닙니다. 이 경우 모든 숙박 인원의 가격을 반환해야 합니다.
<OccupancyDetails> Pricing Object 앞에 <Occupancy>가 옵니다. 다음을 포함하여 유형별로 투숙객을 지정합니다.
  • <NumAdults>: 성인 투숙객 수
  • <Children> 및 <Child="age">: 어린이 (일반적으로 0~17세)인 투숙객을 지정하고 각 어린이의 연령을 선택적으로 포함합니다.

필수는 아니지만 <OccupancyDetails>를 사용한 쿼리로 인해 각 <Occupancy>에 정의된 적절한 객실 패키지가 포함된 거래 메시지가 생성됩니다. 하지만 객실 패키지를 사용할 수 없는 경우 <OccupancyDetails> 요소를 지정하는 것이 좋습니다.

참고: <OccupancyDetails>가 항상 쿼리에 표시되는 것은 아닙니다. 이 경우 모든 투숙객이 성인이라고 가정해야 합니다.
<UserCountry> Pricing string

사용자가 거주하는 국가별로 요금을 필터링합니다. 값은 2자리 국가 코드(예: 미국의 경우 "US") 또는 지역 코드(예: '유럽'의 경우 "EU")입니다.

<UserCountry>가 정의된 쿼리로 인해 쿼리된 국가에 대해 적절한 <Rates> 블록이 정의된 거래 메시지가 생성됩니다.
<UserDevice> Pricing string

사용자가 검색하는 기기 유형별로 요금을 필터링합니다. 가능한 값은 다음과 같습니다.

  • mobile
  • desktop
  • tablet

<UserDevice>가 정의된 쿼리는 쿼리된 기기 유형에 대해 정의된 적절한 <Rates> 블록이 있는 거래 메시지로 이어져야 합니다.

예

숙박 인원

다음 예는 <Context> 내 <Occupancy>의 실시간 가격 쿼리를 보여줍니다. 실시간 가격 쿼리는 성인 3명을 대상으로 합니다.

<?xml version="1.0" encoding="UTF-8"?>
<Query latencySensitive="true">
  <Checkin>2017-06-07</Checkin>
  <Nights>4</Nights>
  <DeadlineMs>500</DeadlineMs>
  <PropertyList>
    <Property>45617</Property>
  </PropertyList>
  <Context>
    <Occupancy>3</Occupancy>
    <UserCountry>US</UserCountry>
    <UserDevice>mobile</UserDevice>
  </Context>
</Query>

숙박 인원 세부정보

다음 예는 <Context> 내에 <OccupancyDetails>가 있는 실시간 가격 쿼리를 보여줍니다. 실시간 가격 쿼리는 어린이 2명을 포함해 투숙객 4명을 대상으로 하며, 휴대기기에서 예약하는 미국 투숙객에게 적용되는 요금을 찾습니다.

<?xml version="1.0" encoding="UTF-8"?>
<Query latencySensitive="true">
  <Checkin>2017-06-07</Checkin>
  <Nights>5</Nights>
  <DeadlineMs>500</DeadlineMs>
  <PropertyList>
    <Property>8675309</Property>
  </PropertyList>
  <Context>
    <Occupancy>4</Occupancy>
    <OccupancyDetails>
      <NumAdults>2</NumAdults>
      <Children>
        <Child age="4"/>
        <Child age="12"/>
      </Children>
    </OccupancyDetails>
    <UserCountry>US</UserCountry>
    <UserDevice>mobile</UserDevice>
  </Context>
</Query>

여러 컨텍스트

다음 예는 실시간 가격 쿼리에서 <Context> 요소를 추가로 사용하는 방법을 보여줍니다.

<?xml version="1.0" encoding="UTF-8"?>
<Query latencySensitive="true">
  <Checkin>2017-06-07</Checkin>
  <Nights>4</Nights>
  <DeadlineMs>500</DeadlineMs>
  <PropertyList>
    <Property>45617</Property>
  </PropertyList>
  <Context>
    <Occupancy>3</Occupancy>
    <UserCountry>US</UserCountry>
    <UserDevice>mobile</UserDevice>
  </Context>
  <Context>
    <Occupancy>6</Occupancy>
    <OccupancyDetails>
      <NumAdults>4</NumAdults>
      <Children>
        <Child age="6"/>
        <Child age="10"/>
      </Children>
    </OccupancyDetails>
    <UserCountry>US</UserCountry>
    <UserDevice>mobile</UserDevice>
  </Context>
</Query>