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 Hint response)

Élément racine d'un message Hint response. Les messages Hint response spécifient 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 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 -->
    <!-- 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 Hint response :

<!-- 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> ne comporte aucun attribut.

Éléments enfants

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

Élément enfant Valeur requise ? Type Type de réponse d'indication Description
<CheckInDate> Obligatoire Date Séjours exacts Date d'arrivée pour le séjour.
<FirstDate> Obligatoire 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> Obligatoire Objet Tout Conteneur de l'hôtel/du séjour à mettre à jour.
<LastDate> Obligatoire* 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> Obligatoire Entier Séjours exacts Nombre de nuits pour le séjour sous forme d'entier positif.
<Property> Obligatoire Chaîne Tout 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> Obligatoire Objet 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> Obligatoire Objet 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>

Notez que pour qu'un message de plage de dates d'arrivée puisse spécifier plusieurs établissements dans un même é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 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>

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

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.

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

Exemples

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.

Il existe deux types de messages Query :

  • Prix : Google demande la mise à jour des prix des hôtels spécifiés. Lorsque vous recevez un message Query sur les prix, vous devez répondre avec un message <Transaction> contenant les informations tarifaires demandées dans des éléments <Result>.

    Les requêtes de prix en temps réel constituent un type particulier de message Query sur les prix dans lequel Google vous demande des mises à jour de prix en temps réel.

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

  • 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 Query sur les métadonnées, 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.

La syntaxe des messages varie selon le type. Les deux types sont décrits dans cette section.

Syntaxe

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

Syntaxe

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

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 requête de prix en temps réel. Pour que Google envoie des requêtes avec l'attribut <LatencySensitive>, envoyez une demande à 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> Prix Entier 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> Prix Date Dates d'un changement de prix spécifique.
<Context> Prix (requêtes de prix en temps réel uniquement) Objet 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> Prix 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> Métadonnées Chaîne 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> Prix 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> Prix Entier Nombre de nuits pour un séjour donné (jusqu'à 30).
<PropertyList> Prix Objet 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 10 juin 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>

Requête sur les métadonnées

L'exemple suivant illustre un message Query sur les 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 à une requête de prix en temps réel, 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/le séjour correspondant. Chaque établissement/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> Prix Entier Indique le nombre total de clients.

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

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> Prix Objet Est précédé de <Occupancy>. Spécifie les clients par type :

  • <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 Transaction contenant les offres de chambres appropriées définies pour chaque élément <Occupancy> interrogé.

    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> Prix Chaîne

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> Prix Chaîne

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>