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 Hint response. Les messages Hint response spécifient les combinaisons d'hôtels ou de séjours dont les tarifs doivent être mis à jour. Il s'agit de votre réponse à un message Hint request de Google.

Un message Hint response 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 vos serveurs.

Les messages Hint response utilisent l'une des méthodes suivantes pour spécifier les hôtels et les séjours dont les prix doivent être modifiés sur Google:

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

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

  • Séjours inclus dans une période

Chacune de ces méthodes nécessite une syntaxe différente pour le message Hint response.

Pour en savoir plus, consultez la page Messages Hint response.

Syntaxe

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

Séjours exacts

Voici la syntaxe des séjours exacts dans un message Hint response:

<!-- 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 de dates d'arrivée

Voici la syntaxe des plages d'arrivée dans un message Hint response:

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

Séjours inclus dans une période

Voici la syntaxe des séjours inclus dans une période dans un message Hint response:

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

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 Obligatoire ? Type Type de réponse d'indication Description
<CheckInDate> Required Date Séjours exacts Date d'arrivée pour le séjour.
<FirstDate> Required Date Plages de dates d'arrivée et séjours inclus dans une période Première date de la plage dans un message Hint response de plage de dates d'arrivée ou de séjours inclus dans une période. Les dates sont incluses.
<Item> Required Object Tous Conteneur de l'hôtel/du séjour à mettre à jour.
<LastDate> Required* Date Plages de dates d'arrivée et séjours inclus dans une période

Dernière date de la plage dans un message Hint response de plage de dates 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 sous forme d'entier positif.
<Property> Required string Tous

ID de l'hôtel, qui apparaît 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 de dates d'arrivée: plusieurs éléments si vous définissez <MultipleItineraries> sur "checkin_range" dans votre message <QueryControl>.
  • Séjours inclus dans une période: plusieurs éléments 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 élément <Item> ne peut contenir qu'un seul élément <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 Hint response:

<!-- 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 de dates d'arrivée

L'exemple suivant spécifie deux hôtels dont les prix ont changé et doivent être extraits à nouveau. Google extrait tous les séjours allant du 3 au 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>

Séjours inclus dans une période

L'exemple suivant illustre deux utilisations différentes des séjours inclus dans une période : un séjour avec une plage de plusieurs nuits et un autre d'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>

Pour chacun de ces exemples, Google répond par un message <Query>. Vous devez ensuite renvoyer un message <Transaction> incluant les mises à jour des prix pour les hôtels/séjours indiqués.

<HintRequest>

Élément racine d'un message Hint request. Google envoie un message Hint request à votre serveur. Il 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 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 la page 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 obtenu un message Hint response suite à un message Hint request.

Si cette date est antérieure à la dernière fois où vous avez modifié les prix sur votre serveur, vous devez répondre en envoyant un message Hint response. Celui-ci doit préciser les hôtels dont les prix ont été modifiés.

Si aucune récupération récente n'a réussi, cette valeur est définie sur une valeur d'intervalle fixe (pour éviter les problèmes plus graves liés aux longs retards). 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 la page Messages Hint response.

Exemples

L'exemple suivant présente un message Hint request:

Message Hint request

L'exemple suivant présente un 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 la mise à jour de vos tarifs et de vos métadonnées. Ils sont utilisés avec les modes d'envoi Pull et Requête de prix modifiés.

Messages de requête de prix

Les messages de requête de prix spécifient les combinaisons d'établissement et de séjour pour lesquelles vous devez fournir des prix.

Lorsque votre serveur reçoit un message de requête de prix, il doit renvoyer un message <Transaction> comportant les informations tarifaires requises.

Pour en savoir plus, consultez Présentation des tarifs.

Il existe trois types de messages Query spéciaux:

  • Prix en temps réel:Google répond à une demande spécifique d'un utilisateur, qui demande une mise à jour des prix en temps réel. Lorsque les partenaires reçoivent un message Live pricing query, ils doivent répondre par un message <Transaction> contenant les informations tarifaires demandées dans des éléments <Result>.

  • Avec les tarifs basés sur le contexte:Google met à jour son cache de prix en fonction des contextes historiquement populaires. Lorsque vous recevez un message With context query, vous devez répondre avec un message <Transaction> contenant les informations tarifaires demandées dans des éléments <Result>.

  • Métadonnées:Google demande les mises à 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 répondre par un message <Transaction> spécifiant les données sur les chambres et les offres de chambres dans des éléments <PropertyDataSet>. Pour en savoir plus, consultez la section Métadonnées des offres de chambres.

Syntaxe

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

Requête sur les prix

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

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. S'il est fourni et défini sur true, il indique qu'il s'agit d'une Live Pricing Query. Pour que Google envoie des requêtes avec l'attribut latencySensitive, contactez votre responsable de compte technique.

É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 des séjours inclus dans une période en 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. Éléments enfants :
  • <Occupancy>: nombre total de clients
  • <OccupancyDetails>: type de clients, par exemple les adultes ou les enfants
  • <UserCountry>: pays où se trouve l'utilisateur
  • <UserDevice>: type d'appareil utilisé par le client pour rechercher un hôtel, tel que "mobile, tablet ou desktop

L'élément <Context> peut être répété dans une même requête, ce qui permet d'utiliser des requêtes pour différents nombres de personnes. Consultez la section <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 en 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 Query sur les métadonnées. Cet élément peut contenir un ou plusieurs éléments <Property> spécifiant les ID d'établissement des hôtels.
<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 sur les prix d'une plage de dates d'arrivée en mode Pull with Hints.
<Nights> Pricing integer Nombre de nuits pour un séjour donné (jusqu'à 30).
<PropertyList> Pricing Object

Un ou plusieurs ID pour les hôtels qui nécessitent une mise à jour des prix.

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

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

Exemples

Requête sur les prix

L'exemple suivant illustre un message de requête sur les prix qui demande la mise à jour des prix d'un ensemble d'hôtels, disponibles pendant trois nuits à compter du 23 mai 2023:

<?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 dont le temps de réponse est 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 une requête de contexte

<?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 plus d'exemples, en particulier sur les requêtes sur les prix avec séjour inclus dans une période et plage de dates d'arrivée, consultez les exemples de messages Query.

<Context>

L'élément <Context> décrit les informations relatives à un Live pricing query, comme le nombre et le type de clients, le pays de l'utilisateur et l'appareil de l'utilisateur.

Vous ne pouvez pas utiliser plusieurs éléments <Context> avec des pays ou des appareils différents. Lorsque plusieurs éléments <Context> sont utilisés pour rechercher divers nombres de personnes, fournissez le prix associé à chaque nombre en tant qu'offre de chambres supplémentaire pour l'établissement ou le séjour correspondant. Chaque établissement ou séjour doit comporter un seul bloc <Result> avec les prix des différents nombres de personnes.

Pour en savoir plus sur la réponse à la requête <Context>, consultez la section <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 Indique le nombre total de clients.

Bien que cela ne soit pas obligatoire, les requêtes avec <Occupancy> devraient renvoyer un message de transaction contenant les offres de chambres appropriées définies pour chaque élément <Occupancy>. Toutefois, si les offres de chambres ne sont pas disponibles, il est recommandé de spécifier l'élément <Occupancy>.

Remarque:<Occupancy> peut ne pas toujours apparaître 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 clients par type, y compris :
  • <NumAdults>: nombre d'adultes
  • <Children> et <Child="age"> : définissent les enfants (généralement de 0 à 17 ans), et incluent éventuellement l'âge de chaque enfant.

Bien que cela ne soit pas obligatoire, les requêtes avec <OccupancyDetails> devraient renvoyer un message de transaction contenant les offres de chambres appropriées définies pour chaque élément <Occupancy>. Toutefois, si les offres de chambres ne sont pas disponibles, nous vous recommandons de spécifier l'élément <OccupancyDetails>.

Remarque : <OccupancyDetails> peut ne pas toujours apparaître dans une requête. Dans ce cas, vous devez considérer que tous les clients sont des adultes.
<UserCountry> Pricing string

Filtre les tarifs en fonction du pays où se trouve l'utilisateur. Sa valeur est 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 concerné par la requête.
<UserDevice> Pricing string

Filtre les tarifs en fonction du type d'appareil sur lequel 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 avec le bloc <Rates> approprié 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>

Détails du nombre de personnes

L'exemple suivant présente 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 personnes venant des É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>