Der API Explorer

Darf ich mal ein Tool vorstellen, das eigentlich als Spielwiese für Entwickler gedacht ist? Ja? Super!

Es geht um den API Explorer auf der Developer Connection.

Dessen ursprüngliches Einsatzgebiet war als Test- und Erkundungstool für Entwickler, die mit der Reporting API arbeiten wollten (oder sollten).

Darüberhinaus finde ich ihn aber gut geeignet für Marketer oder Analysten, die sich entweder selber and die API heranwagen oder ihrem Entwicklerteam helfen wollen.

Vielleicht gehen wir einfach mal schnell einen üblichen Fall durch.

Vorbereitung

Zunächst muß man seine Zugangsdaten aus der Admin Console holen, und zwar unter Reports & Analytics > Admin > Company Settings > Web Services.

Die trägt man dann oben in die zwei Felder ein, oder besser noch in sein Profile, dann muß man das nicht jedesmal wieder tun. In Zukunft reicht es dann, sich einzuloggen (oben rechts, wo sonst?) und dann sieht das direkt so aus:

Das war’s schon mit den Vorbereitungen. Sobald Username und Passwort da stehen, kann man loslegen.

Report Anfordern

Ich würde sagen wir fangen mal mit einem ganz einfachen Report an. Wie wäre es mit den 10 meistbesuchten Seiten? Page Views und Visits als Metriken?

Ok.

Ich weiß jetzt gerade nicht die Report Suite ID aus dem Kopf, also suchen wir uns die mal schnell raus. Dazu wähle ich zuerst im Dropdown „API“ die „Company“ aus. Das darunterliegende „Method“ Menü wird jetzt geladen, und wenn es fertig ist wähle ich dort „GetReportSuites“.

(Für Entwickler: Ich bestimme hier mit 2 Dropdowns, daß ich Company.GetReportSuites aufrufen möchte. Das geht beim Programmieren einfacher. Aber macht ja nichts.)

Wir sind noch nicht ganz fertig.

Die Parameter dieser Methode sind optional (ausprobieren oder Dokumentation ansehen) und ich nehme sie daher einfach mal weg.

Dann klicke ich „Get Response“ und bekomme meine Liste im Feld unten:

So, die erste ist ja auch gleich meine! Dann können wir ja jetzt den Report abfragen.

Da wir einen Report wollen, wählen wir aus dem obersten Dropdown erst einmal „Report“ aus, das ist die API mit der man Reports verwaltet. Die Methode ist „Queue“, wie in „hinten anstellen“. Wir stellen eine Reportinganfrage an.

Auf einmal ist im Fenster ziemlich viel los, die Report.Queue Methode erwartet nämlich eine „ReportDescription“. Ohne ReportDescription wissen API und Backend nicht, was für einen Report sie liefern sollen.

Zum Glück sind seit v1.4 der Reporting API sehr viele der Werte optional. Wir nehmen einfach mal das absolute Minimum und sehen, was passiert.

Also: rsid, metrics, elements…

Ein Klick auf Get Response… wow, das klappt sogar! „Sending Request for Report.Queue()…“ und dann das:

Ich bin entzückt!

Aber wo ist der Report?

Report Abrufen

Den muß man sich abholen! Bisher ist er ja nur in der Queue und das System holt die Daten und baut ihn zusammen.

Ich kopiere mir also die reportID aus dem Resultat und rufe den Report ab. Bei „API“ wähle ich „Report“ und bei „Method“ wechsle ich auf „Get“. Dann setze ich die reportID im oberen Feld ein und klicke Get Response.

Das Resultat sieht wie folgt aus:

Das sind jetzt zwar strenggenommen nicht die Top 10, sondern nur Top 8 (und ich habe zwecks Längenbegrenzung einige Ergebnisse herausgeschnitten), aber es ist ein vollwertiger Report und ich kann ja mal erklären, was wir da sehen.

Oben im Report sieht man die Parameter – „elements“, „reportSuite“ und „metrics“ haben wir eingestellt, „type“ und „period“ hat das Backend einfach auf den Default gestellt, nämlich „ranked“ und „heute“.

Danach kommen dann die Daten. Für jede Seite wird Name und URL angezeigt sowie zwei Werte in „counts“. Der erste zeigt die PVs, der zweite die Visits. Warum? Weil das unter „metrics“ in genau der Reihenfolge definiert ist.

Weiter unten stehen unter „totals“ die Gesamtzahlen für die Metriken.

Außerdem sieht man hier, welche Version der Reporting API genau im Spiel war und wie lange Queueing und Processing gedauert haben („waitSeconds“ & „runSeconds“).

Das ist doch schon ganz gut, oder?

Vielleicht sollten wir mal probieren, ob wir etwas kaputtmachen können. Wie wäre es mit einem uninformierten Versuch, einen anderen Reportingzeitraum auszuwählen?

Vielleicht so?

Oops:

Die Reporting API liefert also bei Falschbenutzung Fehlermeldungen zurück. Das ist gut!

Machen wir es doch nochmal richtig:

Ich habe auch gleich „anomalyDetection“ und „currentData“ auf „true“ gesetzt und bekomme daher jetzt für jeden Datenpunkt (jede Seite) nicht nur ein paar Metriken, sondern gleich eine ganze Struktur:

Die Anomaly Detection liefert für jede Metrik und jedes Element drei weitere Werte:

1. upperBounds — Die obere Schranke für das Vorhersagemodell. 90% der Werte sollten unterhalb liegen
2. lowerBounds — Die untere Schranke. 90% sollten oberhalb liegen.
3. forecasts — Der vorhergesagte Wert für die Metrik.

Alle diese Werte sind in meinem Beispiel witzlos, weil ich so wenig Traffic in dieser Report Suite habe und da mit Statistik nicht viel zu holen ist. Probieren wir es doch mal mit dem Report von webanalyticsfordevelopers.com, da ist mehr los:

Sieht gut aus, oder?! Sogar nah am Forecast!

Notes

Die Werte aus der Reporting API kann ein Entwickler wunderschön in ein selbstgebautes Dashboard einbauen, insbesondere mit Anomaly Detection. Dort kann für jeden Wert eine Zone geplottet werden, in der die Werte liegen sollten, und man kann sogar für einen gewissen Zeitraum in die Zukunft die Vorhersage darstellen.

Warum sollte man als Analyst oder Marketer mit dem API Explorer spielen?

Wenn man jemals mit einem Entwickler zusammenarbeitet, der mithilfe der Reporting API Daten aus SiteCatalyst Reports & Analytics herauskitzeln soll, dann kann man ihm vielleicht direkt eine gültige und zielführende ReportDescription liefern. Sowas macht den Job einfacher!

Und zu guter Letzt noch ein Tip, den ich mir ehrlich gesagt nicht selber ausgedacht habe. Begegnet ist er mir bei einem Analysten im UK.

Es ist eine hervorragende Idee, den API Explorer in zwei Tabs zu öffnen!

Warum?

Na weil man dann in einem Tab an der ReportDescription feilen kann und im zweiten Tab jeweils die resultierenden Reports abholen. Man muß nur immer die reportID rüberkopieren.

Das tolle daran ist, daß man nicht durch den Wechsel der „method“ auf „Get“ jedesmal wieder seine ReportDescription verliert und neu machen (oder pasten) muß.

Ein ganz großer Tip!