Referensi XML Kueri & Petunjuk

Bagian ini menyediakan referensi untuk arsitektur berbasis XML Google Pesan Permintaan Petunjuk, Pesan Respons Petunjuk, dan Pesan kueri.

<Hint> (Pesan Respons Petunjuk)

Elemen root pesan Respons Petunjuk. Pesan Respons Petunjuk menentukan kombinasi hotel atau itinerari mana yang perlu ditentukan ulang harganya. Mereka adalah Respons terhadap pesan Permintaan Petunjuk dari Google.

Pesan Respons Petunjuk seharusnya hanya menentukan hotel yang harganya telah ditetapkan 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 oleh Google:

  • Itinerari pasti: Kombinasi tanggal check-in dan panjang masa inap mereka.

  • Rentang tanggal check-in: Menentukan rentang check-in yang dimulai dengan tanggal check-in pertama dan diakhiri dengan tanggal tanggal check-in.

  • Menginap dengan rentang (atau itinerari dengan rentang)

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

Untuk mengetahui informasi selengkapnya, lihat Pesan Respons Petunjuk.

Sintaksis

Elemen <Hint> menggunakan sintaksis yang berbeda, bergantung pada jenis Petunjuk Pesan respons:

Itinerari pasti

Berikut ini adalah sintaksis untuk itinerari pasti dalam Respons Petunjuk pesan:

<!-- 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 dalam Respons Petunjuk pesan:

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

Dengan rentang menginap

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

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

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

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

Atribut

Elemen <Hint> berisi atribut opsional: id. Kapan asalkan, atribut tersebut disertakan sebagai atribut hintId di <Query> pesan yang dikirim berdasarkan <Hint> ini.

Elemen turunan

Elemen <Hint> memiliki elemen turunan berikut:

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

Tanggal terakhir rentang tanggal untuk rentang check-in atau rentang tetap Respons Petunjuk. Tanggal bersifat inklusif.

* Elemen ini bersifat opsional untuk menginap dengan rentang.
<LengthOfStay> Required integer Itinerari persis Jumlah malam untuk itinerari, yang dinyatakan sebagai positif bilangan bulat.
<Property> Required string Semua

ID hotel, yang menggunakan ID yang sama seperti Daftar Hotel. Nomor dari <Property> elemen yang dapat Anda tetapkan dalam satu Blok <Item> ditentukan berdasarkan jenis Petunjuk Pesan respons:

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

Contoh

Itinerari pasti

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

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

Dengan rentang menginap

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>

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

<HintRequest>

Elemen root pesan Permintaan Petunjuk. Google mengirimkan Permintaan Petunjuk ke server Anda dan mengharapkan respons yang menentukan hotel dan itinerari yang harganya telah berubah sejak terakhir kali Google menerima Respons Petunjuk 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 Saat terakhir kali Google berhasil mendapatkan pesan Respons Petunjuk ke pesan Permintaan Petunjuk.

Jika waktu ini lebih lama dari terakhir kali Anda memperbarui harga di server, Anda harus merespons dengan memberikan Petunjuk Pesan respons yang menentukan hotel yang telah berubah.

Jika belum ada pengambilan yang berhasil baru-baru ini, ini akan disetel ke nilai interval tetap (untuk menghindari masalah yang lebih serius dengan backlog). Nilai interval tetap saat ini adalah 1000 detik, tetapi dapat berubah sewaktu-waktu.

Untuk mengetahui informasi selengkapnya, baca Pesan Respons Petunjuk.

Contoh

Contoh berikut menampilkan pesan Permintaan Petunjuk:

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 Query. Query pesan adalah permintaan dari Google untuk pembaruan harga atau metadata. Model ini digunakan dengan model pull dan Harga yang diubah mode pengiriman.

Ada tiga jenis pesan Query:

  • Harga real time: Google merespons permintaan pengguna tertentu, yaitu dengan meminta pembaruan harga real-time. Saat menerima pesan Live pricing query, partner harus merespons dengan pesan <Transaction> yang berisi informasi harga yang diminta di elemen <Result>.

  • Dengan harga berdasarkan konteks: Google memperbarui cache harganya berdasarkan konteks yang populer secara historis. Saat Anda menerima With context query Anda, Anda harus membalas dengan pesan <Transaction> yang berisi meminta informasi harga di elemen <Result>.

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

Untuk mengetahui informasi selengkapnya, baca Ringkasan harga untuk kueri harga dan metadata Paket Kamar untuk kueri metadata.

Tiga jenis sintaks yang berbeda adalah sebagai berikut:

Sintaksis

Elemen <Query> menggunakan sintaksis berikut:

Harga real time

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

Dengan konteks

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

Metadata

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

Atribut

Elemen <Query> dapat berisi satu atribut: latencySensitive.

Atribut latencySensitive bersifat opsional. Jika disediakan dan ditetapkan ke true, menunjukkan bahwa kuerinya adalah Live Pricing Query. Agar Google dapat mengirimkan kueri dengan atribut latencySensitive, hubungi Manajer Akun Teknis (TAM) Anda.

Elemen turunan

Elemen <Query> memiliki elemen turunan berikut:

Elemen Turunan Jenis Kueri Jenis Deskripsi
<AffectedNights> Pricing integer Jumlah malam untuk menginap dengan rentang. Elemen ini hanya digunakan untuk kueri harga Menginap dengan Rentang yang digunakan dengan Harga yang Diubah.
<Checkin> Pricing Date Tanggal perubahan harga tertentu.
<Context> Pricing (Live Pricing Queries only) <Context> Untuk Kueri Harga Real Time, tentukan parameter tertentu yang menjadi dasar kueri dibuat. Elemen turunan meliputi:
  • <Occupancy>: jumlah total tamu
  • <OccupancyDetails>: jenis tamu, seperti orang dewasa atau anak-anak
  • <UserCountry>: negara tempat pengguna berada ditemukan
  • <UserDevice>: jenis perangkat yang digunakan tamu untuk menelusuri hotel, misalnya "mobile," "tablet", atau "desktop".

Elemen <Context> dapat diulang dalam permintaan tunggal, yang memungkinkan kueri untuk jumlah tamu yang berbeda. Konsultasi <Context> untuk daftar elemen turunan, sintaksis, dan contoh.
<FirstDate> Pricing Date Tanggal mulai untuk rentang itinerari saat harga ditetapkan berlaku. Elemen ini hanya digunakan untuk harga Rentang Tanggal Check-in kueri 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 Query metadata. Elemen ini dapat berisi satu atau beberapa <Property> elemen yang menentukan ID properti hotel.
<LastDate> Pricing Date Tanggal akhir untuk rentang itinerari saat harga diterapkan. Elemen ini hanya digunakan untuk harga Rentang Tanggal Check-in kueri yang digunakan dengan Pull + Hints.
<Nights> Pricing integer Jumlah malam untuk itinerari tertentu, maksimal 30.
<PropertyList> Pricing Object

Satu atau beberapa ID untuk hotel yang memerlukan pembaruan harga.

Tentukan setiap hotel di 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 menunjukkan 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>2023-05-23</Checkin>
  <Nights>3</Nights>
  <PropertyList>
    <Property>pid5</Property>
    <Property>pid8</Property>
    <Property>pid13</Property>
    <Property>pid21</Property>
  </PropertyList>
</Query>

Kueri harga real time

Contoh berikut menunjukkan Kueri Harga Real Time dengan waktu respons batas 500 md:

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

Dengan kueri konteks

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

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 rentang tanggal menginap dan rentang tanggal check-in kueri harga, lihat contoh pesan Query.

<Context>

Elemen <Context> menjelaskan informasi untuk Live pricing query, 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, berikan harga setiap jumlah tamu sebagai Paket Kamar tambahan untuk properti atau itinerari yang sesuai. Setiap properti atau 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> Pricing integer Menentukan jumlah total tamu.

Meskipun tidak wajib, kueri dengan <Occupancy> harus menghasilkan pesan transaksi dengan Paket Kamar yang sesuai ditentukan untuk setiap <Occupancy>, tetapi jika Paket Kamar tidak tersedia, sebaiknya Anda menentukan Elemen <Occupancy>.

Catatan:<Occupancy> mungkin tidak selalu muncul dalam kueri. Dalam kasus tersebut, Anda harus menampilkan harga semua jumlah tamu.
<OccupancyDetails> Pricing Object Didahului oleh <Occupancy>. Menentukan tamu menurut {i>type<i}, termasuk:
  • <NumAdults>: jumlah tamu dewasa
  • <Children> dan <Child="age">: Menentukan tamu anak-anak (biasanya berusia 0-17 tahun), dan secara opsional mencakup usia setiap anak.

Meskipun tidak wajib, kueri yang berisi <OccupancyDetails> akan menghasilkan pesan transaksi dengan Paket Kamar yang sesuai yang ditentukan untuk setiap <Occupancy>, tetapi jika Paket Kamar tidak tersedia, sebaiknya tentukan elemen <OccupancyDetails>.

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

Memfilter tarif berdasarkan negara tempat pengguna berada. Nilainya adalah Kode negara 2 huruf seperti "US" untuk Amerika Serikat, atau Kode wilayah, seperti "EU" untuk "Eropa".

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

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

  • mobile
  • desktop
  • tablet

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

Contoh

Kehadiran

Contoh berikut menunjukkan kueri Harga real time untuk <Occupancy> dalam <Context>. Kueri harga real time adalah untuk 3 orang dewasa tamu.

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

Contoh berikut menunjukkan kueri Harga real time dengan <OccupancyDetails> di <Context>. Kueri harga real time adalah untuk 4 tamu, 2 di antaranya adalah anak-anak dan meminta tarif yang berlaku untuk pemesanan tamu di 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>

Berbagai konteks

Contoh berikut menunjukkan penggunaan elemen <Context> tambahan di 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>