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 de demande d'indication, les messages de réponse d'indication et les messages de demande XML.

<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 de demande d'indication envoyé par 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 de vos serveurs.

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

  • 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 comprise entre la première et la dernière date d'arrivée.

  • Séjours inclus dans une période (ou trajets 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 les 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:

Itinéraires 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 de dates 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 Obligatoire ? Type Type de réponse d'indication Description
<CheckInDate> Required Date Itinéraires exacts Date d'arrivée du 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 de réponse d'indication pour une 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 ou 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 de réponse d'indication pour une 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 correspondant au séjour, exprimé en entier positif.
<Property> Required string Tous

Identifiant d'un hôtel, identique à celui de 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 de réponse d'indication:

  • Itinéraires exacts: jusqu'à 100 hôtels.
  • Plages d'arrivée: plusieurs si vous définissez <MultipleItineraries> sur "checkin_range" dans votre message <QueryControl>.
  • Séjour inclus dans la plage: plusieurs éléments si vous définissez <MultipleItineraries> sur "affected_dates" dans votre message <QueryControl>.
<Stay> Required Object Itinéraires exacts Conteneur pour les éléments <CheckinDate> et <LengthOfStay> dans un message de réponse d'indication 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 de réponse d'indication de séjour inclus dans une plage.

Exemples

Itinéraires exacts

L'exemple suivant définit plusieurs séjours pour un même établissement avec 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 de dates 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 obtient tous les séjours entre le 3 et le 6 juillet pour les hôtels 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 propriétés dans un seul <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'un 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 même élément <Item>, la valeur de l'élément <MultipleItineraries> dans <QueryControl> doit être définie sur "affected_dates".

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

<HintRequest>

Élément racine d'un message de demande d'indication. Google envoie un message de demande d'indication à 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 de votre serveur.

Si des prix sont modifiés, Google envoie une notification <Query> qui extrait les données tarifaires mises à jour pour les hôtels et séjours indiqués.

Pour en savoir plus, consultez la section Messages de demande d'indication.

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 de réponse d'indication pour un message de demande d'indication.

Si cette date est antérieure à la dernière mise à jour des prix sur votre serveur, vous devez répondre en envoyant un message de réponse d'indication. Celui-ci indique les hôtels qui ont été modifiés.

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

Exemples

L'exemple suivant présente un message de demande d'indication:

Message de demande d'indication

L'exemple suivant présente un message de demande d'indication:

<?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 envoyées par Google pour la mise à 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 demande d'un utilisateur spécifique et lui demande de mettre à jour les 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 demandées sur les tarifs dans les éléments <Result>.

  • Avec la tarification contextuelle:Google met à jour son cache des prix en fonction des contextes qui sont traditionnellement populaires. Lorsque vous recevez un message With context query, vous devez répondre avec un message <Transaction> contenant les informations de tarification 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 répondre par un message <Transaction> qui spécifie les données sur les chambres et les offres de chambres dans des éléments <PropertyDataSet>.

Pour en savoir plus, consultez la 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>

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 attribut: latencySensitive.

L'attribut latencySensitive est facultatif. Lorsqu'elle est fournie et définie sur true, elle 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 pour un séjour inclus dans une période. Cet élément n'est utilisé que pour les requêtes de prix en séjours inclus dans une 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. Les éléments enfants sont les suivants :
  • <Occupancy>: nombre total d'invités
  • <OccupancyDetails>: type de client, tel qu'un adulte ou un enfant
  • <UserCountry>: pays où se trouve l'utilisateur.
  • <UserDevice>: type d'appareil utilisé par l'invité pour rechercher un hôtel, tel que "mobile, "tablet" ou "desktop".

L'élément <Context> peut être répété dans une seule requête, ce qui permet d'exécuter des requêtes portant sur différents nombres de personnes. Consultez <Context> pour obtenir la liste des éléments enfants, la syntaxe et les 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 de prix liées à la plage de dates d'arrivée utilisées avec la 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> qui spécifient des ID d'établissement hôtelier.
<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 de prix liées à la plage de dates d'arrivée en mode 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 nécessitant de mettre à jour les 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 de prix

L'exemple suivant présente un message de requête de prix demandant des mises à jour des prix pour un ensemble d'hôtels, disponible 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 de prix en temps réel

L'exemple suivant montre une requête de 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 de contexte

<?xml version="1.0" encoding="UTF-8"?>
<Query>
  <Checkin>2017-07-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 concernant les tarifs pour des séjours inclus dans des plages et des dates d'arrivée, consultez les exemples de messages Query.

<Context>

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

Plusieurs <Context> ne seront jamais utilisés avec différents pays ou appareils. Lorsque plusieurs <Context> sont utilisés pour envoyer une requête pour plusieurs nombres de personnes, veuillez fournir chaque prix d'occupation sous forme d'offre de chambres supplémentaire pour l'établissement ou le séjour correspondant. Chaque établissement/séjour doit comporter un seul bloc <Result> avec les prix correspondant à plusieurs nombres de personnes.

Pour en savoir plus sur 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 Indique le nombre total d'invités.

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

Remarque:<Occupancy> peut ne pas toujours apparaître dans une requête. Dans ce cas, vous devez afficher les prix de toutes les biens.
<OccupancyDetails> Pricing Object est précédé de <Occupancy>. Spécifie les invités par type, y compris:

  • <NumAdults>: nombre de clients adultes
  • <Children> et <Child="age"> : spécifient 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 générer un message de transaction avec les offres de chambres appropriées définies pour chaque <Occupancy> interrogé.

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

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

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

Filtrer les tarifs en fonction du type d'appareil sur lequel l'utilisateur effectue sa recherche. Les valeurs possibles sont :

  • mobile
  • desktop
  • tablet

Les requêtes pour lesquelles <UserDevice> est défini doivent renvoyer 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 est réservée à 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 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 sont des enfants, et recherche un tarif applicable à une réservation de clients 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 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>