Berichterstellungs-API für Hotelpreisanzeigen
Hinweis
Diese Betaversion von HotelPreisanzeigen ist nur für ausgewählte Teilnehmer verfügbar. Informationen zur Teilnahme am Beta-Release-Programm finden Sie bei Ihrem Account Manager, oder registrieren Sie sich hier.
Api und Dokumentation können geändert werden.
Die Berichterstellung ist ein asynchroner Prozess. Es folgt der allgemeine Ablauf zum Anfordern eines Berichts.
- Erstellen einer Anforderung mit den Berichtsparametern
- Senden einer Anforderung an den Berichterstellungsdienst
- Der Dienst stellt die Anforderung in die Warteschlange, bis er sie verarbeiten kann.
- Rufen Sie den Dienst in regelmäßigen Abständen ab, um die status des Berichtsauftrags zu erhalten.
- Wenn die status Abgeschlossen ist, verwenden Sie die URL, die der Dienst bereitstellt, um den Bericht herunterzuladen.
Ein Beispiel zum Anfordern und Herunterladen eines Berichts finden Sie unter Berichtscodebeispiel.
Anfordern eines Berichts
Um einen Bericht anzufordern, senden Sie eine HTTP POST-Anforderung an den folgenden Endpunkt (informationen zum Sandboxendpunkt finden Sie unter Endpunkte):
https://partner.api.bingads.microsoft.com/Travel/v1/Customers({customerId})/Accounts({accountId})/ReportJobs
Der Text der Anforderung ist ein ReportJob-Objekt . Sie müssen die folgenden Felder in der Anforderung angeben:
- StartDate – Der Anfang des Berichtszeitraums
- EndDate – Das Ende des Berichtszeitraums
- Spalten – Die Spalten, die in den Bericht aufgenommen werden sollen
- ReportType – Der Typ des berichts oder der Entität, der heruntergeladen werden soll
Alle anderen Felder sind optional.
Die niedrigste verfügbare Granularität ist täglich (stündlich wird nicht unterstützt). Wenn Columns
die Spalte Date (Datum) enthält, enthält der Bericht Zeilen für jeden Tag im StartDate
Fenster und EndDate
einschließlich. Wenn Sie Date nicht einschließen, zeigen die Berichtsdaten die Gesamtleistungszusammenfassung für das angegebene Start- und Enddatum an.
Das folgende Beispiel zeigt eine ReportJob
Anforderung für einen Leistungsbericht.
{
"ReportType":"Performance",
"StartDate":"2017-11-06",
"EndDate":"2017-11-13",
"Columns":[
"HotelId",
"Clicks"
]
}
Standardmäßig generiert der Dienst Berichte im unkomprimierten CSV-Format. Um den Bericht zu komprimieren und die Downloadleistung zu verbessern, schließen Sie das Feld Komprimierung ein, und legen Sie es auf ZIP fest.
Die Antwort auf die POST enthält eine Berichtsauftrags-ID (siehe AddResponse). Zum Beispiel:
{
"value":"1080"
}
Abrufen der status eines Berichtsauftrags
Nachdem Sie die ID abgerufen haben, verwenden Sie sie, um die status des Berichtsauftrags abzurufen. Um die status abzurufen, senden Sie eine HTTP GET-Anforderung an:
https://partner.api.bingads.microsoft.com/Travel/v1/Customers({customerId})/Accounts({accountId})/ReportJobs('{jobId}')
Der Berichtsauftrag ist nach Abschluss eines unbestimmten Zeitraums gültig, in der Regel aber mindestens sieben Tage. Nach sieben Tagen sollten Sie eine neue Berichtsanforderung übermitteln.
Der Text der Antwort ist ein ReportJob-Objekt . Um die status des Auftrags zu bestimmen, greifen Sie auf das Status
Feld zu. Wenn der Auftrag abgeschlossen ist, wird auf Abgeschlossen festgelegt, Status
und das Url
Feld enthält die URL, die Sie zum Herunterladen des Berichts verwenden. Die URL ist sieben Tage lang gültig. Wenn die URL abläuft, müssen Sie eine neue Auftragsanforderung übermitteln.
Wie lange es dauert, bis Berichtsaufträge abgeschlossen sind, ist unbestimmt und basiert auf mehreren Variablen, die die Anzahl der Aufträge in der Warteschlange, die Datenmenge und die Größe des Berichtszeitraums ständig ändern. Im Allgemeinen sollten Sie die status des Auftrags alle fünf Sekunden abfragen, bis die status des Auftrags abgeschlossen oder fehlgeschlagen ist.
Herunterladen des Berichts
Wenn die status des Berichtsauftrags Abgeschlossen ist, enthält das Feld des Url
Auftrags die URL, die Sie zum Herunterladen des Berichts verwenden. Um den Bericht herunterzuladen, senden Sie eine HTTP GET-Anforderung an die angegebene URL.
Wenn Sie die Download-URL zum Herunterladen des Berichts verwenden, geben Sie den Autorisierungsheader nicht wie bei den anderen Berichtsanforderungen an. verwenden Sie einfach die Download-URL.
Bei nicht komprimierten Berichten enthält der Content-Type-Header der GET-Antwort text/csv. Bei komprimierten Berichten enthält der Header application/zip.
Wenn Sie den Dienst aufgefordert haben, die Daten des Berichts zu komprimieren (siehe Feld des Berichtsauftrags Compression
), platziert der Dienst die Datei in einem Ordner und verwendet die ZIP-Komprimierung, um den Bericht zu komprimieren. Denken Sie daran, den Ordner zu dekomprimieren, bevor Sie auf den Bericht zugreifen und diesen lesen. Der Name der Berichtsdatei wird automatisch generiert und weist die Form performance-request-ID<> auf.
Filtern von Berichtsdaten
Um die Daten im Bericht zu filtern, verwenden Sie das Feld des Filter
ReportJob-Objekts. Sie können den Bericht nach den folgenden Dimensionsspalten und einer beliebigen Measurespalte filtern. Bei Spaltennamen wird die Groß-/Kleinschreibung beachtet.
- SubaccountId
- SubaccountName
- HotelGroupId
- HotelGroupName
- HotelId
- HotelName
- HotelStatus
- PartnerHotelId
- DeviceType
Die Verwendung von Filtern ist ein AND-Vorgang. Wenn Sie beispielsweise nach HotelPartnerId gleich 123 und DeviceType gleich Mobile filtern, enthält der Bericht nur Daten, bei denen die Hotel-ID des Partners 123 ist UND der Gerätetyp mobil ist.
Um die Daten eines Berichts zu filtern, legen Sie auf eine OData-$filter Zeichenfolge festFilter
. Das folgende Beispiel zeigt, wie Sie den Bericht nach Anzeigen filtern, die auf Desktops und Tablets angezeigt werden. Bei den Enumerationswerten, die Sie im Filter verwenden, wird die Groß-/Kleinschreibung beachtet. Verwenden Sie beispielsweise Desktop anstelle von 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'",
}
Zusätzlich zur Verwendung des Filter
Felds können Sie die SubaccountId
Felder und HotelGroupId
verwenden, um den Bericht auf ein bestimmtes Unterkonto oder eine bestimmte Hotelgruppe zu beschränken. Die Verwendung dieser Felder, um den Bereich auf ein einzelnes Unterkonto oder eine Hotelgruppe zu beschränken, bietet eine bessere Leistung als die Verwendung von Filter
. Wenn Sie und HotelGroupId
verwendenSubaccountId
, geben Sie diese nicht auch im Filter an.
Einschließen von Nicht-Leistungshotels in den Bericht
Standardmäßig enthält der Leistungsbericht nur Hotels, die während des Berichtszeitraums Aufrufe aufweisen. Um Hotels einzuschließen, die während des Berichtszeitraums keine Impressionen hatten, legen Sie das Feld IncludeNonPerformingHotels in der Berichtsanforderung auf true fest.
{
"ReportType":"Performance",
"StartDate":"2017-11-06",
"EndDate":"2017-11-13",
"Columns":[
"HotelId",
"PartnerHotelId",
"Clicks",
"Impressions"
],
"IncludeNonPerformingHotels" : true
}
Wenn Sie im Bericht nicht leistungsfähige Hotels anfordern, darf die columns
Eigenschaft nicht die folgenden Dimensionsspalten enthalten:
- Datum
- DeviceType
- HotelCountry
- LengthOfStay
- SlotType
- UserCountry
Wenn die columns
-Eigenschaft eines der oben genannten Felder enthält, schlägt die Anforderung von Berichtsaufträgen fehl.
Wie wirkt sich IncludeNonPerformingHotels auf die Berichterstellung für Hotels aus, die Gruppen verschoben haben?
Standardmäßig enthält der Bericht Hotelleistungsdaten für das Hotel, unabhängig davon, ob Sie den Bericht nach Hotel, Hotelgruppe oder Unterkonto segmentieren. Das Verschieben des Hotels von einer Gruppe in eine andere wirkt sich nicht auf das Standardberichtsverhalten aus. Wenn der Bericht beispielsweise die Hotelspalte enthält, enthält der Bericht alle Leistungsdaten für das Hotel während des angegebenen Zeitraums.
Date Hotel ID Clicks
1-1-2018 5678 12
Wenn Sie die Hotelspalte und die Spalte "Hotelgruppe" einschließen, enthält der Bericht Hotelleistungsdaten, die für jede Hotelgruppe während des angegebenen Zeitraums aufgetreten sind.
Date Hotel group ID Hotel ID Clicks
1-1-2018 1234 5678 2
2-1-2018 9876 5678 10
Die Dinge ändern sich jedoch, wenn Sie die IncludeNonPerformingHotels-Anforderungseigenschaft einschließen. Bei "true" enthält der Bericht nur Leistungsdaten für aktive Hotel- und Hotelgruppenzuordnungen. Dies bedeutet, dass sich das obige Beispiel für den Hotelbericht wie folgt ändert:
Date Hotel ID Clicks
1-1-2018 5678 10
Und das Beispiel für die Hotelgruppe ändert sich in:
Date Hotel group ID Hotel ID Clicks
2-1-2018 9876 5678 10
Bücher geschlossen
Informationen zum Schließen von Büchern finden Sie unter Bestimmen, wann Bücher geschlossen werden. Die Bestimmung, wann Bücher für Hotelpreisanzeigen geschlossen werden, ist mit den folgenden Ausnahmen identisch mit microsoft Advertising-Kampagnen:
- Der Berichtsdienst von Hotel Price Ads verwendet die Zeitzone des Kontos.
- Der Berichtsdienst von Hotel Price Ads unterstützt ReturnOnlyCompleteData nicht.
Leistungsberichtsspalten
Berichte enthalten Dimensionsspalten und Measurespalten (Metriken). Die Metrikdaten werden nach den Dimensionsspalten segmentiert. Dies bedeutet, dass für die Metrikdaten ein Rollup zur Dimension der untersten Ebene in der Dimensionshierarchie ausgeführt wird, die Sie in Ihrer Berichtsanforderung angeben.
Im Folgenden ist die Dimensionshierarchie für den Leistungsbericht dargestellt.
- Datum
- SubaccountId/Name
- HotelGroupId/Name
- HotelId/Name, PartnerHotelId
- HotelCountry
- UserCountry
- SlotType
- LengthOfStay
- DeviceType
Wenn die Anforderung z. B. SubaccountId und Clicks enthält, wird für die Klicks ein Rollup zu SubaccountId ausgeführt.
Datum | Unterkonto | Klicks |
---|---|---|
2017-11-16 | 123 | 40 |
Und wenn die Anforderung SubaccountId, HotelGroupId und Clicks enthält, wird für die Klicks ein Rollup zu HotelGroupId ausgeführt.
Datum | Unterkonto | Hotelgruppe | Klicks |
---|---|---|---|
2017-11-16 | 123 | 987 | 12 |
2017-11-16 | 123 | 654 | 13 |
2017-11-16 | 123 | 321 | 15 |
Die Anforderung muss mindestens eine Dimensionsspalte und eine Measurespalte enthalten.
Dimensionsspalten
Spaltenname | Berichtsspaltenname | Beschreibung |
---|---|---|
AdvancedBookingWindow | Adv. Buchungsfenster | Die Anzahl der Tage vor dem Check-in-Datum, an dem der Benutzer das Hotelzimmer buchen möchte. Wenn heute beispielsweise der 3. Mai ist und der Benutzer einen Raum für den 8. Mai buchen möchte, ist der Wert der Spalte 5. |
CheckinDay | Checkin Day | Der Wochentag, an dem der Benutzer beim Hotel einchecken möchte. Im Folgenden sind die möglichen ganzzahligen Werte aufgeführt.
|
Datum | Datum | Ein Datum innerhalb des Berichtszeitraums. Diese Spalte wird dem Bericht automatisch hinzugefügt, wenn sie nicht angegeben wird. Das Format ist JJJJ-MM-TT (z. B. 2017-11-16). |
Datetype.fromstring | Datumstyp | Gibt an, ob der Benutzer nach Hotels mit bestimmten Datumsangaben gesucht hat. Im Folgenden sind die möglichen Werte aufgeführt.
|
DeviceType | Gerätetyp | Der Gerätetyp, auf dem die Anzeigen angezeigt wurden. Im Folgenden sind die möglichen Werte aufgeführt.
|
HotelCountry | Hotelland | Der zweistellige ISO 3116-Ländercode des Landes oder der Region, in dem bzw. der sich das Hotel befindet. Beispiel: USA für USA. |
HotelGroupId | Hotelgruppen-ID | Die ID, die die Hotelgruppe eindeutig identifiziert. |
HotelGroupName | Name der Hotelgruppe | Der Anzeigename der Hotelgruppe. |
HotelId | Hotel-ID | Die ID, die das Hotel eindeutig identifiziert. |
HotelName | Hotelname | Der Name des Hotels. |
LengthOfStay | Verweildauer | Die Dauer des Aufenthalts der Reiseroute. |
PartnerHotelId | Partnerhotel-ID | Die ID, die der Partner verwendet, um das Hotel eindeutig zu identifizieren. |
SiteType | Websitetyp | Die Bing-Website, die Benutzer verwendet haben, um nach Hotels zu suchen. Im Folgenden sind die möglichen Werte aufgeführt.
|
SlotType | Slottyp | Die Platzierung der Anzeigen auf der Ergebnisseite. Im Folgenden sind die möglichen Werte aufgeführt.
|
SubAccountId | Unterkonto-ID | Die ID, die das Unterkonto (Unterkunftskampagne) eindeutig identifiziert. |
SubAccountName | Name des Unterkontos | Der Anzeigename des Unterkontos. |
UserCountry | Benutzerland | Der aus zwei Buchstaben bestehende ISO 3116-Ländercode des Landes oder der Region, in dem bzw. der sich der Benutzer befindet. Beispiel: USA für USA. HINWEIS: Vor dem 2. August 2018 enthält UserCountry das Land oder die Region des Herausgebers. Nach dem 2. August 2018 enthält UserCountry das Land oder die Region des Benutzers. |
Measurespalten
Spaltenname | Berichtsspaltenname | Beschreibung |
---|---|---|
AverageCPC | Durchschn. CPC | Die durchschnittlichen Kosten pro Klick, die berechnet werden, indem die Gesamtkosten aller Klicks durch die Anzahl der Klicks dividiert werden. Die Kosten werden in der Währung des Kontos angegeben. Die Daten sind ab dem 6. Dezember 2017 verfügbar. |
MittelwertCPCUSD | Durchschn. CPC USD | Die durchschnittlichen Kosten pro Klick, die berechnet werden, indem die Gesamtkosten aller Klicks durch die Anzahl der Klicks dividiert werden. Die Kosten werden in US-Dollar angegeben. |
AveragePosition | Durchschn. pos. | Die durchschnittliche Position von Anzeigen auf der Ergebnisseite. Position bezieht sich auf die Reihenfolge der Anzeige auf der Seite relativ zu allen anderen Anzeigen in allen Slots. |
AverageSlotPosition | Durchschn. slot pos. | Die durchschnittliche Position von Anzeigen im Slottyp. Wenn Sie diese Metrik einschließen, sollten Sie auch die Spalte SlotType-Dimension einschließen. |
AvgBookedABW | Durchschn. Gebuchte ABW | Das durchschnittliche Vorverkaufsfenster für das Hotel. Der Durchschnitt wird als (gebuchte ABW/Konvertierungen) berechnet. Weitere Informationen... |
AvgBookedNights | Durchschn. Gebuchte Nächte | Die durchschnittlich gebuchten Übernachtungen für das Hotel. Der Durchschnitt wird berechnet als (insgesamt gebuchte Übernachtungen/Konvertierungen). Weitere Informationen... |
GebuchtABW | Gebuchte ABW | Die gesamten Tage des Vorverkaufsfensters für das Hotel. Weitere Informationen... |
Klicks | Klicks | Die Anzahl der Klicks auf Anzeigen. |
Klicken Sie auf Freigeben. | Klicken Sie auf Freigeben. | Der Prozentsatz der Klicks, die an Ihre Anzeigen gingen, von der Gesamtzahl der Klicks auf dem Markt, auf den Sie abzielen. Von den geschätzten 1.000 Klicks an diesem Tag in Ihrem Zielmarkt hatten Sie beispielsweise etwa 230 oder 23 %. Der Wert liegt im Bereich von 0,0 bis 1,0. Weitere Informationen... |
Konvertierungen | Konvertierungen | Eine Hotelbuchung. Weitere Informationen... |
ConversionRate | Umrechnungskurs | Die Rate der Konvertierungen. Die Rate wird als (Konvertierungen/Klicks)*100 berechnet. Weitere Informationen... |
CPA | CPA | Die Kosten pro Erwerb. Die Kosten werden als (Ausgaben/Konvertierungen) berechnet. |
CTR | CTR | Die Klickrate der Anzeigen. DIE CTR wird berechnet, indem die Anzahl der Klicks auf die Anzeigen durch die Anzahl der Aufrufe dividiert wird. Weitere Informationen... |
EligibleImpressions | Berechtigte impr. | Die Gesamtzahl der realisierten und nicht realisierten Impressionen (Impressionen plus verpasste Impressionen). Weitere Informationen... |
Eindrücke | Impr. | Gibt an, wie oft Anzeigen angezeigt wurden. |
GrossRevenue | Bruttoumsatz | Der Gesamtumsatz, einschließlich Steuern. Weitere Informationen |
GrossRevenuePerClick | Bruttoumsatz / Klick | Der Bruttoumsatz pro Klick. Der Umsatz pro Klick wird berechnet als (Bruttoumsatz/Klicks). Weitere Informationen... |
GrossRevenuePerConv | Bruttoumsatz / conv | Der Bruttoumsatz pro Konvertierung. Der Umsatz pro Konvertierung wird als (Bruttoumsatz/Konvertierungen) berechnet. Weitere Informationen... |
GrossROAS | Brutto-ROAS | Die Bruttorendite der Anzeigenausgaben. Der ROAS wird als (Bruttoumsatz/Ausgaben) * 100 berechnet. Weitere Informationen... |
ImpressionShare | Impr. teilen | Der Prozentsatz der Impressionen, von den gesamten verfügbaren Impressionen auf dem Markt, auf den Sie abzielen. Von den geschätzten 59.000 Aufrufen, die an diesem Tag in Ihrem Zielmarkt aufgetreten sind, haben Sie beispielsweise 2.300 oder 3 % erhalten. Der Wert liegt im Bereich von 0,0 bis 1,0. Weitere Informationen... |
MissedImpressions | Verpasst impr. | Die Gesamtzahl der verlorenen Impressionen. Dies ist die Summe der folgenden Spalten:
|
MissedImpressionsInsufficientBid | Verpasst impr. unzureichendes Gebot | Die Anzahl der Impressionen verloren, weil Ihre Gebote niedrig waren und nicht gut im Auktionsmarkt traten. Weitere Informationen... |
MissedImpressionsNoTax | Verpasst impr. keine Steuern | Die Anzahl der verlorenen Eindrücke, weil das Hotel keine Steuern angegeben hat. Weitere Informationen... |
MissedImpressionsWeitere | Verpasst impr. Andere | Die Anzahl der verlorenen Eindrücke aus allen anderen Gründen. In der Regel war eine niedrige Rangfolge oder Ihre Rate im Abschnitt Weitere Tarife verfügbar, aber der Benutzer hat den Abschnitt nicht erweitert, um Ihre Rate anzuzeigen. Weitere Informationen... |
MissedImpressionsSpendingCapReached | Verpasst impr. Ausgabenobergrenze erreicht | Die Anzahl der verlorenen Impressionen, weil Sie Ihr tägliches Ausgabenlimit erreicht haben. Weitere Informationen... |
NetRevenue | Nettoumsatz | Der Gesamtumsatz ohne Steuern. Weitere Informationen... |
NetRevenuePerClick | Nettoumsatz / Klick | Der Nettoumsatz pro Klick. Der Umsatz pro Klick wird als (Nettoumsatz/Klicks) berechnet. Weitere Informationen... |
NetRevenueConv | Nettoumsatz / conv | Der Nettoumsatz pro Konvertierung. Der Umsatz pro Konvertierung wird als (Nettoumsatz/Konvertierungen) berechnet. Weitere Informationen... |
NetROAS | Net ROAS | Die Nettorendite der Anzeigenausgaben. Der ROAS wird als (Nettoumsatz/Ausgaben) * 100 berechnet. |
Verbringen | Verbringen | Die Gesamtkosten aller Klicks. Die Kosten werden in der Währung des Kontos angegeben. Die Daten sind ab dem 6. Dezember 2017 verfügbar. Weitere Informationen... |
SpendUSD | Ausgeben von USD | Die Gesamtkosten aller Klicks. Die Kosten werden in US-Dollar angegeben. |
TotalBookedNights | Gebuchte Aufenthaltsdauer | Die gesamt gebuchten Übernachtungen für das Hotel. Weitere Informationen... |
Anteil der Stimme
Zusätzlich zu der Regel, dass Anforderungen mindestens eine Dimensionsspalte und eine Measurespalte enthalten müssen, muss jeder Bericht, der SOV-Spalten (Share of Voice) enthält, mindestens eine der folgenden Dimensionsspalten enthalten.
- HotelGroupId
- HotelId
- PartnerHotelId
- SubAccountId
Im Folgenden sind die SOV-Spalten aufgeführt:
- Klicken Sie auf Freigeben.
- EligibleImpressions
- ImpressionShare
- MissedImpressions
- MissedImpressionsInsufficientBid
- MissedImpressionsNoTax
- MissedImpressionsWeitere
- MissedImpressionsSpendingCapReached
Hinweis
SOV-Daten sind ab dem 1. Mai 2018 verfügbar. Wenn Sie einen Berichtszeitraum angeben, der Datumsangaben vor dem 1. Mai 2018 enthält, enthalten die SOV-Felder einen Wert von null (0) für Datumswerte vor dem 1. Mai.
Beispielbericht zur Leistung
Im Folgenden finden Sie ein Beispiel für die Kopfzeilen und Spalten des Berichts.
"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
Die erste Kopfzeile enthält den Namen des Berichts und den angeforderten Berichtszeitraum. Die zweite Headerzeile enthält die Anforderungs-ID des Berichts. Wenn ein Problem mit dem Bericht vorliegt, verwenden Sie die ID, wenn Sie sich an den Support wenden, um Hilfe zu dem Problem zu erhalten.
Hinweis
IDs wie die Hotel-ID oder die Anzeigengruppen-ID sind in eckigen Klammern eingeschlossen (z. B. [1234567890]).