API de informes de anuncios de precios de hotel

Nota:

Esta versión beta de Hotel Price Ads solo está disponible para seleccionar participantes. Para obtener información sobre cómo participar en el programa de versión beta, póngase en contacto con el administrador de cuentas o inscríbase aquí.

La API y la documentación están sujetas a cambios.

La creación de informes es un proceso asincrónico. A continuación se muestra el flujo general para solicitar un informe.

• Creación de una solicitud con los parámetros del informe
• Envío de una solicitud al servicio de informes
• El servicio pone en cola la solicitud hasta que pueda procesarla.
• Sondear el servicio periódicamente para obtener el estado del trabajo de informe
• Cuando el estado sea Completado, use la dirección URL que proporciona el servicio para descargar el informe.

Para obtener un ejemplo que muestra cómo solicitar y descargar un informe, vea Ejemplo de código de informes.

Solicitud de un informe

Para solicitar un informe, envíe una solicitud HTTP POST al siguiente punto de conexión (para el punto de conexión de espacio aislado, consulte Puntos de conexión):

https://partner.api.bingads.microsoft.com/Travel/v1/Customers({customerId})/Accounts({accountId})/ReportJobs

El cuerpo de la solicitud es un objeto ReportJob . Debe especificar los siguientes campos en la solicitud:

• StartDate: el inicio del período de informes
• EndDate: el final del período de informes
• Columnas: las columnas que se van a incluir en el informe
• ReportType: tipo de informe o entidad que se va a descargar

El resto de campos son opcionales.

La granularidad más baja disponible es diaria (no se admite cada hora). Si Columns incluye la columna Date, el informe contiene filas para cada día en la StartDate ventana y EndDate , de forma inclusiva. Si no incluye Date, los datos del informe muestran el resumen de rendimiento total de las fechas de inicio y finalización especificadas.

En el ejemplo siguiente se muestra una ReportJob solicitud para un informe de rendimiento.

{
    "ReportType":"Performance", 
    "StartDate":"2017-11-06", 
    "EndDate":"2017-11-13", 
    "Columns":[  
        "HotelId", 
        "Clicks" 
    ] 
}

De forma predeterminada, el servicio genera informes en formato CSV sin comprimir. Para comprimir el informe y mejorar el rendimiento de descarga, incluya el campo Compresión y establézcalo en ZIP.

La respuesta a POST contiene un identificador de trabajo de informe (consulte AddResponse). Por ejemplo:

{
    "value":"1080"
}

Sondeo del estado de un trabajo de informe

Después de obtener el identificador, úselo para obtener el estado del trabajo del informe. Para obtener el estado, envíe una solicitud HTTP GET a:

https://partner.api.bingads.microsoft.com/Travel/v1/Customers({customerId})/Accounts({accountId})/ReportJobs('{jobId}')

El trabajo de informe es válido durante un período de tiempo indeterminado después de que se complete, pero normalmente durante al menos siete días. Después de siete días, debe enviar una nueva solicitud de informe.

El cuerpo de la respuesta es un objeto ReportJob . Para determinar el estado del trabajo, acceda al Status campo . Cuando finaliza el trabajo, Status se establece en Completado y el Url campo contiene la dirección URL que se usa para descargar el informe. La dirección URL es válida durante siete días. Si la dirección URL expira, debe enviar una nueva solicitud de trabajo.

El tiempo que tardan los trabajos de informe en finalizar no está determinado y se basa en varias variables que cambian constantemente este número de trabajos en la cola, la cantidad de datos y el tamaño del período de informe. Por lo general, debe sondear el estado del trabajo cada cinco segundos hasta que el estado del trabajo sea Completado o Erróneo.

Descarga del informe

Cuando el estado del trabajo de informe es Completado, el campo del Url trabajo contiene la dirección URL que se usa para descargar el informe. Para descargar el informe, envíe una solicitud HTTP GET a la dirección URL especificada.

Cuando use la dirección URL de descarga para descargar el informe, no especifique el encabezado Authorization como lo hace con las otras solicitudes de informe; simplemente use la dirección URL de descarga.

En el caso de los informes sin comprimir, el encabezado Content-Type de la respuesta GET contiene text/csv. Para los informes comprimidos, el encabezado contiene application/zip.

Si pidió al servicio que comprima los datos del informe (consulte el campo del trabajo del Compression informe), el servicio coloca el archivo en una carpeta y usa la compresión ZIP para comprimir el informe. No olvide descomprimir la carpeta antes de acceder al informe y leerlo. El nombre del archivo de informe se genera automáticamente y tiene el formulario, el identificador> de solicitud de< rendimiento.

Filtrado de datos de informe

Para filtrar los datos del informe, use el campo del Filter objetoReportJob. Puede filtrar el informe por las siguientes columnas de dimensión y cualquier columna de medida. Los nombres de columna distinguen mayúsculas de minúsculas.

• SubaccountId
• SubaccountName
• HotelGroupId
• HotelGroupName
• HotelId
• HotelName
• HotelStatus
• PartnerHotelId
• DeviceType

El uso de filtros es una operación AND. Por ejemplo, si filtra por HotelPartnerId igual a 123 y DeviceType igual a Mobile, el informe solo contiene datos donde el identificador de hotel del asociado es 123 y el tipo de dispositivo es móvil.

Para filtrar los datos de un informe, establezca en Filter una cadena de $filter de OData. En el ejemplo siguiente se muestra cómo filtrar el informe para los anuncios que se muestran en escritorios y tabletas. Los valores de enumeración que se usan en el filtro distinguen mayúsculas de minúsculas. Por ejemplo, use Escritorio en lugar de escritorio.

{
    "ReportType":"Performance", 
    "StartDate":"2017-11-06", 
    "EndDate":"2017-11-13", 
    "Columns":[  
        "HotelId", 
        "Clicks" 
    ], 
    "Filter":"DeviceType eq Enum.DeviceType'Desktop' or DeviceType eq Enum.DeviceType'Tablet'", 
}

Además de usar el Filter campo , puede usar los SubaccountId campos y HotelGroupId para limitar el informe a una subcuenta o grupo de hoteles específico. El uso de estos campos para limitar el ámbito a una sola subcuenta o grupo de hoteles proporciona un mejor rendimiento que el uso de Filter. Si usa SubaccountId y HotelGroupId, no los especifique también en el filtro.

Inclusión de hoteles que no funcionan en el informe

De forma predeterminada, el informe de rendimiento solo contiene hoteles que tienen impresiones durante el período del informe. Para incluir hoteles que no tuvieron impresiones durante el período de informe, establezca el campo IncludeNonPerformingHotels en la solicitud de informe en true.

{
    "ReportType":"Performance", 
    "StartDate":"2017-11-06", 
    "EndDate":"2017-11-13", 
    "Columns":[  
        "HotelId",
        "PartnerHotelId",
        "Clicks",
        "Impressions"
    ],
    "IncludeNonPerformingHotels" : true
}

Si solicita hoteles que no funcionan en el informe, la columns propiedad no debe incluir las siguientes columnas de dimensión:

• Fecha
• DeviceType
• HotelCountry
• LengthOfStay
• SlotType
• UserCountry

Si la columns propiedad incluye cualquiera de los campos anteriores, se produce un error en la solicitud de trabajos del informe.

¿Cómo afecta IncludeNonPerformingHotels a los informes de hoteles que han movido grupos?

De forma predeterminada, el informe incluye datos de rendimiento de hoteles para el hotel, independientemente de si segmenta el informe por hotel, grupo de hoteles o subcuenta. Mover el hotel de un grupo a otro no afecta al comportamiento predeterminado de los informes. Por ejemplo, si el informe incluye la columna hotel, el informe incluye todos los datos de rendimiento del hotel durante el período de tiempo especificado.

Date        Hotel ID   Clicks
1-1-2018    5678       12

Si incluye la columna de hotel y la columna de grupo de hoteles, el informe incluye los datos de rendimiento del hotel que se produjeron para cada grupo de hoteles durante el período de tiempo especificado.

Date       Hotel group ID   Hotel ID   Clicks
1-1-2018   1234             5678       2
2-1-2018   9876             5678       10

Pero las cosas cambian si se incluye la propiedad de solicitud IncludeNonPerformingHotels. Si es true, el informe incluye datos de rendimiento solo para las asociaciones activas de hoteles y grupos de hoteles. Esto significa que el ejemplo de informe de hoteles anterior cambia a:

Date        Hotel ID   Clicks
1-1-2018    5678       10

Y el ejemplo de grupo de hoteles cambia a:

Date       Hotel group ID   Hotel ID   Clicks
2-1-2018   9876             5678       10

Libros cerrados

Para obtener información sobre cuándo se cierran los libros, vea Determinar cuándo se cierran los libros. Determinar cuándo se cierran los libros de Anuncios de precios de hotel es lo mismo que para las campañas de Microsoft Advertising con las siguientes excepciones:

• El servicio de informes de Hotel Price Ads usa la zona horaria de la cuenta.
• El servicio de informes de Hotel Price Ads no admite ReturnOnlyCompleteData.

Columnas de informe de rendimiento

Los informes contienen columnas de dimensión y columnas de medida (métricas). Los datos de métricas se segmentan por las columnas de dimensión. Esto significa que los datos de métricas se acumulan hasta la dimensión de nivel más bajo de la jerarquía de dimensiones que especifique en la solicitud de informe.

A continuación se muestra la jerarquía de dimensiones del informe de rendimiento.

1. Fecha
2. SubaccountId/Name
3. HotelGroupId/Name
4. HotelId/Name, PartnerHotelId
5. HotelCountry
6. UserCountry
7. SlotType
8. LengthOfStay
9. DeviceType

Por ejemplo, si la solicitud contiene SubaccountId y Clicks, los clics se acumulan en SubaccountId.

Fecha	Subcuenta	Clics
2017-11-16	123	40

Y si la solicitud contiene SubaccountId, HotelGroupId y Clicks, los clics se acumulan en HotelGroupId.

Fecha	Subcuenta	Grupo hotelero	Clics
2017-11-16	123	987	12
2017-11-16	123	654	13
2017-11-16	123	321	15

La solicitud debe incluir al menos una columna de dimensión y una columna de medida.

Columnas de dimensión

Nombre de columna	Nombre de columna de informe	Description
AdvancedBookingWindow	Ventana de reserva de Adv.	El número de días anteriores a la fecha de registro de entrada que el usuario solicita para reservar la habitación del hotel. Por ejemplo, si hoy es 3 de mayo y el usuario pide reservar una habitación para el 8 de mayo, el valor de la columna es 5.
CheckinDay	Día de checkin	El día de la semana en que el usuario está solicitando el registro de entrada en el hotel. Los siguientes son los valores enteros posibles. 1 (lunes) 2 (martes) 3 (miércoles) 4 (jueves) 5 (viernes) 6 (sábado) 7 (domingo)
Fecha	Fecha	Una fecha dentro del período de informes. Esta columna se agrega automáticamente al informe si no se especifica. El formato es AAAA-MM-dd (por ejemplo, 2017-11-16).
DateType	Tipo de fecha	Indica si el usuario ha buscado hoteles con fechas específicas. A continuación se muestran los valores posibles. DefaultDate: el usuario no ha buscado hoteles con fechas específicas SelectedDate: el usuario que ha buscado hoteles con fechas específicas
DeviceType	Tipo de dispositivo	Tipo de dispositivo en el que se mostraron los anuncios. A continuación se muestran los valores posibles. Escritorio Móvil Tablet
HotelCountry	País del hotel	El código de país ISO 3116 de dos letras del país o región donde se encuentra el hotel. Por ejemplo, EE. UU. para Estados Unidos.
HotelGroupId	Id. de grupo de hoteles	Identificador que identifica de forma única el grupo de hoteles.
HotelGroupName	Nombre del grupo de hoteles	Nombre para mostrar del grupo de hoteles.
HotelId	Id. de hotel	Identificador que identifica de forma única el hotel.
HotelName	Nombre del hotel	El nombre del hotel.
LengthOfStay	Duración de la estancia	La duración de la estancia del itinerario.
PartnerHotelId	Id. de hotel asociado	El identificador que usa el asociado para identificar de forma única el hotel.
SiteType	Tipo de sitio	El sitio web de Bing que los usuarios usaban para buscar hoteles. A continuación se muestran los valores posibles. LocalUniversal: el usuario usó Bing.com para buscar hoteles MapResults: el usuario usó Bing.com/maps para buscar hoteles PropertyPromotionAd: el usuario estaba mirando la primera página de resultados que se muestra en la búsqueda de mapas.
SlotType	Tipo de ranura	Colocación de los anuncios en la página de resultados. A continuación se muestran los valores posibles. R: la ranura de prioridad donde los anuncios se muestran en la página de resultados cuando se cargan. M: la ranura secundaria donde se muestran los anuncios solo después de que el usuario haga clic en Más tasas.
SubAccountId	Id. de subcuenta	Identificador que identifica de forma única la subcuenta (campaña de hospedaje).
SubAccountName	Nombre de subcuenta	Nombre para mostrar de la subcuenta.
UserCountry	País del usuario	El código de país ISO 3116 de dos letras del país o región donde se encuentra el usuario. Por ejemplo, EE. UU. para Estados Unidos. NOTA: Antes del 2 de agosto de 2018, UserCountry contiene el país o región del publicador. Después del 2 de agosto de 2018, UserCountry contiene el país o región del usuario.

Columnas de medida

Nombre de columna	Nombre de columna de informe	Description
AverageCPC	CPC promedio	El costo medio por clic, que se calcula dividiendo el costo total de todos los clics por el número de clics. El costo está en la moneda de la cuenta. Los datos están disponibles a partir del 6 de diciembre de 2017.
AverageCPCUSD	Promedio de CPC USD	El costo medio por clic, que se calcula dividiendo el costo total de todos los clics por el número de clics. El costo es en dólares estadounidenses.
AveragePosition	Promedio de pos.	Posición media de los anuncios en la página de resultados. Posición hace referencia al orden del anuncio en la página en relación con el resto de anuncios en todas las ranuras.
AverageSlotPosition	Promedio de espacio pos.	Posición media de los anuncios en el tipo de ranura. Si incluye esta métrica, también debe incluir la columna de dimensión SlotType.
AvgBookedABW	Promedio de ABW reservado	El promedio de ventana de reserva avanzada para el hotel. El promedio se calcula como (ABW/conversiones reservadas). Más información.
AvgBookedNights	Promedio de noches reservadas	El promedio de noches reservadas para el hotel. El promedio se calcula como (total de noches/conversiones reservadas). Más información.
BookedABW	ABW reservado	El total de días de ventana de reserva avanzada para el hotel. Más información.
Clics	Clics	Número de veces que se ha hecho clic en los anuncios.
Clickshare	Haga clic en compartir	El porcentaje de clics que fueron a tus anuncios, del número total de clics en el mercado al que apuntaste. Por ejemplo, de los 1.000 clics estimados que se produjeron este día en el mercado objetivo, tenía aproximadamente un 230 o un 23 %. El valor está en el intervalo de 0,0 a 1,0. Más información.
Conversiones	Conversiones	Una reserva de hotel. Más información.
ConversionRate	Tasa de conversión	Tasa de conversiones. La tasa se calcula como (conversiones/clics)*100. Más información.
CPA	CPA	Costo por adquisición. El costo se calcula como (gasto/conversiones).
CTR	CTR	La tasa de clics de los anuncios. CTR se calcula dividiendo el número de veces que se ha hecho clic en los anuncios por el número de impresiones. Más información.
EligibleImpressions	Impr apto.	El número total de impresiones realizadas y no realizadas (impresiones más impresiones perdidas). Más información.
Impresiones	Impr.	El número de veces que se mostraron anuncios.
GrossRevenue	Ingresos brutos	Los ingresos totales, incluidos los impuestos. Más información
GrossRevenuePerClick	Ingresos brutos/clic	Ingresos brutos por clic. Los ingresos por clic se calculan como (ingresos brutos/clics). Más información.
GrossRevenuePerConv	Ingresos brutos/conv	Ingresos brutos por conversión. Los ingresos por conversión se calculan como (ingresos brutos o conversiones). Más información.
GrossROAS	ROAS bruto	La rentabilidad bruta del gasto en anuncios. El ROAS se calcula como (ingresos/gastos brutos) * 100. Más información.
ImpressionShare	Impr. share	El porcentaje de impresiones, del total de impresiones disponibles en el mercado que estaba apuntando. Por ejemplo, de las 59 000 impresiones estimadas que se produjeron este día en el mercado objetivo, recibió 2.300 o un 3 %. El valor está en el intervalo de 0,0 a 1,0. Más información.
MissedImpressions	Impr perdido.	Número total de impresiones perdidas. Esta es la suma de las siguientes columnas: MissedImpressionsInsufficientBid MissedImpressionsNoTax MissedImpressionsOther MissedImpressionsSpendingCapReached Más información.
MissedImpressionsInsufficientBid	Impr perdido. oferta insuficiente	El número de impresiones perdidas porque sus ofertas eran bajas y no competían bien en el marketplace de subastas. Más información.
MissedImpressionsNoTax	Impr perdido. sin impuestos	El número de impresiones perdidas porque el hotel no especificó impuestos. Más información.
MissedImpressionsOther	Impr perdido. Otro	Número de impresiones perdidas por todas las demás razones. Normalmente, la clasificación baja o la tasa estaba disponible en la sección Más tarifas , pero el usuario no expandió la sección para ver la tasa. Más información.
MissedImpressionsSpendingCapReached	Impr perdido. límite de gasto alcanzado	Número de impresiones perdidas porque ha alcanzado el límite de gasto diario. Más información.
NetRevenue	Ingresos netos	Los ingresos totales, excepto los impuestos. Más información.
NetRevenuePerClick	Ingresos netos/clic	Ingresos netos por clic. Los ingresos por clic se calculan como (ingresos netos o clics). Más información.
NetRevenueConv	Ingresos netos/conv	Ingresos netos por conversión. Los ingresos por conversión se calculan como (ingresos o conversiones netos). Más información.
NetROAS	ROAS neto	La rentabilidad neta del gasto en anuncios. El ROAS se calcula como (ingresos/gastos netos) * 100.
Gastar	Gastar	Costo total de todos los clics. El costo está en la moneda de la cuenta. Los datos están disponibles a partir del 6 de diciembre de 2017. Más información.
SpendUSD	Gastar USD	Costo total de todos los clics. El costo es en dólares estadounidenses.
TotalBookedNights	Duración reservada de la estancia	El total de noches reservadas para el hotel. Más información.

Uso compartido de voz

Además de la regla que las solicitudes deben incluir al menos una columna de dimensión y una columna de medida, cualquier informe que incluya columnas de uso compartido de voz (SOV) debe incluir al menos una de las siguientes columnas de dimensión.

• HotelGroupId
• HotelId
• PartnerHotelId
• SubAccountId

A continuación se muestran las columnas SOV:

• Clickshare
• EligibleImpressions
• ImpressionShare
• MissedImpressions
• MissedImpressionsInsufficientBid
• MissedImpressionsNoTax
• MissedImpressionsOther
• MissedImpressionsSpendingCapReached

Nota:

Los datos de SOV están disponibles a partir del 1 de mayo de 2018. Si especifica un período de informes que incluye fechas anteriores al 1 de mayo de 2018, los campos SOV contendrán un valor cero (0) para las fechas anteriores al 1 de mayo.

Informe de rendimiento de ejemplo

A continuación se muestra un ejemplo de las filas y columnas de encabezado del informe.

"Performance report (October 30, 2017 - November 29, 2017)"
Request Id: f11b6610-5b85-4d7f-97ad-69668eb9da11

Date,Subaccount ID,Hotel group ID,Clicks,CTR,Impr.,Spend,User country

La primera fila de encabezado contiene el nombre del informe y el período de informe solicitado. La segunda fila de encabezado contiene el identificador de solicitud del informe. Si hay un problema con el informe, usaría el identificador cuando se ponga en contacto con el soporte técnico para obtener ayuda con el problema.

Nota:

Los identificadores, como el id. de hotel o el de grupo de anuncios, se incluyen entre corchetes (por ejemplo, [1234567890]).