Referensi XML Kueri & Petunjuk

Bagian ini menyediakan referensi untuk pesan Permintaan Petunjuk, pesan Respons Petunjuk, dan pesan Kueri berbasis XML Google.

<Hint> (Pesan Respons Petunjuk)

Elemen root pesan Respons Petunjuk. Pesan Respons Petunjuk menentukan kombinasi hotel/itinerari mana yang perlu ditentukan ulang harganya. Pesan tersebut adalah respons Anda terhadap pesan Permintaan Petunjuk dari Google.

Pesan Respons Petunjuk hanya akan menentukan hotel yang harganya telah berubah sejak terakhir kali Google menerima Respons Petunjuk yang berhasil dari server Anda.

Pesan Respons Petunjuk menggunakan salah satu metode berikut untuk menentukan hotel dan itinerari yang harus ditentukan ulang harganya oleh Google:

  • Itinerari pasti: Kombinasi tanggal check-in dan lama menginap.
  • Rentang tanggal check-in: Menentukan rentang tanggal check-in, yang dimulai dengan tanggal check-in pertama dan diakhiri dengan tanggal check-in terakhir.
  • Menginap dengan rentang (atau itinerari dengan rentang)

Setiap metode ini memerlukan sintaksis yang berbeda untuk pesan Respons Petunjuk.

Untuk mengetahui informasi selengkapnya, baca Pesan Respons Petunjuk.

Sintaksis

Elemen <Hint> menggunakan sintaksis yang berbeda, bergantung pada jenis pesan Respons Petunjuk:

Itinerari Pasti

Berikut adalah sintaksis untuk itinerari pasti pada pesan Respons Petunjuk:

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

Rentang Check-in

Berikut adalah sintaksis untuk rentang check-in pada pesan Respons Petunjuk:

<!-- Check-in Ranges Hint Response -->
<?xml version="1.0" encoding="UTF-8"?>
<Hint>
  <Item>
    <!-- At least one is required -->
    <!-- Can be > 1 if MultipleItineraries is "checkin_range" in your QueryControl message -->
    <Property>hotel_ID</Property>
    [...]

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

Menginap dengan Rentang

Berikut adalah sintaksis untuk menginap dengan rentang pada pesan Respons Petunjuk:

<!-- Ranged Stay Hint Response -->
<?xml version="1.0" encoding="UTF-8"?>
<Hint>
  <Item>
    <!-- At least one is required -->
    <!-- Can be > 1 if MultipleItineraries is "affected_dates" in your QueryControl message -->
    <Property>hotel_ID</Property>
    [...]

    <StaysIncludingRange>
      <!-- Required -->
      <FirstDate>first_date</FirstDate>

      <!-- Optional -->
      <LastDate>last_date</LastDate>
    </StaysIncludingRange>
  </Item>
  ...
</Hint>

Atribut

Elemen <Hint> tidak memiliki atribut.

Elemen turunan

Elemen <Hint> memiliki elemen turunan berikut:

Elemen Turunan Wajib? Jenis Jenis Respons Petunjuk Deskripsi
<CheckInDate> Wajib Date Itinerari pasti Tanggal check-in untuk itinerari.
<FirstDate> Wajib Date Rentang check-in dan itinerari dengan rentang Tanggal pertama dari rentang tanggal untuk pesan Respons Petunjuk rentang check-in atau menginap dengan rentang. Tanggal bersifat inklusif.
<Item> Wajib Object Semua Container untuk hotel/itinerari yang akan diperbarui.
<LastDate> Wajib* Date Rentang check-in dan itinerari dengan rentang Tanggal terakhir dari rentang tanggal untuk pesan Respons Petunjuk rentang check-in atau menginap dengan rentang. Tanggal bersifat inklusif.

* Elemen ini bersifat opsional untuk menginap dengan rentang.

<LengthOfStay> Wajib Integer Itinerari pasti Jumlah malam untuk itinerari, yang dinyatakan sebagai bilangan bulat positif.
<Property> Wajib String Semua ID hotel, yang menggunakan ID yang sama seperti Daftar Hotel. Jumlah elemen <Property> yang dapat Anda tentukan dalam satu blok <Item> ditentukan berdasarkan jenis pesan Respons Petunjuk:

  • Itinerari pasti: Hingga 100 hotel.
  • Rentang check-in: Lebih dari satu jika Anda menetapkan <MultipleItineraries> ke "checkin_range" dalam pesan <QueryControl>.
  • Menginap dengan rentang: Lebih dari satu jika Anda menetapkan <MultipleItineraries> ke "affected_dates" dalam pesan <QueryControl>.
<Stay> Wajib Object Itinerari pasti Container untuk elemen <CheckinDate> dan <LengthOfStay> dalam pesan Respons Petunjuk itinerari pasti. Setiap <Item> hanya boleh berisi satu <Stay>.
<StaysIncludingRange> Wajib Object Itinerari dengan rentang Container untuk elemen <FirstDate> dan <LastDate> dalam pesan Respons Petunjuk menginap dengan rentang.

Contoh

Itinerari Pasti

Contoh berikut menentukan beberapa itinerari untuk Pesan Respons Petunjuk satu properti:

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

Rentang Check-in

Contoh berikut menentukan dua hotel yang harganya telah berubah dan harus diambil lagi. Google mendapatkan semua itinerari antara 3 Juli dan 6 Juli untuk properti 12345 dan 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>

Perhatikan bahwa agar pesan rentang check-in dapat menentukan beberapa properti dalam satu <Item>, nilai <MultipleItineraries> dalam <QueryControl> harus ditetapkan ke "checkin_range".

Menginap dengan Rentang

Contoh berikut menunjukkan dua penggunaan menginap dengan rentang yang berbeda, satu untuk rentang malam dan satu lagi untuk satu malam:

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

Perhatikan bahwa agar pesan menginap dengan rentang dapat menentukan beberapa properti dalam satu <Item>, nilai <MultipleItineraries> dalam <QueryControl> harus ditetapkan ke "affected_dates".

Untuk masing-masing contoh ini, Google merespons dengan <Query>, lalu Anda harus merespons dengan <Transaction> yang menyertakan pembaruan harga untuk hotel/itinerari yang ditentukan.

<HintRequest>

Elemen root pesan Permintaan Petunjuk. Google mengirimkan pesan Permintaan Petunjuk ke server Anda dan mengharapkan respons yang menentukan hotel dan itinerari yang harganya telah berubah sejak terakhir kali Google menerima Respons Petunjuk yang berhasil dari server Anda.

Jika ada perubahan harga, Google akan mengirimkan <Query> yang mengambil data harga yang diperbarui untuk hotel dan itinerari yang ditunjukkan.

Untuk mengetahui informasi selengkapnya, baca Pesan Permintaan Petunjuk.

Sintaksis

Elemen <HintRequest> menggunakan sintaksis berikut:

Sintaksis

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

Atribut

Elemen <HintRequest> tidak memiliki atribut.

Elemen turunan

Elemen <HintRequest> memiliki elemen turunan berikut:

Elemen Turunan Jenis Deskripsi
<LastFetchTime> DateTime Terakhir kali Google berhasil mendapatkan pesan Respons Petunjuk terhadap pesan Permintaan Petunjuk.

Jika waktu ini lebih lama dari terakhir kali Anda memperbarui harga di server, Anda harus merespons dengan pesan Respons Petunjuk yang menentukan hotel yang telah diubah.

Untuk mengetahui informasi selengkapnya, baca Pesan Respons Petunjuk.

Contoh

Pesan Permintaan Petunjuk

Contoh berikut menampilkan pesan Permintaan Petunjuk:

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

Elemen root pesan Kueri. Pesan kueri adalah permintaan dari Google untuk pembaruan harga atau metadata. Pesan kueri digunakan dengan mode pengiriman Pull dan Harga yang Diubah.

Ada dua jenis pesan Kueri:

  • Harga: Google meminta pembaruan harga untuk hotel yang ditentukan. Saat menerima pesan Kueri harga, Anda harus merespons dengan pesan <Transaction> yang berisi informasi harga yang diminta di elemen <Result>.

    Kueri Harga Real Time adalah jenis khusus pesan Kueri harga saat Google meminta pembaruan harga real time.

    Untuk mengetahui informasi selengkapnya, baca Ringkasan Harga.

  • Metadata: Google meminta pembaruan metadata untuk kamar dan Paket Kamar untuk hotel yang ditentukan. Saat menerima pesan Kueri metadata, Anda harus merespons dengan pesan <Transaction> yang menentukan data tentang kamar dan Paket Kamar di elemen <PropertyDataSet>.

    Untuk mengetahui informasi selengkapnya, baca Metadata Paket Kamar.

Sintaksis untuk pesan berbeda, bergantung pada jenisnya. Kedua jenis ini dijelaskan di bagian ini.

Sintaksis

Elemen <Query> menggunakan sintaksis berikut:

Sintaksis

<?xml version="1.0" encoding="UTF-8"?>
<Query latencySensitive="true_or_false">
<!-- The "latencySensitive" attribute appears only with Live Pricing Queries -->

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

    <!-- Only for Live Pricing Queries -->
    <DeadlineMs>deadline</DeadlineMs>
    <Context>
      <Occupancy>total_number_of_guests</Occupancy>
      <UserCountry>country_code</UserCountry>
      <UserDevice>device_type</UserDevice>
    </Context>

  <!-- METADATA QUERIES -->
    <HotelInfoProperties>
      <Property>property_ID</Property>
      ...
    </HotelInfoProperties>

</Query>

Atribut

Elemen <Query> dapat berisi satu atribut: <LatencySensitive>.

Atribut <LatencySensitive> bersifat opsional. Saat disediakan dan ditetapkan ke true, ini menunjukkan bahwa kueri tersebut adalah Kueri Harga Real Time. Agar Google dapat mengirimkan kueri dengan atribut <LatencySensitive>, harap kirimkan permintaan ke manajer akun teknis Anda.

Elemen turunan

Elemen <Query> memiliki elemen turunan berikut:

Elemen Turunan Jenis Kueri Jenis Deskripsi
<AffectedNights> Harga Integer Jumlah malam untuk menginap dengan rentang. Elemen ini hanya digunakan untuk kueri harga Menginap dengan Rentang yang digunakan dengan Harga yang Diubah.
<Checkin> Harga Date Tanggal perubahan harga tertentu.
<Context> Harga (khusus Kueri Harga Real Time) Object Untuk Kueri Harga Real Time, menentukan parameter tertentu yang digunakan untuk membuat kueri. Elemen turunan mencakup:
  • <Occupancy>: jumlah total tamu
  • <OccupancyDetails>: jenis tamu, seperti orang dewasa atau anak-anak
  • <UserCountry>: negara tempat pengguna berada
  • <UserDevice>: jenis perangkat yang digunakan tamu untuk menelusuri hotel, seperti "mobile", "tablet", atau "desktop".

Elemen <Context> dapat diulang dalam satu permintaan, yang memungkinkan kueri untuk jumlah tamu yang berbeda. Baca <Context> untuk mengetahui daftar elemen turunan, sintaksis, dan contoh.

<FirstDate> Harga Date Tanggal mulai untuk rentang itinerari saat harga diterapkan. Elemen ini hanya digunakan untuk kueri harga Rentang Tanggal Check-in yang digunakan dengan Harga yang Diubah.
<HotelInfoProperties> Metadata String Satu atau beberapa properti yang diinginkan Google untuk memperbarui metadata kamar dan Paket Kamar pada pesan Kueri metadata. Elemen ini dapat berisi satu atau beberapa elemen <Property> yang menentukan ID properti hotel.
<LastDate> Harga Date Tanggal akhir untuk rentang itinerari saat harga diterapkan. Elemen ini hanya digunakan untuk kueri harga Rentang Tanggal Check-in yang digunakan dengan Pull + Petunjuk.
<Nights> Harga Integer Jumlah malam untuk itinerari tertentu, maksimal 30.
<PropertyList> Harga Object Satu atau beberapa ID untuk hotel yang memerlukan pembaruan harga.

Tentukan setiap hotel dalam elemen <Property>. Nilainya adalah string yang cocok dengan ID hotel dalam Daftar Hotel Anda. Contoh:


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

Contoh

Kueri Harga

Contoh berikut menampilkan pesan Kueri harga yang meminta pembaruan harga untuk serangkaian hotel, yang tersedia untuk 3 malam, dan mulai tanggal 10 Juni 2018:

<?xml version="1.0" encoding="UTF-8"?>
<Query>
  <Checkin>2018-06-10</Checkin>
  <Nights>3</Nights>
  <PropertyList>
    <Property>pid5</Property>
    <Property>pid8</Property>
    <Property>pid13</Property>
    <Property>pid21</Property>
  </PropertyList>
</Query>

Kueri Metadata

Contoh berikut menampilkan pesan Kueri metadata:

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

Untuk contoh lainnya, termasuk menginap dengan rentang dan kueri harga rentang tanggal check-in, lihat Contoh pesan kueri.

<Context>

Elemen <Context> menjelaskan informasi untuk Kueri Harga Real Time, termasuk jumlah dan jenis tamu, negara pengguna, dan perangkat pengguna.

Beberapa <Context> tidak akan pernah digunakan dengan negara atau perangkat pengguna yang berbeda. Jika beberapa <Context> digunakan untuk mengkueri beberapa jumlah tamu, harap berikan setiap harga jumlah tamu sebagai Paket Kamar tambahan untuk properti/itinerari yang sesuai. Setiap properti/itinerari harus memiliki satu blok <Result> dengan harga untuk beberapa jumlah tamu yang disertakan.

Untuk mengetahui detail respons untuk kueri <Context>, lihat <OccupancyDetails>.

Sintaksis

Elemen <Context> menggunakan sintaksis berikut:

Sintaksis

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

Elemen turunan

Elemen <Context> memiliki elemen turunan berikut:

Elemen Turunan Jenis kueri Jenis Deskripsi
<Occupancy> Harga Integer Menentukan jumlah total tamu.

Meskipun tidak wajib, kueri yang berisi <Occupancy> akan menghasilkan pesan transaksi dengan Paket Kamar yang sesuai yang ditentukan untuk setiap <Occupancy> yang dikueri.

Catatan: <Occupancy> mungkin tidak selalu muncul dalam kueri. Dalam kasus tersebut, Anda harus menampilkan harga semua jumlah tamu.

<OccupancyDetails> Harga Object Didahului oleh <Occupancy>. Menentukan tamu berdasarkan jenis, termasuk:

  • <NumAdults>: jumlah tamu dewasa
  • <Children> dan <Child "age">: Menentukan tamu anak-anak (biasanya berusia 0-17 tahun), dan menyertakan usia setiap anak secara opsional.
  • Meskipun tidak wajib, kueri yang berisi <OccupancyDetails> akan menghasilkan pesan transaksi dengan Paket Kamar yang sesuai yang ditentukan untuk setiap <Occupancy> yang dikueri.

    Catatan: <OccupancyDetails> mungkin tidak selalu muncul dalam kueri. Dalam kasus tersebut, Anda harus mengasumsikan bahwa semua tamu adalah orang dewasa.

<UserCountry> Harga String

Memfilter tarif berdasarkan negara tempat pengguna berada. Nilainya adalah kode negara 2 huruf seperti “AS” untuk Amerika Serikat, atau kode wilayah, seperti "UE" untuk "Eropa".

Kueri yang berisi <UserCountry> yang ditentukan akan menghasilkan pesan transaksi dengan blok <Rates> yang sesuai yang ditentukan untuk negara yang dikueri.

<UserDevice> Harga String

Memfilter tarif berdasarkan jenis perangkat yang digunakan pengguna untuk melakukan penelusuran. Kemungkinan nilainya:

  • seluler
  • desktop
  • tablet

Kueri yang berisi <UserDevice> yang ditentukan akan menghasilkan pesan transaksi dengan blok <Rates> yang sesuai yang ditentukan untuk jenis perangkat yang dikueri.

Contoh

Jumlah Tamu

Contoh berikut menampilkan Kueri Harga Real Time untuk <Occupancy> dalam <Context>. Kueri Harga Real Time untuk 3 orang dewasa.

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

Detail Jumlah Tamu

Contoh berikut menampilkan Kueri Harga Real Time dengan <OccupancyDetails> dalam <Context>. Kueri Harga Real Time adalah untuk 4 tamu, 2 di antaranya adalah anak-anak, dan mencari tarif yang berlaku untuk pemesanan tamu AS dari perangkat seluler:

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

Multi-Konteks

Contoh berikut menunjukkan penggunaan elemen <Context> tambahan dalam Kueri Harga Real Time.

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