مرجع 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 است. وقتی ارائه شود، به‌عنوان مشخصه hintId در پیام‌های <Query> ارسال‌شده براساس این <Hint> گنجانده می‌شود.

عناصر فرزند

عنصر <Hint> دارای عناصر فرزند زیر است:

عنصر فرعی الزامی است؟ نوع نوع پاسخ خوانایاری شرح
<CheckInDate> Required Date برنامه‌های سفر دقیق تاریخ ورود برای برنامه سفر.
<FirstDate> Required Date محدوده‌های اعلام حضور و برنامه‌های سفر محدوده‌دار اولین تاریخ از محدوده تاریخ برای محدوده ثبت ورود یا پیام «پاسخ خوانایاری» اقامت محدوده‌ای. تاریخ‌ها شامل این روزها است.
<Item> Required Object همه محتوی برای هتل/برنامه سفر که باید به‌روز شود.
<LastDate> Required* Date محدوده‌های اعلام حضور و برنامه‌های سفر محدوده‌دار

آخرین تاریخ از محدوده تاریخ برای محدوده ورود یا پیام «پاسخ خوانایاری» اقامت محدوده‌ای. تاریخ‌ها شامل روزهای ابتدا و انتها است.

* این عنصر برای اقامت‌های بازه‌ای اختیاری است.
<LengthOfStay> Required integer برنامه‌های سفر دقیق تعداد شب‌های سفر که به‌صورت عدد صحیح مثبت بیان می‌شود.
<Property> Required string همه

شناسه هتل، بااستفاده از همان شناسه فهرست هتل. تعداد عناصر <Property> که می‌توانید در یک بلوک <Item> مشخص کنید براساس نوع پیام «پاسخ خوانایاری» تعیین می‌شود:

  • برنامه‌های سفر دقیق: حداکثر ۱۰۰ هتل.
  • محدوده‌های اعلام حضور: اگر <MultipleItineraries> را روی "checkin_range" در پیام <QueryControl> تنظیم کنید، بیش‌از یک مورد خواهد بود.
  • اقامت بازه‌ای: اگر <MultipleItineraries> را روی "affected_dates" در پیام <QueryControl> تنظیم کنید، بیش‌از یک مورد.
<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>

محدوده‌های اعلام حضور

مثال زیر دو هتل را مشخص می‌کند که قیمت‌گذاری آن‌ها تغییر کرده است و باید دوباره واکشی شوند. Google همه برنامه‌های سفر بین ۳ ژوئیه و ۶ ژوئیه را برای دارایی‌های ۱۲۳۴۵ و ۶۷۸۹۰ دریافت می‌کند:

<!-- 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>

اقامت‌های محدوده‌ای

مثال زیر دو کاربرد متفاوت از اقامت‌های بازه‌ای را نشان می‌دهد، یکی برای بازه‌ای از شب‌ها و دیگری برای یک شب:

<!-- 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 موفق شد پیام «پاسخ خوانایاری» را برای پیام «درخواست خوانایاری» دریافت کند.

اگر این زمان قدیمی‌تر از آخرین باری است که قیمت‌ها را در سرورتان به‌روزرسانی کرده‌اید، باید با پیام «پاسخ خوانایاری» که مشخص می‌کند کدام هتل‌ها تغییر کرده‌اند پاسخ دهید.

اگر اخیراً واکشی موفقی انجام نشده باشد، این مقدار روی یک مقدار فاصله ثابت تنظیم می‌شود (برای جلوگیری از مشکلات جدی‌تر با کارهای معوقه بزرگ). مقدار فاصله ثابت فعلی ۱۰۰۰ ثانیه است، اما ممکن است تغییر کند.

برای اطلاعات بیشتر، به پیام‌های پاسخ خوانایاری مراجعه کنید.

مثال‌ها

مثال زیر پیام «درخواست خوانایاری» را نشان می‌دهد:

پیام «درخواست خوانایاری»

نمونه زیر پیام «درخواست خوانایاری» را نشان می‌دهد:

<?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 دریافت می‌کنند، باید با پیام <Transaction> که حاوی اطلاعات قیمت درخواستی در عناصر <Result> است پاسخ دهند.

  • با قیمت‌گذاری «زمینه»: Google حافظه نهان قیمت خود را براساس زمینه‌هایی که در گذشته محبوب بوده‌اند به‌روز می‌کند. وقتی پیام With Context query دریافت می‌کنید، باید با پیام <Transaction> که حاوی اطلاعات قیمت درخواستی در عناصر <Result> است پاسخ دهید.

    • با پُرسمان‌های بافتاری برای یک نفر

      هنگام ارائه نرخ‌ها در پاسخ به پُرسمان‌های «با بافت»، فقط باید نرخ مربوط به بافت مشخص‌شده را ارسال کنید. نرخ پایه اشغال حداقل به ۲ ساکن نیاز دارد، بنابراین اگر یک ساکن در نرخ پایه لحاظ شود، نادیده گرفته می‌شود و همچنان به‌عنوان اشغال دوگانه درنظر گرفته می‌شود. در این مورد، باید نرخ پایه را به‌عنوان غیرقابل‌دسترس رد کنید و از نرخ تودرتو در داخل تک‌نفره استفاده کنید. به نمونه پاسخ «با بافت» مراجعه کنید. می‌توانید از قیمت تغییریافته با بافت برای ادغام نرخ‌ها با تنظیم مشخصه mergeable روی "true" استفاده کنید. بیشتر بدانید.

    • قیمت‌گذاری تغییریافته (قبلاً «کشیدن با راهنمایی») با بافت

      وقتی پاسخ پیام <Transaction> را به «قیمت تغییریافته با پُرسمان بافت» ارسال می‌کنید، Google آن را به‌عنوان جایگزین کامل اطلاعات قیمت و دردسترس بودن برای هتل یا برنامه سفر مشخص درنظر می‌گیرد و همه نرخ‌های مختص بافت از پاسخ مستثنی می‌شوند و از حافظه نهان برداشته می‌شوند.

      برای جلوگیری از رونویسی، باید مشخصه mergeable را روی "true" در عنصر <Result> در پیام <Transaction> تنظیم کنید. Google نرخ‌ها را با نرخ‌های ذخیره‌شده موجود برای بافت ارائه‌شده در پاسخ پیوست می‌کند. اگر از مشخصه mergeable استفاده نکنید، باید همه نرخ‌ها را برای همه زمینه‌های مربوطه در پاسخ ارسال کنید.

    • پرس‌وجوی «قیمت‌گذاری زنده» با «زمینه»

      پُرسمان «قیمت‌گذاری زنده» با «زمینه» به‌طور پیش‌فرض رفتار مشخصه ادغام‌پذیر دارد، بنابراین تنظیم این مشخصه الزامی نیست. اگر همه زمینه‌های دیگر یکسان باقی بمانند، فقط باید نرخ(های) زمینه(های) خاصی را که Google درخواست کرده است ارسال کنید. اگر زمینه‌های دیگر تغییر کرده است، باید تغییرات آن زمینه‌ها را به‌طور صریح ارسال کنید؛ درغیراین‌صورت، نرخ‌های جدید در حافظه نهان Google به‌روزرسانی نخواهد شد.

  • فراداده: Google درخواست به‌روزرسانی فراداده برای اتاق‌ها و «بسته‌های ترکیبی اتاق» برای هتل‌های مشخص‌شده می‌کند. وقتی پیام Metadata Query دریافت می‌کنید، باید با پیام <Transaction> پاسخ دهید که داده‌های مربوط به اتاق‌ها و «بسته‌های ترکیبی اتاق» را در عناصر <PropertyDataSet> مشخص می‌کند. برای اطلاعات بیشتر، به فراداده «بسته ترکیبی اتاق» مراجعه کنید.

نحو

عنصر <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 می‌خواهد. این عنصر می‌تواند حاوی یک یا چند عنصر <Property> باشد که شناسه‌های دارایی هتل را مشخص می‌کنند.
<LastDate> Pricing Date تاریخ پایان برای طیفی از برنامه‌های سفر که قیمت‌گذاری بر آن‌ها اعمال می‌شود. این عنصر فقط برای پُرسمان‌های قیمت‌گذاری «محدوده تاریخ ورود» استفاده می‌شود که با «کشیدن + راهنمایی» استفاده می‌شوند.
<Nights> Pricing integer تعداد شب‌ها برای برنامه سفر خاص، حداکثر ۳۰ شب.
<PropertyList> Pricing Object

یک یا چند شناسه برای هتلی که به به‌روزرسانی قیمت نیاز دارد.

هر هتل را در عنصر <Property> تعریف کنید. مقدار رشته‌ای است که با شناسه هتل در فهرست هتل شما مطابقت دارد. برای مثال:

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

مثال‌ها

پُرسمان قیمت‌گذاری

مثال زیر پیام «پرسمان» قیمت‌گذاری را نشان می‌دهد که به‌روزرسانی قیمت را برای مجموعه‌ای از هتل‌ها، دردسترس برای ۳ شب، و شروع از ۲۳ مه ۲۰۲۳ درخواست می‌کند:

<?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>

پُرسمان قیمت‌گذاری زنده

مثال زیر «پرس‌وجوی قیمت‌گذاری زنده» را با محدودیت زمان پاسخ ۵۰۰ میلی‌ثانیه نشان می‌دهد:

<?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, 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>

با پاسخ بافتاری

مثال زیر توضیح می‌دهد که چگونه نرخ پایه را برای یک نفر روی unavailable(-1) تنظیم کنید و نرخ‌ها را در عنصر <Occupancy> قرار دهید.

<?xml version="1.0" encoding="UTF-8"
<Transaction id="Wtdj8QoQIWcAAbaTGlIAAAC4" timestamp="2025-11-19T18:36:48Z">
<Result>
  <Property>6781291</Property>
  <Checkin>2026-01-15</Checkin>
  <Nights>1</Nights>
  <!-- Base rate is set to -1 to indicate unavailability for the default (2-person) occupancy -->
  <Baserate currency="USD">-1</Baserate>
  <Tax currency="USD">0</Tax>
  <OtherFees currency="USD">0</OtherFees>
  <Rates>
    <!-- Nested Rate for Single Occupancy -->
    <Rate rate_rule_id="rule-951">
      <Occupancy>1</Occupancy>
      <OccupancyDetails>
        <NumAdults>1</NumAdults>
      </OccupancyDetails>
      <Baserate currency="USD">150.00</Baserate>
      <Tax currency="USD">15.00</Tax>
      <OtherFees currency="USD">5.00</OtherFees>
    </Rate>
  <!-- Other nested rates for different occupancies or room types could be included here if available -->
  </Rates>
</Result>
</Transaction>

پُرسمان فراداده

<?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">: مشخص می‌کند کدام مهمانان کودک هستند (معمولاً سن ۰ تا ۱۷ سال)، و به‌طور اختیاری شامل سن هر کودک می‌شود.

اگرچه اجباری نیست، اما پُرسمان‌های دارای <OccupancyDetails> باید به پیام تراکنش با «بسته‌های ترکیبی اتاق» مناسب تعریف‌شده برای هر <Occupancy> منجر شود، اما اگر «بسته‌های ترکیبی اتاق» دردسترس نباشد، توصیه می‌شود عنصر <OccupancyDetails> را مشخص کنید.

توجه: <OccupancyDetails> ممکن است همیشه در پُرسمان نشان داده نشود. در چنین مواردی، باید فرض کنید که همه مهمانان بزرگسال هستند.
<UserCountry> Pricing string

نرخ‌ها را براساس کشوری که کاربر در آن قرار دارد فیلتر می‌کند. مقدار آن یک کد کشور ۲ حرفی مانند "US" برای ایالات متحده، یا یک کد منطقه مانند "EU" برای «اروپا» است.

پرس‌وجوهایی که <UserCountry> برای آن‌ها تعریف شده است باید به پیام تراکنشی با بلوک <Rates> مناسب تعریف‌شده برای کشور مورد پرس‌وجو منجر شوند.
<UserDevice> Pricing string

نرخ‌ها را براساس نوع دستگاهی که کاربر از آن جستجو می‌کند فیلتر می‌کند. مقادیر احتمالی:

  • mobile
  • desktop
  • tablet

پرس‌وجوهایی که <UserDevice> برای آن‌ها تعریف شده است باید به پیام تراکنشی منجر شوند که بلوک <Rates> مناسب برای نوع دستگاه پرس‌وجوشده در آن تعریف شده باشد.

مثال‌ها

میزان اشغال

مثال زیر یک پُرسمان قیمت‌گذاری زنده را برای <Occupancy> در <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>
</Query>

جزئیات اشغال

مثال زیر یک پُرسمان قیمت‌گذاری زنده را با <OccupancyDetails> در <Context> نشان می‌دهد. پرسمان قیمت‌گذاری زنده برای ۴ مهمان است که ۲ نفر از آن‌ها کودک هستند و به‌دنبال نرخی است که برای رزرو مهمان ایالات متحده از دستگاه همراه قابل‌اعمال باشد:

<?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>