API de Relatórios de Anúncios de Preços de Hotel
Nota
Esta versão beta do Hotel Price Ads está disponível apenas para participantes selecionados. Para obter informações sobre como participar no programa de versão beta, contacte o seu gestor de conta ou inscreva-se aqui.
A API e a documentação estão sujeitas a alterações.
Os relatórios são um processo assíncrono. Segue-se o fluxo geral para pedir um relatório.
- Criar um pedido com os parâmetros do relatório
- Enviar um pedido para o serviço de relatórios
- O serviço coloca o pedido em fila até conseguir processá-lo
- Consultar periodicamente o serviço para obter o estado da tarefa de relatório
- Quando o estado for Concluído, utilize o URL que o serviço fornece para transferir o relatório.
Para obter um exemplo que mostra como pedir e transferir um relatório, veja Exemplo de código de relatório.
Pedir um relatório
Para pedir um relatório, envie um pedido HTTP POST para o seguinte ponto final (para o ponto final do sandbox, veja Pontos finais):
https://partner.api.bingads.microsoft.com/Travel/v1/Customers({customerId})/Accounts({accountId})/ReportJobs
O corpo do pedido é um objeto ReportJob . Tem de especificar os seguintes campos no pedido:
- StartDate — O início do período de relatórios
- EndDate — O fim do período de relatórios
- Colunas — As colunas a incluir no relatório
- ReportType — O tipo de relatório ou entidade a transferir
Todos os outros campos são opcionais.
A granularidade mais baixa disponível é diária (a hora não é suportada). Se Columns incluir a coluna Data, o relatório contém linhas para cada dia na StartDate janela e EndDate , inclusivamente. Se não incluir Data, os dados do relatório mostram o resumo de desempenho total das datas de início e de fim especificadas.
O exemplo seguinte mostra um ReportJob pedido para um relatório de desempenho.
{
"ReportType":"Performance",
"StartDate":"2017-11-06",
"EndDate":"2017-11-13",
"Columns":[
"HotelId",
"Clicks"
]
}
Por predefinição, o serviço gera relatórios em formato CSV descomprimido. Para comprimir o relatório e melhorar o desempenho da transferência, inclua o campo Compressão e defina-o como ZIP.
A resposta ao POST contém um ID de tarefa de relatório (veja AddResponse). Por exemplo:
{
"value":"1080"
}
Consultar o estado de uma tarefa de relatório
Depois de obter o ID, utilize-o para obter o estado da tarefa de relatório. Para obter o estado, envie um pedido HTTP GET para:
https://partner.api.bingads.microsoft.com/Travel/v1/Customers({customerId})/Accounts({accountId})/ReportJobs('{jobId}')
A tarefa de relatório é válida durante um período indeterminado de tempo após a conclusão, mas normalmente durante, pelo menos, sete dias. Após sete dias, deverá submeter um novo pedido de relatório.
O corpo da resposta é um objeto ReportJob . Para determinar o estado da tarefa, aceda ao Status campo . Quando a tarefa for concluída, Status está definido como Concluído e o Url campo contém o URL que utiliza para transferir o relatório. O URL é válido durante sete dias. Se o URL expirar, tem de submeter um novo pedido de tarefa.
Quanto tempo demora a conclusão dos trabalhos de relatório é indeterminado e baseia-se em várias variáveis que estão constantemente a alterar esse número de tarefas na fila, a quantidade de dados e o tamanho do período de relatórios. Geralmente, deve consultar o estado da tarefa a cada cinco segundos até que o estado da tarefa seja Concluído ou Falhado.
A transferir o relatório
Quando o estado da tarefa do relatório for Concluído, o campo da Url tarefa contém o URL que utiliza para transferir o relatório. Para transferir o relatório, envie um pedido HTTP GET para o URL especificado.
Quando utilizar o URL de transferência para transferir o relatório, não especifique o cabeçalho Autorização tal como faz com os outros pedidos de relatório; utilize simplesmente o URL de transferência.
Para relatórios não comprimidos, o cabeçalho Content-Type da resposta GET contém texto/csv. Para relatórios comprimidos, o cabeçalho contém aplicação/zip.
Se tiver pedido ao serviço para comprimir os dados do relatório (veja o campo da tarefa do Compression relatório), o serviço coloca o ficheiro numa pasta e utiliza a compressão ZIP para comprimir o relatório. Lembre-se de descomprimir a pasta antes de aceder e ler o relatório. O nome do ficheiro de relatório é gerado automaticamente e tem o ID> de formulário, pedido de< desempenho.
Filtrar dados do relatório
Para filtrar os dados no relatório, utilize o campo do Filter objetoReportJob. Pode filtrar o relatório nas seguintes colunas de dimensão e em qualquer coluna de medida. Os nomes das colunas são sensíveis às maiúsculas e minúsculas.
- SubaccountId
- SubaccountName
- HotelGroupId
- HotelGroupName
- HotelId
- HotelName
- HotelStatus
- PartnerHotelId
- DeviceType
A utilização de filtros é uma operação E. Por exemplo, se filtrar por HotelPartnerId igual a 123 e DeviceType igual a Mobile, o relatório contém dados apenas em que o ID de hotel do parceiro é 123 E o tipo de dispositivo é móvel.
Para filtrar os dados de um relatório, defina Filter como uma cadeia de $filter OData. O exemplo seguinte mostra como filtrar o relatório para anúncios apresentados em ambientes de trabalho e tablets. Os valores de enumeração que utiliza no filtro são sensíveis a maiúsculas e minúsculas. Por exemplo, utilize o Ambiente de Trabalho em vez do ambiente de trabalho.
{
"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'",
}
Além de utilizar o Filter campo, pode utilizar os SubaccountId campos e HotelGroupId para limitar o relatório a uma subconta específica ou grupo hoteleiro. A utilização destes campos para limitar o âmbito a uma única subconta ou grupo hoteleiro proporciona um melhor desempenho do que a utilização Filterde . Se utilizar SubaccountId e HotelGroupId, não especifique-os também no filtro.
Incluindo hotéis sem desempenho no relatório
Por predefinição, o relatório de desempenho contém apenas hotéis com impressões durante o período de relatórios. Para incluir hotéis que não tiveram impressões durante o período de relatório, defina o campo IncludeNonPerformingHotels no pedido de relatório como verdadeiro.
{
"ReportType":"Performance",
"StartDate":"2017-11-06",
"EndDate":"2017-11-13",
"Columns":[
"HotelId",
"PartnerHotelId",
"Clicks",
"Impressions"
],
"IncludeNonPerformingHotels" : true
}
Se pedir hotéis sem desempenho no relatório, a columns propriedade não pode incluir as seguintes colunas de dimensão:
- Data
- DeviceType
- HotelCountry
- LengthOfStay
- Tipode Slot
- UserCountry
Se a columns propriedade incluir qualquer um dos campos acima, o pedido de tarefas de relatório falhará.
Como é que IncludeNonPerformingHotels afeta a criação de relatórios para hotéis que mudaram de grupo?
Por predefinição, o relatório inclui dados de desempenho do hotel, independentemente de segmentar o relatório por hotel, grupo hoteleiro ou subconta. Mover o hotel de um grupo para outro não afeta o comportamento predefinido do relatório. Por exemplo, se o relatório incluir a coluna hoteleira, o relatório inclui todos os dados de desempenho do hotel durante o período de tempo especificado.
Date Hotel ID Clicks
1-1-2018 5678 12
Se incluir a coluna hoteleira e a coluna do grupo hoteleiro, o relatório inclui dados de desempenho do hotel que ocorreram para cada grupo hoteleiro durante o período de tempo especificado.
Date Hotel group ID Hotel ID Clicks
1-1-2018 1234 5678 2
2-1-2018 9876 5678 10
No entanto, as coisas mudam se incluir a propriedade de pedido IncludeNonPerformingHotels. Se for verdadeiro, o relatório inclui dados de desempenho apenas para associações de hotéis e grupos hoteleiros ativos. Isto significa que o exemplo de relatório de hotéis acima muda para:
Date Hotel ID Clicks
1-1-2018 5678 10
E o exemplo do grupo hoteleiro muda para:
Date Hotel group ID Hotel ID Clicks
2-1-2018 9876 5678 10
Livros fechados
Para obter informações sobre quando os livros fecham, consulte Determinar quando os livros fecham. Determinar quando os livros fecham para Anúncios de Preços de Hotel é o mesmo que para campanhas do Microsoft Advertising com as seguintes exceções:
- O serviço de relatórios do Hotel Price Ads utiliza o fuso horário da conta.
- O serviço de relatórios do Hotel Price Ads não suporta ReturnOnlyCompleteData.
Colunas de relatórios de desempenho
Os relatórios contêm colunas de dimensão e colunas de medida (métricas). Os dados de métricas são segmentados pelas colunas de dimensão. Isto significa que os dados de métricas são atualizados para a dimensão de nível mais baixo na hierarquia de dimensões que especificar no pedido de relatório.
Segue-se a hierarquia de dimensões do Relatório de Desempenho.
- Data
- SubaccountId/Name
- HotelGroupId/Nome
- HotelId/Name, PartnerHotelId
- HotelCountry
- UserCountry
- Tipode Slot
- LengthOfStay
- DeviceType
Por exemplo, se o pedido contiver SubaccountId e Cliques, os cliques são agregados para SubaccountId.
| Data | Subconta | Cliques |
|---|---|---|
| 2017-11-16 | 123 | 40 |
Se o pedido contiver SubaccountId, HotelGroupId e Cliques, os cliques são atualizados para HotelGroupId.
| Data | Subconta | Grupo hoteleiro | Cliques |
|---|---|---|---|
| 2017-11-16 | 123 | 987 | 12 |
| 2017-11-16 | 123 | 654 | 13 |
| 2017-11-16 | 123 | 321 | 15 |
O pedido tem de incluir, pelo menos, uma coluna de dimensão e uma coluna de medida.
Colunas de dimensão
| Nome da coluna | Nome da coluna de relatório | Descrição |
|---|---|---|
| AdvancedBookingWindow | Janela de reserva Adv. | O número de dias antes da data de entrada que o utilizador está a pedir para reservar o quarto de hotel. Por exemplo, se hoje for 3 de maio e o utilizador pedir para reservar uma sala para 8 de maio, o valor da coluna é 5. |
| CheckinDay | Dia de entrada | O dia da semana em que o utilizador está a pedir para dar entrada no hotel. Seguem-se os valores inteiros possíveis.
|
| Data | Data | Uma data no período de relatórios. Esta coluna é adicionada automaticamente ao relatório, se não for especificada. O formato é AAAA-MM-dd (por exemplo, 2017-11-16). |
| DateType | Tipo de data | Indica se o utilizador procurou hotéis com datas específicas. Seguem-se os valores possíveis.
|
| DeviceType | Tipo de dispositivo | O tipo de dispositivo em que os anúncios foram apresentados. Seguem-se os valores possíveis.
|
| HotelCountry | País hoteleiro | O código de país ISO 3116 de duas letras do país ou região onde se encontra o hotel. Por exemplo, E.U.A. para Estados Unidos. |
| HotelGroupId | ID do grupo hoteleiro | O ID que identifica exclusivamente o grupo hoteleiro. |
| HotelGroupName | Nome do grupo de hotéis | O nome a apresentar do grupo hoteleiro. |
| HotelId | Hotel ID | O ID que identifica exclusivamente o hotel. |
| HotelName | Nome do hotel | O nome do hotel. |
| LengthOfStay | Duração da estadia | A duração do itinerário. |
| PartnerHotelId | ID do hotel parceiro | O ID que o parceiro utiliza para identificar exclusivamente o hotel. |
| Tipo de Site | Tipo de site | O site do Bing que os utilizadores usavam para procurar hotéis. Seguem-se os valores possíveis.
|
| Tipode Slot | Tipo de bloco | A colocação dos anúncios na página de resultados. Seguem-se os valores possíveis.
|
| SubAccountId | ID da subconta | O ID que identifica exclusivamente a subconta (campanha de alojamento). |
| SubAccountName | Nome da subconta | O nome a apresentar da subconta. |
| UserCountry | País/região do utilizador | O código de país ISO 3116 de duas letras do país ou região onde o utilizador está localizado. Por exemplo, E.U.A. para Estados Unidos. NOTA: Antes de 2 de agosto de 2018, UserCountry contém o país ou região do publicador. Depois de 2 de agosto de 2018, UserCountry contém o país ou região do utilizador. |
Medir colunas
| Nome da coluna | Nome da coluna de relatório | Descrição |
|---|---|---|
| AverageCPC | Avg. CPC | O custo médio por clique, que é calculado ao dividir o custo total de todos os cliques pelo número de cliques. O custo está na moeda da conta. Os dados estão disponíveis a partir de 6 de dezembro de 2017. |
| AverageCPCUSD | Avg. CPC USD | O custo médio por clique, que é calculado ao dividir o custo total de todos os cliques pelo número de cliques. O custo está em dólares americanos. |
| AveragePosition | Avg. pos. | A posição média dos anúncios na página de resultados. Posição refere-se à ordem do anúncio na página relativamente a todos os outros anúncios em todos os blocos. |
| AverageSlotPosition | Média de pos de slot. | A posição média dos anúncios no tipo de bloco. Se incluir esta métrica, também deve incluir a coluna de dimensão SlotType. |
| AvgBookedABW | AVG reservado ABW | A janela média de reservas avançadas para o hotel. A média é calculada como (ABW/conversões reservadas). Saiba mais. |
| AvgBookedNights | Noites médias reservadas | As noites médias reservadas para o hotel. A média é calculada como (total de noites/conversões reservadas). Saiba mais. |
| BookedABW | ABW Reservado | O total de dias de janela de reserva avançada para o hotel. Saiba mais. |
| Cliques | Cliques | O número de vezes em que os anúncios foram clicados. |
| Clique em Partilhar | Clique em partilhar | A percentagem de cliques que foram para os seus anúncios, do número total de cliques no mercado que estava a direcionar. Por exemplo, dos 1000 cliques estimados que ocorreram neste dia no seu mercado-alvo, tinha cerca de 230 ou 23%. O valor está no intervalo de 0,0 a 1,0. Saiba mais. |
| Conversões | Conversões | Uma reserva de hotel. Saiba mais. |
| Taxa de Conversão | Taxa de conversão | A taxa de conversões. A taxa é calculada como (conversões/cliques)*100. Saiba mais. |
| CPA | CPA | O custo por aquisição. O custo é calculado como (gastos/conversões). |
| CTR | CTR | A taxa de clique-através dos anúncios. A CTR é calculada ao dividir o número de vezes que os anúncios foram clicados pelo número de impressões. Saiba mais. |
| EligibleImpressions | Impr elegível. | O número total de impressões realizadas e não realizadas (impressões e impressões perdidas). Saiba mais. |
| Impressões | Impr. | O número de vezes que os anúncios foram apresentados. |
| GrossRevenue | Receita bruta | A receita total, incluindo impostos. Ler mais |
| GrossRevenuePerClick | Receita bruta/clique em | A receita bruta por clique. A receita por clique é calculada como (receita bruta/cliques). Saiba mais. |
| GrossRevenuePerConv | Receita bruta/conv | A receita bruta por conversão. A receita por conversão é calculada como (receita/conversões brutas). Saiba mais. |
| GrossROAS | ROAS Bruto | O retorno bruto dos gastos com anúncios. O ROAS é calculado como (receita/gastos brutos) * 100. Saiba mais. |
| ImpressionShare | Impr. partilhar | A percentagem de impressões, do total de impressões disponíveis no mercado que estava a visar. Por exemplo, de uma estimativa de 59 000 impressões que ocorreram neste dia no seu mercado-alvo, recebeu 2300 ou 3%. O valor está no intervalo de 0,0 a 1,0. Saiba mais. |
| MissedImpressions | Impr perdido. | O número total de impressões perdidas. Esta é a soma das seguintes colunas:
|
| MissedImpressionsInsufficientBid | Impr perdido. oferta insuficiente | O número de impressões perdidas porque as suas ofertas eram baixas e não competiam bem no mercado de leilões. Saiba mais. |
| MissedImpressionsNoTax | Impr perdido. sem impostos | O número de impressões perdidas porque o hotel não especificou impostos. Saiba mais. |
| MissedImpressionsOther | Impr perdido. outro | O número de impressões perdidas por todas as outras razões. Normalmente, a classificação baixa ou a sua taxa estavam disponíveis na secção Mais tarifas , mas o utilizador não expandiu a secção para ver a sua taxa. Saiba mais. |
| MissedImpressionsSpendingCapReached | Impr perdido. limite de gastos atingido | O número de impressões perdidas porque atingiu o limite de gastos diários. Saiba mais. |
| NetRevenue | Receita líquida | A receita total, excluindo impostos. Saiba mais. |
| NetRevenuePerClick | Receita líquida/clique em | A receita líquida por clique. A receita por clique é calculada como (receita líquida/cliques). Saiba mais. |
| NetRevenueConv | Receita líquida/conv | A receita líquida por conversão. A receita por conversão é calculada como (receita líquida/conversões). Saiba mais. |
| NetROAS | Net ROAS | O retorno líquido dos gastos com anúncios. O ROAS é calculado como (receita líquida/gasto) * 100. |
| Gastar | Gastar | O custo total de todos os cliques. O custo está na moeda da conta. Os dados estão disponíveis a partir de 6 de dezembro de 2017. Saiba mais. |
| SpendUSD | Gastar USD | O custo total de todos os cliques. O custo está em dólares americanos. |
| TotalBookedNights | Duração reservada da estadia | O total de noites reservadas para o hotel. Saiba mais. |
Partilha de voz
Para além da regra que os pedidos têm de incluir, pelo menos, uma coluna de dimensão e uma coluna de medida, qualquer relatório que inclua colunas de partilha de voz (SOV) tem de incluir, pelo menos, uma das seguintes colunas de dimensão.
- HotelGroupId
- HotelId
- PartnerHotelId
- SubAccountId
Seguem-se as colunas SOV:
- Clique em Partilhar
- EligibleImpressions
- ImpressionShare
- MissedImpressions
- MissedImpressionsInsufficientBid
- MissedImpressionsNoTax
- MissedImpressionsOther
- MissedImpressionsSpendingCapReached
Nota
Os dados SOV estão disponíveis a partir de 1 de maio de 2018. Se especificar um período de relatório que inclua datas anteriores a 1 de maio de 2018, os campos SOV conterão um valor zero (0) para datas anteriores a 1 de maio.
Relatório de Desempenho de Exemplo
Segue-se um exemplo das linhas e colunas de cabeçalho do relatório.
"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
A primeira linha de cabeçalho contém o nome do relatório e o período de relatório pedido. A segunda linha de cabeçalho contém o ID do pedido do relatório. Se existir um problema com o relatório, utilizará o ID quando contactar o suporte para obter ajuda para o problema.
Nota
Os IDs, como o ID do hotel ou o ID do grupo de anúncios, estão entre parênteses retos (por exemplo, [1234567890]).