Reports & Daten

Abruf der Reports

https://ws.etracker.com/api/v6/report

Mit diesem Abruf bekommst du eine Liste aller Reports (auch eigener), die über die Schnittstelle zur Verfügung stehen. Die Rückgabe ist ein JSON-Objekt bestehend aus Schlüssel-Wert-Paaren, in denen die Schlüssel Report-Ids und die Werte Report-Namen sind:

{ "EAPage":"Seiten", "CCOverview":"Übersicht", "72":"Mein individueller Report", …}

Report-Daten können mit den numerischen oder alphabetischen Report-Ids aufgerufen werden.

Abruf von Report- & Metadaten

Die Abfragen an der etracker REST Report API werden wie folgt aufgebaut:

https://ws.etracker.com/api/v6/report/#ReportID#/#Service#

Die verfügbaren Services sind:

Definition von etracker Reports

Die etracker Reports können als dynamische Tabellen oder sog. Data Cubes verstanden werden. Sie bestehen aus Attributen (attributes) und Kennzahlen (key figures). In der Literatur werden auch die Begriffe Dimensionen (für Attribute) und Maße (für Kennzahlen) verwendet.

Attribute beinhalten nominale oder kategorische Werte, die keine Zahlen sind, und stellen die Eigenschaften von Benutzerinteraktionen dar. Typische Attributwerte sind Namen (z.B. ‚Startseite‘ oder ‚Damenbekleidung‘), Kategorien (z.B. ‚Kunde‘, ’nicht Kunde‘) oder Zeiten (z .B. ‚2016-01-25‘ oder ‚9 Uhr‘).

Manche Attributwerte haben eine natürliche Reihenfolge (z .B. die Zeiten), die meisten können aber nicht sinnvoll bzw. nur alphabetisch sortiert werden. Wenn aus drei Attributen jeweils ein Wert selektiert werden soll, dann sprechen wir von einer Attributwertkombination oder Ausprägung. Seien z.B. die Attribute ‚Seitenname‘, ‚Land‘ und ‚Betriebssystem‘ gegeben, dann wären die Werte ‚Startseite‘, ‚Deutschland‘ und ‚Windows‘ eine Attributwertkombination und ‚Startseite‘, ‚Österreich‘, ‚Windows‘ eine weitere Attributwertkombination.

Kennzahlen beinhalten numerische Werte, die sortiert und aggregiert werden können. Kennzahlen werden immer in aggregierter Form von der REST-API zurückgegeben. Die Aggregationsmethode hängt von der Kennzahl ab. Bei der Kennzahl ‚Bounce Rate‘ wird bspw. gemittelt. Bei der Kennzahl ‚Besucher‘ wird dagegen summiert. Jede Abfrage eines Reports über die REST-API gibt eine Tabelle zurück, die eine bestimmte aggregierte Ansicht wiedergibt. Jede Kennzahl wird für jede vorhandene Attributwertkombination aggregiert. Jede Zeile in der Tabelle besteht dann aus einer Attributwertkombination gefolgt von den dazugehöigen aggregierten Kennzahlen. Zwei Zeilen einer solchen Tabelle könnten wie folgt aussehen:

Die Attributwertkombination und Kennzahlen der zweiten Zeile kann wie folgt interpretiert werden: Es gab 57 Besucher auf der Startseite aus Österreich mit dem Betriebssystem Windows und 35,09% von ihnen haben nur eine Seite aufgerufen.

Abfrage von Report Informationen

Der Abruf der Informationen und Metadaten des Reports ‚Gerät‘ erfolgt mit der folgenden Abfrage: https://ws.etracker.com/api/v6/report/EADeviceType/info

Die Rückgabe ist ein JSON-Array mit einem Element und folgender Struktur:

{
 "report": {
 "createDate": "2016-01-01 00:00:00",
 "dimensions": "1",
 "segments": "0",
 "visualizationType": "",
 },
"attributes": [
 {
 "id": "device_type",
 "label": "Ger\u00e4tetyp",
 "type": "attribute",
 "sortable": true
 },
 …
 ],
"key-figures": [
 {
 "id": "unique_visits",
 "label": "Besuche",
 "type": "integer",
 "sortable": true
 },
 …
 ]
 "views": [
 {
 "view_id": "24",
 "name": "Test Konfiguration",
 "tm": "1477324586",
 "access": "this_user",
 "is_default": false
 },
 …
}

Das Rückgabe-Objekt beinhaltet vier Unterelemente:

1. Ein report-Objekt mit allgemeinen Informationen wie das Datum, an dem ein Report erzeugt wurde.
2. Ein attributes-Array mit Metadaten zu jedem Attribut im Report.
3. Ein key-figures-Array mit Metadaten zu jeder Kennzahl im Report.
4. Ein views-Array mit Metadaten zu jeder von Benutzern definierten Ansicht des Reports.

Die Arrays zu den Attributen und Kennzahlen beinhalten Objekte mit den folgenden Daten für jedes Attribut und jede Kennzahl:

1. Das id für die Kommunikation mit der REST-API.
2. Eine für Menschen lesbare Bezeichnung (label). Die Sprache der Bezeichnungen hängt von der im Header verwendeten Account- bzw. von der Subuser-ID ab und kann über die entsprechenden Einstellungen in der etracker Applikation geändert werden.
3. Der Datentyp (type) der Werte in der Spalte.
4. Ein Boolean-Wert (‚true‘ oder ‚false‘), der angibt, ob der Report nach dem Attribut oder der Kennzahl sortiert werden kann.

Die Datentypen, die in etracker Reports vorkommen können, werden in der folgenden Tabelle beschrieben. Bei den Beispieldaten handelt es sich um Daten wie sie von der REST-API zurückgegeben werden.

Ansichten können von jedem Benutzer zu jedem Report in der etracker Applikation interaktiv definiert und gespeichert werden. Das views-Array enthält die folgenden Daten zu jeder von Benutzern definierten Ansicht:

1. Die view_id für die Kommunikation mit der REST-API.
2. Der vom Benutzer vergebene eindeutige Name (name).
3. Weitere Metadaten zur Ansicht (z. B. Zeitpunkt der Erstellung).

Abruf von Report Daten

Der Abruf der Daten des Reports ‚Gerät‘ erfolgt mit folgender Abfrage (eine Datenabfrage ohne Parameter ist möglich, wird aber nicht empfohlen): https://ws.etracker.com/api/v6/report/EADeviceType/data?limit=10

Diese Abfrage gibt Daten im JSON-Format zurück. Für CSV-Daten muss lediglich ‚data.csv‘ anstatt ‚data‘ am Ende der URI stehen. Bis auf das Rückgabeformat sind CSV- und JSON-Abfragen identisch. Deshalb beschreiben wir im Folgenden nur den Fall JSON. Die Rückgabedaten haben etwa dieses Fomat:

[
    [
        "-,-,-,-,-,-,-,-,-,-",
        "=S",
        "",
        …
        "",
        104377,
        …
        4.58239668
    ],
    [
        "373563,1417345,1426710,1426574,1426574,1430935,1373563,1373563,0,3",
        "=0",
        "Desktop",
        …
        "nicht Kunde",
        34201
        …
        2.3541867
    ],
    ...
]

Die Rückgabe ist ein JSON-Array von maximal 11 Arrays, da das Parameter-Limit gleich 10 gesetzt wurde. Jedes Array stellt einen Datensatz oder eine Zeile in der Rückgabe-Tabelle dar. Das erste Array ist immer die Zeile ‚Gesamt‘, in der die Kennzahlen über alle Attributwertkombinationen hinweg aggregiert wurden. Die anderen Arrays sind Attributwertkombinationen mit den entsprechenden aggregierten Kennzahlen. Da keine Sortiervorgaben in den Parametern angegeben wurden, ist die Reihenfolge der Zeilen beliebig.

Jede Zeile beginnt mit einer Liste der Ids der Attributwerte, die für die Attributwertkombination verwendet wurden. Jeder Attributwert hat eine Id, die verwendet werden muss, wenn ein bestimmter Attributwert über die REST-API referenziert werden soll. Die Attributwert-Ids können für die gleichen Attributwerte von etracker Account zu etracker Account variieren. Innerhalb eines Accounts sind sie aber immer eindeutig.

Das zweite Element in jeder Zeile ist eine Kennzeichnung: ‚=S‘ für die Zeile ‚Gesamt‘ und ‚=0‘ für alle anderen Zeilen. Es folgen die Attributwerte der Attributkombination in der gleichen Reihenfolge wie in den Report-Informationen und dann die Kennzahlgrößen der Kennzahlen ebenfalls in der gleichen Reihenfolge wie in den Report-Informationen. Das obige Beispiel dient der Einführung und stellt keine sinnvolle Nutzung der etracker REST-API dar. Um die REST-API sinnvoll zu verwenden, müssen der gewünschte Datenumfang und die Anordnung mithilfe von Parametern eingegrenzt werden.

Abruf von abfragespezifischen Report Metadaten

Zu jeder Daten-Abfrage eines Reports können die entsprechenden abfragespezifischen Metadaten abgerufen werden. Um die Metadaten zur obigen Abfrage zu sehen, muss lediglich ‚data‘ durch ‚metaData‘ ersetzt werden. Dabei sollten die Parameter beibehalten werden.

https://ws.etracker.com/api/v6/report/EADeviceType/metaData?limit=10 Diese Abfrage gibt ein JSON-Array mit einem Eintrag pro Spalte in der dazugehörigen Datenabfrage zurück. Die ersten beiden Einträge haben die Ids ‚id‘ und ‚tree_status‘ und den Typ ’null‘. Sie entsprechen den ersten beiden oben beschriebenen Spalten, die weder Attribute noch Kennzahlen sind.

[
 {
 "id": "id",
 "label": null,
 "type": null,
 "sortable": true
 },
 {
 "id": "tree_status",
 "label": null,
 "type": null,
 "sortable": true
 },
 {
 "id": "device_type",
 "label": "Ger\u00e4tetyp",
 "type": "attribute",
 "sortable": false
 },
 ...
]

Basis-Parameter der Report API

Dies sind die Basis-Parameter der Report API.

Die folgende Abfrage verwendet die obigen Parameter, um gezielter bei der Abfrage des Reports ‚Geräte‘ vorzugehen.

https://ws.etracker.com/api/v6/report/EADeviceType/data?startDate=2021-01-01&endDate=2021-01-31&sortColumn=unique_visits&sortOrder=1&offset=0&limit=10

Die Parameter wurden wie folgt gesetzt:

• startDate = 2021-01-01
• endDate = 2021-01-31
• sortColumn = unique_visits (Besuche)
• sortOrder = 1 (absteigend)
• offset = 0
• limit = 10

Damit werden die in Januar 2021 erfassten Daten nach der Kennzahlspalte ‚Besuche‘ absteigend sortiert und die ersten 10 Zeilen zusammen mit der Zeile ‚Gesamt‘ zurückgegeben. Falls weitere Daten erwünscht sind, können offset und limit progressiv erhöht werden, bis keine Daten mehr zurückgegeben werden. Die nächsten 10 Datensätzen wurden z. B. wie folgt abgefragt:

https://ws.etracker.com/api/v6/report/32005/data?startDate=2021-01-01&endDate=2021-01-31&sortColumn=unique_visits&sortOrder=1&offset=10&limit=10