Documentation de référence XML sur les requêtes et les indications

Cette section fournit une documentation de référence pour les messages Hint request, les messages Hint response et les messages Query.

<Hint> (message de réponse d'indication)

Élément racine d'un message de réponse d'indication. Les messages de réponse d'indication indiquent les combinaisons hôtel/séjour dont les tarifs doivent être mis à jour. Il s'agit de votre réponse à un message Hint request de Google.

Un message de réponse d'indication ne doit spécifier que les hôtels dont les prix ont changé depuis la dernière fois que Google a reçu une réponse d'indication réussie de la part de vos serveurs.

Les messages de réponse d'indication utilisent l'une des méthodes suivantes pour spécifier les hôtels et les séjours dont les prix doivent être modifiés:

  • Séjours exacts: combinaison de la date d'arrivée et de la durée du séjour.

  • Plages de dates d'arrivée: plage de dates d'arrivée, allant de la première à la dernière.

  • Séjours inclus dans une période (ou séjours inclus dans une période)

Chacune de ces méthodes nécessite une syntaxe différente pour le message de réponse d'indication.

Pour en savoir plus, consultez la section Messages de réponse d'indication.

Syntaxe

L'élément <Hint> utilise une syntaxe différente, en fonction du type de message de réponse d'indication:

Séjours exacts

Voici la syntaxe des séjours exacts dans un message de réponse d'indication:

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

Plages d'arrivée

Voici la syntaxe des plages d'arrivée dans un message de réponse d'indication:

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

Séjours inclus dans une période

Voici la syntaxe des séjours inclus dans une période dans un message de réponse d'indication:

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

Attributs

L'élément <Hint> contient un attribut facultatif: id. Lorsqu'il est fourni, il est inclus en tant qu'attribut hintId dans les messages <Query> envoyés en fonction de ce <Hint>.

Éléments enfants

L'élément <Hint> comporte les éléments enfants suivants :

Élément enfant Requis ? Type Type de réponse d'indication Description
<CheckInDate> Required Date Séjours exacts Date d'arrivée pour l'itinéraire.
<FirstDate> Required Date Plages de dates d'arrivée et itinéraires inclus dans une période Première date de la plage de dates d'un message Hint response de plage d'arrivée ou de séjours inclus dans une période. Les dates sont incluses.
<Item> Required Object Toutes Conteneur pour l'hôtel/le séjour à mettre à jour.
<LastDate> Required* Date Plages de dates d'arrivée et itinéraires inclus dans une période

Dernière date de la plage de dates d'un message Hint response de plage d'arrivée ou de séjours inclus dans une période. Les dates sont incluses.

* Cet élément est facultatif pour les séjours inclus dans une période.
<LengthOfStay> Required integer Séjours exacts Nombre de nuits pour le séjour, exprimé sous la forme d'un entier positif.
<Property> Required string Toutes

Identifiant d'un hôtel, qui doit être identique à celui figurant dans la liste d'hôtels. Le nombre d'éléments <Property> que vous pouvez spécifier dans un seul bloc <Item> est déterminé par le type de message Hint response:

  • Séjours exacts: jusqu'à 100 hôtels.
  • Plages d'arrivée: plusieurs si vous définissez <MultipleItineraries> sur "checkin_range" dans votre message <QueryControl>.
  • Séjours inclus dans une période: plusieurs si vous définissez <MultipleItineraries> sur "affected_dates" dans votre message <QueryControl>.
<Stay> Required Object Séjours exacts Conteneur pour les éléments <CheckinDate> et <LengthOfStay> dans un message Hint response de séjour exact. Chaque <Item> ne peut contenir qu'un seul <Stay>.
<StaysIncludingRange> Required Object Séjours inclus dans une période Conteneur pour les éléments <FirstDate> et <LastDate> dans un message Hint response de séjour inclus dans une période.

Exemples

Séjours exacts

L'exemple suivant définit plusieurs séjours pour un même établissement dans un message de réponse d'indication:

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

Plages d'arrivée

L'exemple suivant spécifie deux hôtels dont les prix ont changé et doivent être récupérés à nouveau. Google récupère tous les séjours entre le 3 et le 6 juillet pour les établissements 12345 et 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>

Notez que pour qu'un message de plage d'arrivée puisse spécifier plusieurs établissements dans un seul élément <Item>, la valeur de <MultipleItineraries> dans <QueryControl> doit être définie sur "checkin_range".

Séjours inclus dans une période

L'exemple suivant présente deux utilisations différentes de séjours inclus dans une période, l'une pour une plage de nuits et l'autre pour une seule nuit:

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

Notez que pour qu'un message de séjour inclus dans une période puisse spécifier plusieurs établissements dans un seul élément <Item>, la valeur de <MultipleItineraries> dans <QueryControl> doit être définie sur "affected_dates".

Pour chacun de ces exemples, Google répond avec un <Query>. Vous devez ensuite répondre avec un <Transaction> qui inclut les mises à jour des prix pour les hôtels/séjours spécifiés.

<HintRequest>

Élément racine d'un message Hint request. Nous envoyons un message Hint request à votre serveur et attend une réponse spécifiant les hôtels et les séjours dont les prix ont changé depuis la dernière fois que Google a reçu une réponse d'indication réussie de la part de votre serveur.

En cas de changement de prix, Google envoie un message <Query> qui extrait les données tarifaires mises à jour pour les hôtels et séjours indiqués.

Pour en savoir plus, consultez Messages Hint request.

Syntaxe

L'élément <HintRequest> utilise la syntaxe suivante :

Syntaxe

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

Attributs

L'élément <HintRequest> ne comporte aucun attribut.

Éléments enfants

L'élément <HintRequest> comporte les éléments enfants suivants :

Élément enfant Type Description
<LastFetchTime> DateTime Dernière fois que Google a reçu un message Hint response suite à un message Hint request.

Si cette date est antérieure à la dernière fois que vous avez modifié les prix sur votre serveur, vous devez répondre avec un message de réponse d'indication indiquant les hôtels qui ont changé.

Si aucune récupération récente n'a réussi, cette valeur sera définie sur une valeur d'intervalle fixe (pour éviter les problèmes plus graves avec des tâches en attente volumineuses). La valeur actuelle de l'intervalle fixe est de 1 000 secondes, mais elle est susceptible d'être modifiée.

Pour en savoir plus, consultez Messages de réponse d'indication.

Exemples

Voici un exemple de message Hint request:

Message Hint request

Voici un exemple de message Hint request:

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

Élément racine d'un message Query. Les messages Query sont des requêtes que Google vous envoie pour mettre à jour des prix ou des métadonnées. Ils sont utilisés avec les modes d'envoi Pull et Requête de prix modifiés.

Il existe trois types de messages Query:

  • Requête de prix en temps réel:Google répond à la requête spécifique d'un utilisateur pour demander une mise à jour du prix en temps réel. Lorsqu'ils reçoivent un message Live pricing query, ils doivent y répondre avec un message <Transaction> contenant les informations tarifaires demandées dans les éléments <Result>.

  • Avec la tarification contextuelle:Google met à jour son cache de prix en fonction des contextes historiquement populaires. Lorsque vous recevez un message With context query, vous devez renvoyer un message <Transaction> contenant les informations tarifaires demandées dans les éléments <Result>.

  • Métadonnées:Google demande la mise à jour des métadonnées des chambres et des offres de chambres pour les hôtels spécifiés. Lorsque vous recevez un message Metadata Query, vous devez renvoyer un message <Transaction> contenant des données sur les chambres et les offres de chambres dans les éléments <PropertyDataSet>.

Pour en savoir plus, consultez la page Présentation des tarifs pour les requêtes de prix et les Métadonnées des offres de chambres pour les requêtes de métadonnées.

La syntaxe des trois types différents est décrite ci-dessous.

Syntaxe

L'élément <Query> utilise la syntaxe suivante :

Requête de prix en temps réel

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

Avec contexte

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

Métadonnées

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

Attributs

L'élément <Query> peut contenir un seul attribut: latencySensitive.

L'attribut latencySensitive est facultatif. Lorsqu'il est fourni et défini sur true, il indique que la requête est de type Live Pricing Query. Pour que Google envoie des requêtes avec l'attribut latencySensitive, veuillez contacter votre responsable de compte technique (TAM).

Éléments enfants

L'élément <Query> comporte les éléments enfants suivants :

Élément enfant Type de requête Type Description
<AffectedNights> Pricing integer Nombre de nuits d'un séjour inclus dans une période. Cet élément n'est utilisé que pour les requêtes de prix de séjours inclus dans une période avec le mode Requête de prix modifiés.
<Checkin> Pricing Date Dates d'un changement de prix spécifique.
<Context> Pricing (Live Pricing Queries only) <Context> Pour les requêtes de prix en temps réel, spécifie certains paramètres sous lesquels la requête est effectuée. Voici les différents éléments enfants :
  • <Occupancy>: nombre total d'invités
  • <OccupancyDetails>: type de clients (par exemple, adultes ou enfants)
  • <UserCountry>: pays où se trouve l'utilisateur
  • <UserDevice>: type d'appareil utilisé par le client pour rechercher un hôtel (par exemple, "mobile, tablet ou desktop).

L'élément <Context> peut être répété dans une seule requête, ce qui permet d'effectuer des requêtes pour différents nombres de personnes. Consultez <Context> pour obtenir la liste des éléments enfants, la syntaxe et des exemples.
<FirstDate> Pricing Date Date de début d'un ensemble de séjours auxquels les prix s'appliquent. Cet élément n'est utilisé que pour les requêtes sur les prix d'une plage de dates d'arrivée avec le mode Requête de prix modifiés.
<HotelInfoProperties> Metadata string Un ou plusieurs établissements pour lesquels Google souhaite mettre à jour les métadonnées des chambres et des offres de chambres dans un message de métadonnées Query. Cet élément peut contenir un ou plusieurs éléments <Property> spécifiant les ID d'établissements hôteliers.
<LastDate> Pricing Date Date de fin d'un ensemble de séjours auxquels les prix s'appliquent. Cet élément n'est utilisé que pour les requêtes concernant les prix d'une plage de dates d'arrivée avec le mode d'envoi Pull + Hints.
<Nights> Pricing integer Nombre de nuits pour un séjour donné (jusqu'à 30).
<PropertyList> Pricing Object

Un ou plusieurs identifiants d'hôtels pour lesquels les prix doivent être mis à jour.

Définissez chaque hôtel dans un élément <Property>. Cette valeur est une chaîne correspondant à un identifiant d'hôtel dans votre liste d'hôtels. Par exemple :

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

Exemples

Requête de prix

L'exemple suivant illustre un message de requête de prix qui demande la mise à jour des prix d'un ensemble d'hôtels, disponibles pendant trois nuits et à partir du 10 juin 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>

Requête de prix en temps réel

L'exemple suivant présente une requête de prix en temps réel avec un temps de réponse limité à 500 millisecondes:

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

Avec requête contextuelle

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

Requête de métadonnées

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

Pour obtenir d'autres exemples, y compris des requêtes sur les tarifs de séjours inclus dans une période et d'une plage de dates d'arrivée, consultez les exemples de messages Query.

<Context>

L'élément <Context> décrit les informations concernant une Live pricing query, y compris le nombre et le type d'invités, le pays de l'utilisateur et l'appareil de l'utilisateur.

Plusieurs <Context> ne seront jamais utilisés avec des pays ou des appareils utilisateur différents. Lorsque plusieurs valeurs <Context> sont utilisées pour rechercher plusieurs nombres de personnes, veuillez indiquer chaque prix en tant qu'offre de chambres supplémentaire pour l'établissement/le séjour correspondant. Chaque établissement/séjour doit comporter un seul bloc <Result> avec les prix des différents nombres de personnes.

Pour obtenir les détails de la réponse à la requête <Context>, consultez <OccupancyDetails>.

Syntaxe

L'élément <Context> utilise la syntaxe suivante :

Syntaxe

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

Éléments enfants

L'élément <Context> comporte les éléments enfants suivants :

Élément enfant Type de requête Type Description
<Occupancy> Pricing integer Spécifie le nombre total de clients.

Bien que cela ne soit pas obligatoire, les requêtes avec <Occupancy> doivent générer un message Transaction contenant les offres de chambres appropriées définies pour chaque élément <Occupancy> interrogé.

Remarque:<Occupancy> n'apparaît pas toujours dans une requête. Dans ce cas, vous devez renvoyer les prix pour tous les nombres de personnes.
<OccupancyDetails> Pricing Object Est précédé de <Occupancy>. Spécifie les invités par type, y compris:

  • <NumAdults>: nombre d'adultes
  • <Children> et <Child="age"> : précisent quels sont les enfants (généralement de 0 à 17 ans), et inclut éventuellement l'âge de chaque enfant.

    • Bien que cela ne soit pas obligatoire, les requêtes avec <OccupancyDetails> doivent générer un message Transaction contenant les offres de chambres appropriées définies pour chaque élément <Occupancy> interrogé.

    Remarque : <OccupancyDetails> n'apparaît pas toujours dans une requête. Dans ce cas, vous devez partir du principe que tous les clients sont des adultes.
<UserCountry> Pricing string

Filtre les tarifs en fonction du pays où se trouve l'utilisateur. Sa valeur correspond à un code pays à deux lettres, comme “US” pour les États-Unis, ou à un code de région, comme "EU" pour "Europe".

Les requêtes pour lesquelles <UserCountry> est défini doivent générer un message Transaction dans lequel le bloc <Rates> approprié est défini pour le pays interrogé.
<UserDevice> Pricing string

Filtre les tarifs en fonction du type d'appareil à partir duquel l'utilisateur effectue sa recherche. Valeurs possibles :

  • mobile
  • desktop
  • tablet

Les requêtes pour lesquelles <UserDevice> est défini doivent générer un message Transaction dans lequel le bloc <Rates> approprié est défini pour le type d'appareil interrogé.

Exemples

Nombre de personnes

L'exemple suivant présente une requête de prix en temps réel pour <Occupancy> dans <Context>. La requête de prix en temps réel concerne trois adultes.

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

Informations sur le nombre de personnes

L'exemple suivant montre une requête de prix en temps réel avec <OccupancyDetails> dans <Context>. La requête de prix en temps réel concerne quatre personnes, dont deux enfants, et recherche un tarif applicable à une réservation de client aux États-Unis depuis un appareil mobile:

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

Contextes multiples

L'exemple suivant illustre l'utilisation d'un élément <Context> supplémentaire dans une requête de prix en temps réel.

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