Hotel Price Ads Reporting API

Article
02/21/2024

Remarque

Cette version bêta de Hotel Price Ads est disponible uniquement pour certains participants. Pour plus d’informations sur la participation au programme de version bêta, contactez votre responsable de compte ou inscrivez-vous ici.

L’API et la documentation sont susceptibles d’être modifiées.

La création de rapports est un processus asynchrone. Voici le flux général pour demander un rapport.

Créer une requête avec les paramètres de rapport
Envoyer une requête au service de création de rapports
Le service met la demande en file d’attente jusqu’à ce qu’il soit en mesure de la traiter
Interroger régulièrement le service pour obtenir la status du travail de rapport
Une fois le status terminé, utilisez l’URL que le service fournit pour télécharger le rapport.

Pour obtenir un exemple qui montre comment demander et télécharger un rapport, consultez Exemple de code de création de rapports.

Demande d’un rapport

Pour demander un rapport, envoyez une requête HTTP POST au point de terminaison suivant (pour le point de terminaison du bac à sable, consultez Points de terminaison) :

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

Le corps de la requête est un objet ReportJob . Vous devez spécifier les champs suivants dans la demande :

StartDate : début de la période de rapport
EndDate : fin de la période de rapport
Colonnes : colonnes à inclure dans le rapport
ReportType : type de rapport ou d’entité à télécharger

Tout autre champ est facultatif.

La granularité la plus faible disponible est quotidienne (toutes les heures n’est pas prise en charge). Si Columns inclut la colonne Date, le rapport contient des lignes pour chaque jour dans la StartDate fenêtre et EndDate , inclusivement. Si vous n’incluez pas Date, les données de rapport affichent le récapitulatif des performances totales pour les dates de début et de fin spécifiées.

L’exemple suivant montre une ReportJob demande de rapport de performances.

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

Par défaut, le service génère des rapports au format CSV non compressé. Pour compresser le rapport et améliorer les performances de téléchargement, incluez le champ Compression et définissez-le sur ZIP.

La réponse à post contient un ID de travail de rapport (voir AddResponse). Par exemple :

{
    "value":"1080"
}

Interrogation de la status d’un travail de rapport

Après avoir obtenu l’ID, utilisez-le pour obtenir le status du travail de rapport. Pour obtenir le status, envoyez une requête HTTP GET à :

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

Le travail de rapport est valide pendant une durée indéterminée après son exécution, mais généralement pendant au moins sept jours. Après sept jours, vous devez soumettre une nouvelle demande de rapport.

Le corps de la réponse est un objet ReportJob . Pour déterminer la status du travail, accédez au Status champ . Une fois le travail terminé, Status est défini sur Terminé et le Url champ contient l’URL que vous utilisez pour télécharger le rapport. L’URL est valide pendant sept jours. Si l’URL expire, vous devez envoyer une nouvelle demande de travail.

Le temps nécessaire à la fin des travaux de rapport est indéterminé et est basé sur plusieurs variables qui changent constamment comme le nombre de travaux dans la file d’attente, la quantité de données et la taille de la période de rapport. En règle générale, vous devez interroger la status du travail toutes les cinq secondes jusqu’à ce que la status du travail soit Terminée ou Échec.

Téléchargement du rapport

Lorsque le status du travail de rapport est Terminé, le champ du Url travail contient l’URL que vous utilisez pour télécharger le rapport. Pour télécharger le rapport, envoyez une requête HTTP GET à l’URL spécifiée.

Lorsque vous utilisez l’URL de téléchargement pour télécharger le rapport, ne spécifiez pas l’en-tête Autorisation comme vous le faites avec les autres demandes de rapport ; utilisez simplement l’URL de téléchargement.

Pour les rapports non compressés, l’en-tête Content-Type de la réponse GET contient du texte/csv. Pour les rapports compressés, l’en-tête contient application/zip.

Si vous avez demandé au service de compresser les données du rapport (voir le champ du travail de Compression rapport), le service place le fichier dans un dossier et utilise la compression ZIP pour compresser le rapport. N’oubliez pas de décompresser le dossier avant d’accéder au rapport et de le lire. Le nom du fichier de rapport est généré automatiquement et a le formulaire, l’ID> de demande de< performances.

Filtrage des données de rapport

Pour filtrer les données du rapport, utilisez le champ de l’objet FilterReportJob. Vous pouvez filtrer le rapport sur les colonnes de dimension suivantes et sur n’importe quelle colonne de mesure. Les noms des colonnes sont sensibles à la casse.

SubaccountId
SubaccountName
HotelGroupId
HotelGroupName
Id d’hôtel
HotelName
HotelStatus
PartnerHotelId
DeviceType

L’utilisation de filtres est une opération AND. Par exemple, si vous filtrez sur HotelPartnerId égal à 123 et DeviceType égal à Mobile, le rapport contient des données uniquement lorsque l’ID d’hôtel du partenaire est 123 ET que le type d’appareil est mobile.

Pour filtrer les données d’un rapport, définissez sur Filter une chaîne de $filter OData. L’exemple suivant montre comment filtrer le rapport pour les publicités affichées sur les ordinateurs de bureau et les tablettes. Les valeurs d’énumération que vous utilisez dans le filtre respectent la casse. Par exemple, utilisez Desktop au lieu de Desktop.

{
    "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'", 
}

En plus d’utiliser le Filter champ, vous pouvez utiliser les SubaccountId champs et HotelGroupId pour limiter le rapport à un sous-compte ou un groupe d’hôtels spécifique. L’utilisation de ces champs pour limiter l’étendue à un seul sous-compte ou groupe d’hôtels offre de meilleures performances que l’utilisation de Filter. Si vous utilisez SubaccountId et HotelGroupId, ne les spécifiez pas également dans le filtre.

Inclure les hôtels non performants dans le rapport

Par défaut, le rapport de performances contient uniquement les hôtels qui ont des impressions pendant la période de rapport. Pour inclure les hôtels qui n’ont pas eu d’impressions pendant la période de rapport, définissez le champ IncludeNonPerformingHotels dans la demande de rapport sur true.

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

Si vous demandez des hôtels non performants dans le rapport, la columns propriété ne doit pas inclure les colonnes de dimension suivantes :

Date
DeviceType
HotelCountry
LengthOfStay
SlotType
UserCountry

Si la columns propriété inclut l’un des champs ci-dessus, la demande de travaux de rapport échoue.

Comment IncludeNonPerformingHotels affecte-t-il la création de rapports pour les hôtels qui ont déplacé des groupes ?

Par défaut, le rapport inclut des données de performances d’hôtel pour l’hôtel, que vous segmentiez le rapport par hôtel, groupe d’hôtels ou sous-compte. Le déplacement de l’hôtel d’un groupe à un autre n’a pas d’impact sur le comportement de création de rapports par défaut. Par exemple, si le rapport inclut la colonne d’hôtel, le rapport inclut toutes les données de performances de l’hôtel pendant la période spécifiée.

Date        Hotel ID   Clicks
1-1-2018    5678       12

Si vous incluez la colonne d’hôtel et la colonne groupe d’hôtels, le rapport inclut les données de performances des hôtels qui se sont produites pour chaque groupe d’hôtels pendant la période spécifiée.

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

Toutefois, les choses changent si vous incluez la propriété de requête IncludeNonPerformingHotels. Si la valeur est true, le rapport inclut des données de performances uniquement pour les associations d’hôtels et de groupes d’hôtels actifs. Cela signifie que l’exemple d’hôtels ci-dessus change pour :

Date        Hotel ID   Clicks
1-1-2018    5678       10

Et l’exemple de groupe d’hôtels devient :

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

Livres fermés

Pour plus d’informations sur la fermeture des livres, consultez Détermination du moment où les livres se ferment. La détermination de la fermeture des livres pour Hotel Price Ads est la même que pour les campagnes Microsoft Advertising, avec les exceptions suivantes :

Le service de création de rapports d’Hotel Price Ads utilise le fuseau horaire du compte.
Le service de création de rapports d’Hotel Price Ads ne prend pas en charge ReturnOnlyCompleteData.

Colonnes du rapport de performances

Les rapports contiennent des colonnes de dimension et des colonnes de mesure (métriques). Les données de métriques sont segmentées par les colonnes de dimension. Cela signifie que les données de métriques se cumulent jusqu’à la dimension de niveau le plus bas dans la hiérarchie de dimension que vous spécifiez dans votre demande de rapport.

Voici la hiérarchie de dimension pour le rapport de performances.

Date
SubaccountId/Name
HotelGroupId/Name
HotelId/Name, PartnerHotelId
HotelCountry
UserCountry
SlotType
LengthOfStay
DeviceType

Par exemple, si la requête contient SubaccountId et Clicks, les clics sont cumulatifs sur SubaccountId.

Date	Sous-compte	Clics
2017-11-16	123	40

Et si la requête contient SubaccountId, HotelGroupId et Clicks, les clics sont cumulatifs sur HotelGroupId.

Date	Sous-compte	Groupe d’hôtels	Clics
2017-11-16	123	987	12
2017-11-16	123	654	13
2017-11-16	123	321	15

La requête doit inclure au moins une colonne de dimension et une colonne de mesure.

Colonnes de dimension

Nom de colonne	Nom de la colonne de rapport	Description
AdvancedBookingWindow	Fenêtre de réservation Adv.	Nombre de jours avant la date de case activée à laquelle l’utilisateur demande de réserver la chambre d’hôtel. Par exemple, si aujourd’hui est le 3 mai et que l’utilisateur demande de réserver une chambre pour le 8 mai, la valeur de la colonne est 5.
CheckinDay	Jour d’archivage	Jour de la semaine auquel l’utilisateur demande de case activée dans l’hôtel. Voici les valeurs entières possibles. 1 (lundi) 2 (mardi) 3 (mercredi) 4 (jeudi) 5 (vendredi) 6 (samedi) 7 (dimanche)
Date	Date	Date de la période de rapport. Cette colonne est automatiquement ajoutée au rapport si elle n’est pas spécifiée. Le format est AAAA-MM-jj (par exemple, 2017-11-16).
DateType	Type de date	Indique si l’utilisateur a recherché des hôtels à l’aide de dates spécifiques. Voici les valeurs possibles. DefaultDate : l’utilisateur n’a pas recherché d’hôtels à l’aide de dates spécifiques SelectedDate : l’utilisateur a recherché des hôtels à l’aide de dates spécifiques
DeviceType	Type d’appareil	Type d’appareil sur lequel les annonces ont été affichées. Voici les valeurs possibles. Ordinateur de bureau Mobile Tablet
HotelCountry	Pays de l’hôtel	Code de pays ISO 3116 à deux lettres du pays ou de la région où se trouve l’hôtel. Par exemple, Les États-Unis pour États-Unis.
HotelGroupId	ID du groupe d’hôtels	ID qui identifie de façon unique le groupe d’hôtels.
HotelGroupName	Nom du groupe d’hôtels	Nom complet du groupe hôtelier.
Id d’hôtel	ID d’hôtel	ID qui identifie de façon unique l’hôtel.
HotelName	Nom de l’hôtel	Le nom de l’hôtel.
LengthOfStay	Durée du séjour	Durée de séjour de l’itinéraire.
PartnerHotelId	ID d’hôtel partenaire	ID que le partenaire utilise pour identifier l’hôtel de manière unique.
SiteType	Type de site	Site web Bing utilisé par les utilisateurs pour rechercher des hôtels. Voici les valeurs possibles. LocalUniversal : l’utilisateur a utilisé Bing.com pour rechercher des hôtels MapResults : l’utilisateur a utilisé Bing.com/maps pour rechercher des hôtels PropertyPromotionAd : l’utilisateur regardait la première page de résultats affichée dans la recherche de cartes.
SlotType	Type d’emplacement	Placement des annonces sur la page de résultats. Voici les valeurs possibles. R : emplacement prioritaire où les annonces sont affichées sur la page de résultats lors du chargement. M : emplacement secondaire où les publicités sont affichées uniquement après que l’utilisateur a cliqué sur Plus de tarifs.
SubAccountId	ID de sous-compte	ID qui identifie de façon unique le sous-compte (campagne d’hébergement).
SubAccountName	Nom du sous-compte	Nom complet du sous-compte.
UserCountry	Pays de l’utilisateur	Code de pays ISO 3116 à deux lettres du pays ou de la région où se trouve l’utilisateur. Par exemple, Les États-Unis pour États-Unis. NOTE: Avant le 2 août 2018, UserCountry contient le pays ou la région de l’éditeur. Après le 2 août 2018, UserCountry contient le pays ou la région de l’utilisateur.

Colonnes de mesure

Nom de colonne	Nom de la colonne de rapport	Description
MoyenneCPC	Avg. CPC	Coût moyen par clic, qui est calculé en divisant le coût total de tous les clics par le nombre de clics. Le coût est dans la devise du compte. Les données sont disponibles à partir du 6 décembre 2017.
AverageCPCUSD	Avg. CPC USD	Coût moyen par clic, qui est calculé en divisant le coût total de tous les clics par le nombre de clics. Le coût est en dollars américains.
AveragePosition	Mo. pos.	Position moyenne des annonces sur la page de résultats. Position fait référence à l’ordre de la publicité sur la page par rapport à toutes les autres annonces sur tous les emplacements.
AverageSlotPosition	Pos d’emplacement moyen.	Position moyenne des annonces dans le type d’emplacement. Si vous incluez cette métrique, vous devez également inclure la colonne de dimension SlotType.
AvgBookedABW	Moyenne réservée ABW	Fenêtre de réservation avancée moyenne pour l’hôtel. La moyenne est calculée sous la forme (abw/conversions réservées). En savoir plus.
AvgBookedNights	Nuits réservées moy	Les nuits moyennes réservées pour l’hôtel. La moyenne est calculée comme (nombre total de nuits réservées/conversions). En savoir plus.
BookABW	Réservé ABW	Nombre total de jours de la fenêtre de réservation avancée pour l’hôtel. En savoir plus.
Clics	Clics	Nombre de fois où les annonces ont été cliquées.
Cliquez sur Partager	Cliquez sur Partager	Pourcentage de clics qui sont allés à vos annonces, sur le nombre total de clics dans le marché que vous ciblez. Par exemple, sur les 1 000 clics estimés qui se sont produits ce jour dans votre marché ciblé, vous en avez eu environ 230, soit 23 %. La valeur est comprise entre 0,0 et 1,0. En savoir plus.
Conversions	Conversions	Une réservation d’hôtel. En savoir plus.
Taux de conversion	Taux de conversion	Taux de conversions. Le taux est calculé en tant que (conversions/clics)*100. En savoir plus.
CPA	CPA	Coût par acquisition. Le coût est calculé en tant que (dépenses/conversions).
CTR	CTR	Taux de clics des annonces. Le CTR est calculé en divisant le nombre de fois où les annonces ont été cliquées par le nombre d’impressions. En savoir plus.
EligibleImpressions	Impr éligible.	Nombre total d’impressions réalisées et non réalisées (impressions plus impressions manquées). En savoir plus.
Impressions	Impr.	Nombre de fois où des annonces ont été affichées.
GrossRevenue	Chiffre d’affaires brut	Chiffre d’affaires total, taxes comprises. En savoir plus
GrossRevenuePerClick	Chiffre d’affaires brut / clic	Chiffre d’affaires brut par clic. Le chiffre d’affaires par clic est calculé comme (revenu brut/clics). En savoir plus.
GrossRevenuePerConv	Chiffre d’affaires brut / conv	Chiffre d’affaires brut par conversion. Le chiffre d’affaires par conversion est calculé comme (chiffre d’affaires brut/conversions). En savoir plus.
GrossROAS	ROAS brut	Le retour brut sur les dépenses publicitaires. Le ROAS est calculé comme (revenu brut/dépense) * 100. En savoir plus.
ImpressionShare	Impr. share	Pourcentage d’impressions, sur le total des impressions disponibles sur le marché que vous ciblez. Par exemple, sur une estimation de 59 000 impressions qui se sont produites ce jour dans votre marché ciblé, vous en avez reçu 2 300, soit 3 %. La valeur est comprise entre 0,0 et 1,0. En savoir plus.
MissedImpressions	Impr manqué.	Nombre total d’impressions perdues. Il s’agit de la somme des colonnes suivantes : MissedImpressionsInsufficientBid MissedImpressionsNoTax MissedImpressionsOther MissedImpressionsSpendingCapReached En savoir plus.
MissedImpressionsInsufficientBid	Impr manqué. enchère insuffisante	Le nombre d’impressions perdues parce que vos enchères étaient faibles et ne sont pas en concurrence sur le marché des enchères. En savoir plus.
MissedImpressionsNoTax	Impr manqué. aucune taxe	Le nombre d’impressions perdues parce que l’hôtel n’a pas spécifié de taxes. En savoir plus.
MissedImpressionsOther	Impr manqué. Autres	Nombre d’impressions perdues pour toutes les autres raisons. En règle générale, un classement faible ou votre taux était disponible dans la section Plus de taux , mais l’utilisateur n’a pas étendu la section pour afficher votre taux. En savoir plus.
MissedImpressionsSpendingCapReached	Impr manqué. plafond de dépenses atteint	Nombre d’impressions perdues parce que vous avez atteint votre limite de dépense quotidienne. En savoir plus.
NetRevenue	Chiffre d’affaires net	Chiffre d’affaires total, hors taxes. En savoir plus.
NetRevenuePerClick	Chiffre d’affaires net / cliquez sur	Chiffre d’affaires net par clic. Le chiffre d’affaires par clic est calculé comme (revenu net/clics). En savoir plus.
NetRevenueConv	Chiffre d’affaires net / conv	Chiffre d’affaires net par conversion. Le chiffre d’affaires par conversion est calculé comme (chiffre d’affaires/conversions nets). En savoir plus.
NetROAS	Net ROAS	Retour net sur les dépenses publicitaires. Le ROAS est calculé en tant que (recettes/dépenses nettes) * 100.
Passer	Passer	Coût total de tous les clics. Le coût est dans la devise du compte. Les données sont disponibles à partir du 6 décembre 2017. En savoir plus.
SpendUSD	Dépensez l’USD	Coût total de tous les clics. Le coût est en dollars américains.
TotalBookedNights	Durée réservée du séjour	Le nombre total de nuits réservées pour l’hôtel. En savoir plus.

En plus de la règle selon laquelle les demandes doivent inclure au moins une colonne de dimension et une colonne de mesure, tout rapport qui inclut des colonnes de partage de voix (SOV) doit inclure au moins l’une des colonnes de dimension suivantes.

HotelGroupId
Id d’hôtel
PartnerHotelId
SubAccountId

Voici les colonnes SOV :

Cliquez sur Partager
EligibleImpressions
ImpressionShare
MissedImpressions
MissedImpressionsInsufficientBid
MissedImpressionsNoTax
MissedImpressionsOther
MissedImpressionsSpendingCapReached

Remarque

Les données SOV sont disponibles à partir du 1er mai 2018. Si vous spécifiez une période de rapport qui inclut des dates antérieures au 1er mai 2018, les champs SOV contiennent une valeur zéro (0) pour les dates antérieures au 1er mai.

Exemple de rapport sur les performances

L’exemple suivant illustre les lignes et les colonnes d’en-tête du rapport.

"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 première ligne d’en-tête contient le nom du rapport et la période de rapport demandée. La deuxième ligne d’en-tête contient l’ID de demande du rapport. En cas de problème avec le rapport, vous utiliserez l’ID lorsque vous contactez le support technique pour obtenir de l’aide sur le problème.

Remarque

Les ID tels que l’ID d’hôtel ou l’ID de groupe d’annonces sont placés entre crochets (par exemple, [1234567890]).

Hotel Price Ads Reporting API

Demande d’un rapport

Interrogation de la status d’un travail de rapport

Téléchargement du rapport

Filtrage des données de rapport

Inclure les hôtels non performants dans le rapport

Comment IncludeNonPerformingHotels affecte-t-il la création de rapports pour les hôtels qui ont déplacé des groupes ?

Livres fermés

Colonnes du rapport de performances

Colonnes de dimension

Colonnes de mesure

Partage de la voix

Exemple de rapport sur les performances

Ressources supplémentaires