Consulta de XML de sugerencias y consultas

En esta sección, se proporciona una referencia para los mensajes de solicitud de sugerencia, los mensajes de respuesta de sugerencia y los mensajes de consulta basados en XML de Google.

<Hint> (mensaje de respuesta de sugerencia)

Es el elemento raíz de un mensaje de respuesta de sugerencia. Los mensajes de respuesta de sugerencia especifican para qué combinaciones de hotel o itinerario se debe cambiar el precio. Son tu respuesta a un mensaje de solicitud de sugerencia de Google.

Un mensaje de respuesta a una sugerencia debe especificar solo aquellos hoteles cuyos precios cambiaron desde la última vez que Google recibió una respuesta de sugerencia correcta de tus servidores.

Los mensajes de respuesta de sugerencias usan uno de los siguientes métodos para especificar los itinerarios y hoteles a los que Google debería cambiar el precio:

  • Itinerarios exactos: Una combinación de fecha de entrada y duración de la estadía.

  • Períodos de entrada: Especifica un rango de fechas de entrada, que comienza con la primera fecha de entrada y termina con la última fecha de entrada.

  • Estadías por intervalos (o itinerarios intervalos)

Cada uno de estos métodos requiere una sintaxis diferente para el mensaje de respuesta de sugerencia.

Para obtener más información, consulta los mensajes de respuesta de sugerencia.

Sintaxis

El elemento <Hint> usa una sintaxis diferente, según el tipo de mensaje de respuesta de sugerencia:

Itinerarios exactos

A continuación, se muestra la sintaxis de itinerarios exactos en un mensaje de respuesta a una sugerencia:

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

Rangos de check-in

A continuación, se muestra la sintaxis de los rangos de registro en un mensaje de respuesta de sugerencia:

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

Estadías a distancia

A continuación, se muestra la sintaxis de los rangos de intervalo en un mensaje de respuesta a una sugerencia:

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

Atributos

El elemento <Hint> contiene un atributo opcional: id. Cuando se proporciona, se incluye como el atributo hintId en los mensajes <Query> enviados según este <Hint>.

Elementos secundarios

El elemento <Hint> tiene los siguientes elementos secundarios:

Elemento secundario ¿Es obligatoria? Tipo Tipo de respuesta de sugerencia Descripción
<CheckInDate> Required Date Itinerarios exactos La fecha de entrada del itinerario.
<FirstDate> Required Date Itinerarios a distancia y rangos de check-in Es la primera fecha del período correspondiente a un período de registro o mensaje de respuesta de sugerencias de estadía. Las fechas son inclusivas.
<Item> Required Object Todas Es un contenedor para el hotel o itinerario que se actualizará.
<LastDate> Required* Date Itinerarios a distancia y rangos de check-in

La última fecha del período correspondiente a un período de registro o mensaje de respuesta de sugerencias de estadía. Las fechas son inclusivas.

* Este elemento es opcional para estadías de distancia.

<LengthOfStay> Required integer Iterarios exactos Es la cantidad de noches del itinerario, expresada como un número entero positivo.
<Property> Required string Todas

Es el ID de un hotel, con el mismo ID que el de la Lista de hoteles. La cantidad de elementos <Property> que puedes especificar en un solo bloque <Item> está determinada por el tipo de mensaje de respuesta de sugerencias:

  • Itinerarios exactos: hasta 100 hoteles
  • Rangos de registro: más de uno si estableces <MultipleItineraries> como "checkin_range" en el mensaje <QueryControl>.
  • Estadía por rango: Más de uno si estableces <MultipleItineraries> como "affected_dates" en tu mensaje <QueryControl>.
<Stay> Required Object Itinerarios exactos Un contenedor para los elementos <CheckinDate> y <LengthOfStay> en un mensaje de respuesta de sugerencia del itinerario exacto. Cada <Item> puede contener un solo objeto <Stay>.
<StaysIncludingRange> Required Object Iterarios de rango Un contenedor para los elementos <FirstDate> y <LastDate> en un mensaje de respuesta de sugerencia por rango permanece.

Ejemplos

Itinerarios exactos

En el siguiente ejemplo, se definen varios itinerarios para una sola propiedad un mensaje de respuesta de sugerencia:

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

Rangos de check-in

En el siguiente ejemplo, se especifican dos hoteles cuyos precios cambiaron y deben recuperarse de nuevo. Google obtiene todos los itinerarios entre el 3 y el 6 de julio para las propiedades 12345 y 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>

Ten en cuenta que, para que un mensaje de rango de registro pueda especificar varias propiedades en un solo <Item>, el valor de <MultipleItineraries> en <QueryControl> se debe establecer en "checkin_range".

Estadías a distancia

En el siguiente ejemplo, se muestran dos usos diferentes de estadías por intervalos: uno para un rango de noches y otro para una sola noche:

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

Ten en cuenta que, para que un mensaje de estadía por rango pueda especificar varias propiedades en un solo <Item>, el valor de <MultipleItineraries> en <QueryControl> se debe establecer en "affected_dates".

Para cada uno de estos ejemplos, Google responde con <Query>, y tú debes responder con una <Transaction> que incluye actualizaciones de precios de los itinerarios o hoteles especificados.

<HintRequest>

Es el elemento raíz de un mensaje de solicitud de sugerencia. Google envía un mensaje de solicitud de sugerencia al servidor y espera una respuesta que especifique los itinerarios y hoteles cuyos precios cambiaron desde la última vez que Google recibió una respuesta de sugerencia correcta de tu servidor.

Si hay algún cambio de precio, Google envía un <Query> que recupera los datos de precios actualizados para los itinerarios y hoteles indicados.

Para obtener más información, consulta los mensajes de solicitud de sugerencias.

Sintaxis

El elemento <HintRequest> usa la siguiente sintaxis:

Sintaxis

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

Atributos

El elemento <HintRequest> no tiene atributos.

Elementos secundarios

El elemento <HintRequest> tiene los siguientes elementos secundarios:

Elemento secundario Tipo Descripción
<LastFetchTime> DateTime La última vez que Google logró recibir un mensaje de respuesta a un mensaje de solicitud de sugerencia.

Si esta hora es anterior a la última vez que actualizaste los precios en tu servidor, debes responder con un mensaje de respuesta a una sugerencia que especifique qué hoteles cambiaron.

Si no se realizó una recuperación correcta recientemente, se establecerá en un valor de intervalo fijo (para evitar problemas más graves con grandes tareas pendientes). El valor actual del intervalo fijo es 1,000 segundos, pero está sujeto a cambios.

Para obtener más información, consulta Mensajes de respuesta de sugerencia.

Ejemplos

En el siguiente ejemplo, se muestra un mensaje de solicitud de sugerencia:

Mensaje de solicitud de sugerencia

En el siguiente ejemplo, se muestra un mensaje de solicitud de sugerencia:

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

Es el elemento raíz de un mensaje Query. Los mensajes Query son solicitudes de Google de actualizaciones de precios o metadatos. Se usan con los modos de entrega de precios modificados y de extracción.

Existen tres tipos de mensajes Query:

  • Precios en tiempo real: Google responde a una solicitud específica de un usuario y solicita una actualización de precios en tiempo real. Cuando los socios reciben un mensaje Live pricing query, deben responder con un mensaje <Transaction> que contenga la información de precios solicitada en los elementos <Result>.

  • Con precios contextuales: Google actualiza la caché de precios en función de los contextos históricamente populares. Cuando recibes un mensaje With context query, debes responder con un mensaje <Transaction> que contenga la información de precios solicitada en los elementos <Result>.

  • Metadatos: Google solicita actualizaciones de metadatos para las habitaciones y los paquetes de habitaciones de los hoteles especificados. Cuando recibes un mensaje Metadata Query, debes responder con un mensaje <Transaction> que especifique los datos sobre las habitaciones y los paquetes de habitaciones en los elementos <PropertyDataSet>.

Para obtener más información, consulta la Descripción general de precios para las consultas de precios y los metadatos de los paquetes de Room para las consultas de metadatos.

A continuación, se describe la sintaxis de los tres tipos diferentes.

Sintaxis

El elemento <Query> usa la siguiente sintaxis:

Precios en tiempo real

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

Con contexto

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

Atributos

El elemento <Query> puede contener un atributo: latencySensitive.

El atributo latencySensitive es opcional. Cuando se proporciona y se establece en true, indica que la consulta es un Live Pricing Query. Para que Google envíe consultas con el atributo latencySensitive, comunícate con tu administrador técnico de cuentas (TAM).

Elementos secundarios

El elemento <Query> tiene los siguientes elementos secundarios:

Elemento secundario Tipo de consulta Tipo Descripción
<AffectedNights> Pricing integer La cantidad de noches para un rango de estadía. Este elemento solo se usa para las consultas de precios de estadía por rango que se usan con Precios modificados.
<Checkin> Pricing Date Son las fechas de un cambio de precio específico.
<Context> Pricing (Live Pricing Queries only) <Context> Para las consultas de precios en tiempo real, especifica ciertos parámetros según los cuales se realiza la consulta. Entre los elementos secundarios, se incluyen los siguientes:
  • <Occupancy>: La cantidad total de huéspedes
  • <OccupancyDetails>: Es el tipo de huéspedes, como adultos o niños.
  • <UserCountry>: Es el país donde se encuentra el usuario.
  • <UserDevice>: Es el tipo de dispositivo que usó el invitado para buscar un hotel, como "mobile, "tablet" o "desktop".

El elemento <Context> se puede repetir en una sola solicitud, lo que permite realizar consultas para ocupaciones diferentes. Consulta <Context> para obtener una lista de elementos secundarios, sintaxis y ejemplos.

<FirstDate> Pricing Date Es la fecha de inicio de un rango de itinerarios al que se aplican los precios. Este elemento solo se usa para las consultas de precios del período de registro de entrada que se usan con Precios modificados.
<HotelInfoProperties> Metadata string Una o más propiedades para las que Google desea actualizar los metadatos de habitación y paquete de habitación en un mensaje de metadatos Query Este elemento puede contener uno o más elementos <Property> que especifican los IDs de propiedad de hotel.
<LastDate> Pricing Date Es la fecha de finalización de un rango de itinerarios al que se aplican los precios. Este elemento solo se usa para las consultas de precios del período de registro de entrada que se usan con Pull + Hints.
<Nights> Pricing integer La cantidad de noches para un itinerario en particular, hasta 30.
<PropertyList> Pricing Object

Uno o más IDs de hoteles que requieren actualizaciones de precios.

Define cada hotel en un elemento <Property>. El valor es una string que coincide con un ID de hotel en tu Lista de hoteles. Por ejemplo:

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

Ejemplos

Consulta de precios

En el siguiente ejemplo, se muestra un mensaje de consulta de precios que solicita actualizaciones de precios para un conjunto de hoteles, disponibles por 3 noches, a partir del 10 de junio de 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>

Consulta de precios en tiempo real

En el siguiente ejemplo, se muestra una consulta de precios en tiempo real con un límite de tiempo de respuesta de 500 milisegundos:

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

Con consulta de contexto

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

Consulta de metadatos

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

Para ver ejemplos adicionales, como las consultas de precios de períodos de estadía y de entrada por intervalos, consulta los ejemplos de mensajes Query.

<Context>

El elemento <Context> describe la información de un Live pricing query, incluidos la cantidad y el tipo de invitados, el país y el dispositivo del usuario.

Nunca se usarán múltiples <Context> con diferentes países ni dispositivos de usuarios. Si se usan varios <Context> para buscar ocupaciones, proporciona el precio de cada ocupación como un paquete de habitación adicional para la propiedad o el itinerario correspondiente. Cada propiedad o itinerario debe tener un solo bloque de <Result> con los precios para varias ocupaciones incluidos.

Para obtener los detalles de respuesta de la consulta <Context>, consulta <OccupancyDetails>.

Sintaxis

El elemento <Context> usa la siguiente sintaxis:

Sintaxis

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

Elementos secundarios

El elemento <Context> tiene los siguientes elementos secundarios:

Elemento secundario Tipo de consulta Tipo Descripción
<Occupancy> Pricing integer Especifica la cantidad total de invitados.

Si bien no es obligatorio, las consultas con <Occupancy> deben generar un mensaje de transacción con los paquetes de Room adecuados para cada <Occupancy> consultada.

Nota:<Occupancy> no siempre aparecen en una consulta. En esos casos, debes mostrar los precios de todas las ocupaciones.

<OccupancyDetails> Pricing Object Es precedido por <Occupancy>. Especifica los invitados por tipo, incluidos los siguientes:

  • <NumAdults>: Cantidad de huéspedes adultos
  • <Children> y <Child="age">: Especifica qué invitados son niños (por lo general, de 0 a 17 años) y, de manera opcional, incluye la edad de cada uno.
  • Si bien no es obligatorio, las consultas con <OccupancyDetails> deben generar un mensaje de transacción con los paquetes de Room adecuados definidos para cada <Occupancy> consultada.

    Nota: Es posible que <OccupancyDetails> no siempre aparezca en una consulta. En esos casos, debes suponer que todos los invitados son adultos.

<UserCountry> Pricing string

Filtra las tarifas por el país en el que se encuentra el usuario. El valor es un código de país de 2 letras, como “US”, para Estados Unidos, o un código de región, como "EU" para "Europa".

Las consultas con <UserCountry> definido deberían generar un mensaje de transacción con el bloque <Rates> adecuado definido para el país consultado.

<UserDevice> Pricing string

Filtra las tarifas por el tipo de dispositivo desde el que realiza la búsqueda. Valores posibles:

  • mobile
  • desktop
  • tablet

Las consultas con <UserDevice> definido deberían generar un mensaje de transacción con el bloque <Rates> adecuado definido para el tipo de dispositivo consultado.

Ejemplos

Ocupación

En el siguiente ejemplo, se muestra una consulta de precios en tiempo real para <Occupancy> dentro de <Context>. La consulta de precios en tiempo real es para 3 invitados adultos.

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

Detalles de ocupación

En el siguiente ejemplo, se muestra una consulta de precios en tiempo real con <OccupancyDetails> dentro de <Context>. La consulta de precios en tiempo real es para 4 huéspedes, 2 de los cuales son niños, y busca una tarifa aplicable a una reserva de huésped de EE.UU. desde un dispositivo móvil:

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

Varios contextos

En el siguiente ejemplo, se muestra el uso de un elemento <Context> adicional en una consulta de precios en tiempo real.

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