1. Home
  2. Data Services
  3. REST-Report API
  4. Reports & Daten

Reports & Daten

Abruf der Reports

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

Mit diesem Abruf bekommen Sie 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-Paare, in denen die Schlüssel Report-Ids und die Werte Reportnamen 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 etacker Report REST API werden wie folgt aufgebaut:

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

Die verfügbaren Services sind:

ServiceBeschreibung
infoGibt allgemeine Informationen und metaDaten zu einem Report zurück
metaDataGibt Informationen zu Typen und Namen der Spalten einer bestimmten Report-Abfrage zurück
dataGibt die Daten des entsprechenden Reports im JSON-Format zurück
data.csvGibt die Daten des entsprechenden Reports im CSV-Format zurück

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 Fom 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 vohandene 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:

Attribute  Kennzahlen 
SeitennameLandBetriebssystemBesucherBounce-Rate
StartseiteDeutschalndWindows52330,45%
StartseiteÖsterreichWindows5735,09%

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 hat folgende 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 vom 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.

DatentypBeschreibungBeispiel
attributeAttribute beinhalten Zeichenketten"organisch"
attributeDateEin Datum als Zeichenkette"2016-01-15"
integerGanze Zahl132
floatGleitkommazahl2.316757394
currencyGleitkommazahl mit zwei Nachkommastellen50321.45
percentProzentsatz: Gleitkommazahl zwischen 0 und 10034.501120345
relPercentageRelativer Prozentsatz: Gleitkommazahl zwischen 0 und 10.573944096
staytimeDauer in Sekunden: Die Nachkomastellen sind Sekundenbruchteile239.355444
dateEin Datum2016-01-15
nullIds und Statusangaben, die weder Attribute noch Kennzahlen sind.

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 von Benutzern 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. In diesem Abschnitt werden wir daher nur den Fall JSON beschreiben. Die Rückgabedaten haben etwa das folgende 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

Im Folgenden werden die Basis-Parameter der Report API beschrieben. Es folgen dann Beispiele zur Erläuterung der Parameter.

ParameterLimit
BeschreibungGibt die maximale Anzahl an Datensätzen an. die zzgl. der Summenzeile zurückgegeben werden sollen
Zulässige WerteGanze Zahlen
Beispiele10, 100 oder 5000
ParameterOffset
BeschreibungGibt des Startpunkt bzw. den Datensatz unmittelbar vor dem ersten Rückgabedatensatz der Abfrage an
Zuläsige Werteganze Zahlen
Beispiele0, 10 oder 100
ParameterstartDate
BeschreibungNur Daten, die ab 00:00 Uhr am angegebenen Datum erfasst wurden, sollen für die Abfrage berücksichtigt werden
Zulässige WerteGültige Datumsangaben der Form JJJJ-MM-TT
Beispiele2016-01-23 oder 2012-10-31
ParameterendDate
BeschreibungNur Daten bis 23:59 Uhr am angegebenen Datum sollen erfasst und für die Abfrage berücksichtigt werden
Zulässige WerteGültige Datumsangaben der Form JJJJ-MM-TT
Beispiele2016-01-30 oder 2014-12-17
ParametersortColumn
BeschreibungDie dAten sollen vor der Rückgabe nach den Werten der angegebenen Spalte sortiert werden
Zulässige WerteGültige Ids von sortierbaren Spalten. Die Ids und die Sortierbarkeit sind in den Metadaten eines Reports zu finden
Beispieleunique visits oder pi per visit
ParametersortOrder
BeschreibungGibt die Richtung der Sortierung an (auf- oder absteigend)
Zulässige Werte1 für absteigend, 2 für aufsteigend

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=2016-01-01&endDate=2016-01-31&sortColumn=unique_visits&sortOrder=1&offset=0&limit=10

Die Parameter wurden wie folgt gesetzt:

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

Damit werden die in Januar 2016 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=2016-01-01&endDate=2016-01-31&sortColumn=unique_visits&sortOrder=1&offset=10&limit=10