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 FilterReportJob-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 HotelGroupIdverwendenSubaccountId, 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.

  1. Datum
  2. SubaccountId/Name
  3. HotelGroupId/Name
  4. HotelId/Name, PartnerHotelId
  5. HotelCountry
  6. UserCountry
  7. SlotType
  8. LengthOfStay
  9. 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.
  • 1 (Montag)
  • 2 (Dienstag)
  • 3 (Mittwoch)
  • 4 (Donnerstag)
  • 5 (Freitag)
  • 6 (Samstag)
  • 7 (Sonntag)
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.
  • DefaultDate – Der Benutzer hat nicht nach Hotels mit bestimmten Datumsangaben gesucht.
  • SelectedDate – Der Benutzer hat nach Hotels mit bestimmten Datumsangaben gesucht.
DeviceType Gerätetyp Der Gerätetyp, auf dem die Anzeigen angezeigt wurden. Im Folgenden sind die möglichen Werte aufgeführt.
  • Desktop
  • Mobilgeräte
  • Tablet
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.
  • LocalUniversal– Der Benutzer hat Bing.com verwendet, um nach Hotels zu suchen.
  • MapResults– Der Benutzer hat Bing.com/maps verwendet, um nach Hotels zu suchen.
  • PropertyPromotionAd – Der Benutzer hat sich die erste Ergebnisseite in der Kartensuche angeschaut.
SlotType Slottyp Die Platzierung der Anzeigen auf der Ergebnisseite. Im Folgenden sind die möglichen Werte aufgeführt.
  • A – Der Prioritätsslot, in dem Anzeigen beim Laden auf der Ergebnisseite angezeigt werden.
  • M – Der sekundäre Slot, in dem Anzeigen erst angezeigt werden, nachdem der Benutzer auf Weitere Preise geklickt hat.
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
  • MissedImpressionsNoTax
  • MissedImpressionsWeitere
  • MissedImpressionsSpendingCapReached
Weitere Informationen...
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:

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]).