Maßgeschneiderte Webanalyse

Das Piwik-REST-API
Kommentare

Piwik ist die führende Open-Source-Alternative (GPLv3) zu Google Analytics. Die Webanalyseplattform, die auf PHP und MySQL basiert, können Sie vom Tracking-API über Plug-ins bis hin zum REST-API an Ihre Bedürfnisse anpassen und auf einem eigenen Server installieren – und behalten dadurch die Kontrolle über alle aufgezeichneten Daten. Besonders interessant ist dabei Piwiks REST-API. Hierüber können Sie nicht nur alle vorhandenen Reporte nach Belieben abrufen, sondern die Software auch komplett verwalten. Es lassen sich sogar Funktionen wie Segmentierung nutzen, die generell vorhanden, aber nicht in das Piwik-UI integriert sind. Lesen Sie in den folgenden Abschnitten, wie das API funktioniert und was Sie damit machen können.

Piwiks REST-API besteht aus über zwanzig Objekten, die insgesamt über zweihundert Methoden enthalten. Im Artikel sei daher nur auf einige wichtige davon eingegangen. Eine ergänzende Kurzdokumentation finden Sie in Ihrer Piwik-Installation über den Menüpunkt API (Abb. 1). Die vollständige Dokumentation liegt in der API-Referenz. Sollten Ihnen diese Methoden nicht ausreichen, können Sie über Plug-ins weitere hinzufügen. Und wenn Sie Probleme beim Aufrufen des API haben, prüfen Sie in den Einstellungen von Piwik, ob einzelne Objekte oder sogar das gesamte API nicht versehentlich deaktiviert sind.

Ein API-Aufruf muss neben der Angabe des Moduls API mindestens den Namen der gewünschten Methode enthalten. Das Standard-Format ist XML. Beispiel:

http://demo.piwik.org/?module=API&method=API.getPiwikVersion 1.9.3
Abb. 1: Der Menüpunkt zur API-Kurzdokumentation. Sie finden dort Ihren Auth-Token und können mit nur einem Klick alle Methoden ausprobieren

Abb. 1: Der Menüpunkt zur API-Kurzdokumentation. Sie finden dort Ihren Auth-Token und können mit nur einem Klick alle Methoden ausprobieren

Authentifizierung

Standardmäßig ist Ihre Piwik-Installation nicht öffentlich. Die meisten API-Aufrufe benötigen daher eine Authentifizierung. Sie erfolgt über einen URL-Parameter namens token_auth. Ihren Auth-Token bekommen Sie entweder über den Menüpunkt API oder über das REST-API durch Aufrufen der Methode UsersManager.getTokenAuth. Die Methode erwartet als Parameter Ihren Benutzernamen sowie Ihr Passwort als MD5-Hash.

Achtung: Sobald Sie Ihr Passwort ändern, ändert sich auch Ihr Auth-Token (das Sie auch nicht weitergeben sollten, da andere Personen sich sonst darüber einloggen könnten). Es ist so geheim wie Ihr Benutzername und Passwort. Damit Ihr Auth-Token beim Verwenden des API nicht im Klartext übertragen wird, empfehle ich Ihnen, nach Möglichkeit HTTPS zu verwenden. API-Aufruf mit Authentifizierung:

http://demo.piwik.org/?module=API&method=API.getPiwikVersion&token_auth=d41d8cd98f00b204e9800998ecf8427e

Reportdaten abfragen

Sie haben über das API Zugriff auf alle Reporte, darunter Aktionen, benutzerdefinierte Variablen, Ziele, E-Commerce, Besucher, Referrer, Kampagnen, Suchmaschinen und Provider. Zum Abfragen der Statistiken stehen Ihnen einige Standardparameter zur Verfügung, die für die meisten Methoden Gültigkeit haben (Tabelle 1).

Parameter

Beschreibung

date

Das zu verwendende Datum, ein Datumsbereich oder Keywords wie today, yesterday, last5 oder previous42. Ein last5 gibt Ihnen die Statistiken der letzten fünf Einheiten zurück, previous42 die der vorherigen 42 Einheiten, wobei die heutige Einheit nicht inbegriffen ist. Eine Einheit entspricht der ausgewählten Dauer.

period

Die gewünschte Dauer, die day, week, month, year oder range sein kann. Wenn die Dauer eine range ist, werden die einzelnen Datensätze über den angegebenen Datumsbereich zu einem Ergebnis zusammengefasst.

idSite

Die ID einer Webseite finden Sie unter Einstellungen -> Webseiten in Ihrer Piwik-Installation oder über den Aufruf der Methode SitesManager.getAllSites.

format

Folgende Formate stehen Ihnen zur Verfügung: XML, JSON, CSV, HTML, PHP, RSS und TSV.

flat

Einige Reporte enthalten hierarchische Daten, beispielsweise die besuchten URLs. Wird dieser Parameter mit dem Wert 1 aufgerufen, so werden die Daten auf eine Ebene reduziert.

language

Wenn angegeben, werden Daten, Zeiten und Texte entsprechend lokalisiert.

hideColumns showColumns

Oft spielt die übertragene Datenmenge eine wichtige Rolle. Mit hideColumns können Sie einzelne Spalten von der Antwort entfernen. Eine Whitelist können Sie mit showColumns definieren.

Tabelle 1: Verfügbare Parameter beim Abfragen von Reportdaten, daneben stehen Ihnen noch mehr als zehn Filter- und Sortiermöglichkeiten, ein Offset und ein Limit zur Verfügung

Hier ein Beispiel, um eine Liste der verwendeten Betriebssysteme der letzten sieben Tage zu erhalten, sortiert nach der Anzahl der Aktionen:

http://demo.piwik.org/?module=API&method=UserSettings.getOS&idSite=7&period=day&date=last7&format=JSON&filter_sort_colmn=nb_actions

Einen Auszug aus der Rückgabe zeigt Listing 1. Abbildung 2 zeigt eine Liste der verfügbaren APIs.

[…,
{
label: "Windows 7",
nb_uniq_visitors: 243,
nb_visits: 259,
nb_actions: 587,
max_actions: 25,
sum_visit_length: 36059,
bounce_count: 182,
nb_visits_converted: 9,
logo: "plugins/UserSettings/images/os/WI7.gif",
shortLabel: "Win 7"
},
…]
Abb. 2: Eine Auflistung der verfügbaren APIs

Abb. 2: Eine Auflistung der verfügbaren APIs

Fehlerbehandlung

Tritt beim Aufruf des API ein Fehler auf, erhält man ein Objekt mit result und message zurück.

{ result: "error", message: "Sie können auf die Ressource nicht zugreifen, da Sie dafür mindestens 'superuser' Rechte benötigen." }

Live-API

Das Live-API gibt Ihnen Zugriff auf alle Besucher und Aktionen Ihrer Website, auf Wunsch in Echtzeit. Interessant ist das beispielsweise für Dashboards, um die derzeitigen Besucher im Blick zu behalten. In der Piwik-Mobile-App beruhen das „Besucher-Log“ und die „Besucher in Echtzeit“ auf den Daten des API. Es beinhaltet zwei Methoden:

Die erste Methode Live.getCounters gibt die Anzahl der Besucher, der Aktionen und der erreichten Ziele aus den letzten x Minuten zurück. Will man wissen, wie viele Besucher in den letzten 30 Minuten auf einer Webseite waren, nutzt man folgenden Aufruf:

http://demo.piwik.org/?module=API&method=Live.getCounters&idSite=7&lastMinutes=30&format=JSON

Ausgabe:

[{"visits":"42","actions":"97","visitsConverted":"1"}]

Die zweite Methode Live.getLastVisitsDetails liefert Ihnen wirklich alle Informationen, die über Ihre aktuellen Besucher gespeichert sind. Allein die Daten zu einem einzelnen Besucher könnten hier eine Seite füllen. Darin enthalten sind unter anderem die von ihm ausgeführten Aktionen, wie er auf die Seite kam und die Eigenschaften seines Browsers.

http://demo.piwik.org/?module=API&method=Live.getLastVisitsDetails&idSite=7&period=day&date=today&format=JSON

Wenn Sie sich nicht für Ihre aktuellen Besucher interessieren, können Sie auch Besucher aus der Vergangenheit sowie individuelle Besucher abrufen. Zum Beispiel, um Ihre Besucher mit einer anderen Benutzerdatenbank abzugleichen. Um diejenigen Besucher abzufragen, die ab einem bestimmten Zeitpunkt auf Ihrer Website waren, verwenden Sie den Parameter minTimestamp:

http://demo.piwik.org/?module=API&method=Live.getLastVisitsDetails&idSite=7&period=day&date=today&format=JSON&minTimestamp=1353960661

Mehr Informationen dazu erhalten Sie in der Piwik-Real-Time-Analytics-Dokumentation.

Weiter mit: Teil 2

Alle Teile: Teil 1, Teil 2

Unsere Redaktion empfiehlt:

Relevante Beiträge

Meinungen zu diesem Beitrag

X
- Gib Deinen Standort ein -
- or -