Core Reporting API – Referenzhandbuch

Dieses Dokument enthält die vollständige Referenz für Abfragen und Antworten für die Core Reporting API Version 3.0.

Einführung

Sie fragen die Core Reporting API für Google Analytics-Berichtsdaten ab. Für jede Abfrage sind eine Datenansichts-ID (Profil), ein Start- und Enddatum und mindestens ein Messwert erforderlich. Sie können auch zusätzliche Abfrageparameter wie Dimensionen, Filter und Segmente angeben, um Ihre Abfrage zu verfeinern. In der Übersicht finden Sie Informationen zum Zusammenwirken dieser Konzepte.

Anfragen

Die API bietet eine einzelne Methode zum Anfordern von Daten:

analytics.data.ga.get()

Diese Methode wird in verschiedenen Clientbibliotheken bereitgestellt und verfügt über sprachspezifische Schnittstellen zum Festlegen der Abfrageparameter.

Die API kann auch als RESTful-Endpunkt abgefragt werden:

Authorization: Bearer {oauth2-token}

GET https://www.googleapis.com/analytics/v3/data/ga
  ?ids=ga:12345
  &start-date=2008-10-01
  &end-date=2008-10-31
  &metrics=ga:sessions,ga:bounces

Jeder URL-Suchparameter gibt einen API-Suchparameter an, der URL-codiert sein muss.

Zusammenfassung der Suchparameter

In der folgenden Tabelle sind alle Abfrageparameter zusammengefasst, die von der Core Reporting API akzeptiert werden. Klicken Sie auf die einzelnen Parameternamen, um eine detaillierte Beschreibung zu erhalten.

Name Wert Erforderlich Zusammenfassung
ids string ja Die eindeutige Tabellen-ID im Format ga:XXXX, wobei XXXX die ID der Analytics-Datenansicht bzw. des Analytics-Profils ist, für die die Daten mit der Abfrage abgerufen werden.
start-date string ja Startdatum für das Abrufen von Analytics-Daten. Anfragen können ein Startdatum im Format YYYY-MM-DD oder ein relatives Datum (z.B. today, yesterday oder NdaysAgo, wobei N eine positive Ganzzahl ist.
end-date string ja Enddatum für das Abrufen von Analytics-Daten. In der Anfrage kann ein Enddatum im Format YYYY-MM-DD oder ein relatives Datum (z.B. today, yesterday oder NdaysAgo, wobei N eine positive Ganzzahl ist.
metrics string ja Eine Liste mit durch Kommas getrennten Messwerten, z. B. ga:sessions,ga:bounces.
dimensions string nein Eine Liste mit durch Kommas getrennten Dimensionen für Ihre Analytics-Daten, z. B. ga:browser,ga:city.
sort string nein Eine Liste mit durch Kommas getrennten Dimensionen und Messwerten, die die Sortierreihenfolge und -richtung für die zurückgegebenen Daten angeben.
filters string nein Dimensions- oder Messwertfilter, die die für Ihre Anfrage zurückgegebenen Daten einschränken.
segment string nein Die für Ihre Anfrage zurückgegebenen Daten werden segmentiert.
samplingLevel string nein Die gewünschte Stichprobenebene. Zulässige Werte:
  • DEFAULT: gibt die Antwort mit einer Stichprobengröße zurück, die ein Gleichgewicht zwischen Geschwindigkeit und Genauigkeit herstellt.
  • FASTER: gibt eine schnelle Antwort mit einer kleineren Stichprobengröße zurück.
  • HIGHER_PRECISION: Gibt mit einer großen Stichprobengröße eine genauere Antwort zurück. Dies kann jedoch dazu führen, dass die Antwort langsamer ist.
include-empty-rows boolean nein Die Standardeinstellung ist „true“. Wenn „false“ festgelegt ist, werden Zeilen, in denen alle Messwerte null sind, aus der Antwort ausgeschlossen.
start-index integer nein Die erste Zeile mit abzurufenden Daten, beginnend bei 1. Verwenden Sie diesen Parameter als Paginierungsmechanismus zusammen mit dem Parameter max-results.
max-results integer nein Die maximale Anzahl von Zeilen, die in die Antwort aufgenommen werden sollen.
output string nein Der gewünschte Ausgabetyp für die in der Antwort zurückgegebenen Analytics-Daten. Zulässige Werte sind json und dataTable. Standardeinstellung: json.
fields string nein Auswahl, mit der eine Teilmenge von Feldern angegeben wird, die in der Antwort enthalten sein soll.
prettyPrint string nein Gibt die Antwort mit Einzügen und Zeilenumbrüchen zurück. Standard false.
userIp string nein Gibt die IP-Adresse des Endnutzers an, für den der API-Aufruf erfolgt. Wird verwendet, um die Nutzung pro IP-Adresse zu beschränken.
quotaUser string nein Alternative zu userIp in Fällen, in denen die IP-Adresse des Nutzers unbekannt ist.
access_token string nein Eine Möglichkeit, ein OAuth 2.0-Token bereitzustellen.
callback string nein Name der JavaScript Callback-Funktion für die Antwortbehandlung. Wird in JavaScript JSON-P-Anfragen verwendet.
key string nein Wird für die OAuth 1.0a-Autorisierung verwendet, um die Anwendung anzugeben, für die das Kontingent abgerufen werden soll. Beispiel: key=AldefliuhSFADSfasdfasdfASdf.

Details zu Suchparametern

ids

ids=ga:12345
Erforderlich.
Die eindeutige ID, die zum Abrufen der Analytics-Daten verwendet wird. Diese ID ist die Verkettung des Namespace ga: mit der ID der Analytics-Datenansicht (Profil). Sie können die ID der Datenansicht (des Profils) mit der Methode analytics.management.profiles.list abrufen, die die id in der Ressource „Datenansicht (Profil)“ in der Google Analytics Management API bereitstellt.

Startdatum

start-date=2009-04-20
Erforderlich.
Bei allen Analytics-Datenanfragen muss ein Zeitraum angegeben sein. Wenn Sie die Parameter start-date und end-date nicht in die Anfrage aufnehmen, gibt der Server einen Fehler zurück. Datumswerte können sich auf ein bestimmtes Datum beziehen, indem Sie das Muster YYYY-MM-DD verwenden, oder relativ, indem Sie today, yesterday oder das Muster NdaysAgo verwenden. Werte müssen mit [0-9]{4}-[0-9]{2}-[0-9]{2}|today|yesterday|[0-9]+(daysAgo) übereinstimmen.
Die früheste gültige start-date ist 2005-01-01. Für das Startdatum gibt es keine Obergrenze.
Relative Datumsangaben beziehen sich immer auf das aktuelle Datum zum Zeitpunkt der Abfrage und basieren auf der Zeitzone der Ansicht (Profil), die in der Abfrage angegeben ist.

Beispiel für einen Zeitraum der letzten 7 Tage (beginnend am Vortag) mit relativen Datumsangaben:

  &start-date=7daysAgo
  &end-date=yesterday

Enddatum

end-date=2009-05-20
Erforderlich.
Bei allen Analytics-Datenanfragen muss ein Zeitraum angegeben sein. Wenn Sie die Parameter start-date und end-date nicht in die Anfrage aufnehmen, gibt der Server einen Fehler zurück. Datumswerte können sich auf ein bestimmtes Datum beziehen, indem Sie das Muster YYYY-MM-DD verwenden, oder relativ, indem Sie today, yesterday oder das Muster NdaysAgo verwenden. Werte müssen mit [0-9]{4}-[0-9]{2}-[0-9]{2}|today|yesterday|[0-9]+(daysAgo) übereinstimmen.
Die früheste gültige end-date ist 2005-01-01. Für end-date gibt es keine Obergrenzen.
Relative Datumsangaben beziehen sich immer auf das aktuelle Datum zum Zeitpunkt der Abfrage und basieren auf der Zeitzone der Ansicht (Profil), die in der Abfrage angegeben ist.

Beispiel für einen Zeitraum der letzten 10 Tage (beginnend heute) mit relativen Datumsangaben:

  &start-date=9daysAgo
  &end-date=today

Dimensionen

dimensions=ga:browser,ga:city
Optional.
Der Parameter dimensions schlüsselt Messwerte nach gemeinsamen Kriterien auf, z. B. nach ga:browser oder ga:city. Du kannst zwar die Gesamtzahl der Seitenaufrufe deiner Website abfragen, es ist aber möglicherweise interessanter, nach der Anzahl der Seitenaufrufe aufgeschlüsselt nach Browser zu fragen. In diesem Fall sehen Sie die Anzahl der Seitenaufrufe aus Firefox, Internet Explorer, Chrome usw.

Beachten Sie die folgenden Einschränkungen, wenn Sie dimensions in einer Datenanfrage verwenden:

  • In einer Abfrage können maximal sieben Dimensionen angegeben werden.
  • Sie können keine Abfrage senden, die nur aus Dimensionen besteht: Sie müssen alle angeforderten Dimensionen mit mindestens einem Messwert kombinieren.
  • In derselben Abfrage können nur bestimmte Dimensionen abgefragt werden. Mit dem gültigen Kombinationstool aus der Referenz für Dimensionen und Messwerte können Sie feststellen, welche Dimensionen zusammen verwendet werden können.


metrics

metrics=ga:sessions,ga:bounces
Erforderlich.
Die zusammengefassten Statistiken zu Nutzeraktivitäten auf Ihrer Website, z. B. Klicks oder Seitenaufrufe. Wenn eine Abfrage keinen dimensions-Parameter hat, liefern die zurückgegebenen Messwerte zusammengefasste Werte für den angeforderten Zeitraum, z. B. Seitenaufrufe oder Absprünge insgesamt. Werden Dimensionen jedoch angefordert, werden die Werte nach Dimensionswerten segmentiert. Beispielsweise gibt die mit ga:country angeforderte ga:pageviews die Gesamtzahl der Seitenaufrufe pro Land zurück. Beachten Sie beim Anfordern von Messwerten Folgendes:
  • Jede Anfrage muss mindestens einen Messwert enthalten. Eine Anfrage darf nicht nur aus Dimensionen bestehen.
  • Sie können für jede Abfrage maximal zehn Messwerte angeben.
  • Die meisten Messwertkombinationen aus mehreren Kategorien können zusammen verwendet werden, sofern keine Dimensionen angegeben sind.
  • Messwerte können mit anderen Dimensionen oder Messwerten kombiniert werden, sofern für diesen Messwert gültige Kombinationen zutreffen. Weitere Informationen finden Sie in der Referenz zu Dimensionen und Messwerten.


sort

sort=ga:country,ga:browser
Optional.

Eine Liste mit Messwerten und Dimensionen, die die Sortierreihenfolge und -richtung für die zurückgegebenen Daten angeben.

  • Die Sortierreihenfolge wird durch die von links nach rechts aufgeführte Reihenfolge der aufgeführten Messwerte und Dimensionen angegeben.
  • Die Sortierung (direction) ist standardmäßig aufsteigend und kann in absteigender Reihenfolge geändert werden, indem Sie ein Minuszeichen (-) für das angeforderte Feld verwenden.

Wenn Sie die Ergebnisse einer Abfrage sortieren, können Sie verschiedene Fragen zu Ihren Daten stellen. Um beispielsweise auf die Frage „Was sind meine Top-Länder und welche Browser sie am häufigsten verwenden?“ zu beantworten. können Sie eine Abfrage mit dem folgenden Parameter erstellen. Es sortiert zuerst nach ga:country und dann nach ga:browser, beide in aufsteigender Reihenfolge:

sort=ga:country,ga:browser

Um die Frage „Was sind meine meistverwendeten Browser und welche Länder nutzen sie am häufigsten?“ zu beantworten, können Sie eine Abfrage mit dem folgenden Parameter erstellen. Zuerst wird nach ga:browser und dann nach ga:country in aufsteigender Reihenfolge sortiert:
sort=ga:browser,ga:country

Beachten Sie bei der Verwendung des sort-Parameters Folgendes:

  • Sortieren Sie nur nach Dimensionen oder Messwerten, die Sie in den Parametern dimensions oder metrics verwendet haben. Wenn in Ihrer Anfrage nach einem Feld sortiert wird, das weder im Dimensions- noch im Messwertparameter angegeben ist, erhalten Sie eine Fehlermeldung.
  • Standardmäßig werden Strings in aufsteigender alphabetischer Reihenfolge in der Sprache en-US sortiert.
  • Zahlen werden standardmäßig in aufsteigender numerischer Reihenfolge sortiert.
  • Datumsangaben werden standardmäßig in aufsteigender Reihenfolge nach Datum sortiert.

Filter

filters=ga:medium%3D%3Dreferral
Optional.

Der Abfragestringparameter filters schränkt die von Ihrer Anfrage zurückgegebenen Daten ein. Wenn Sie den Parameter filters verwenden möchten, geben Sie eine Dimension oder einen Messwert an, nach der bzw. dem gefiltert werden soll, gefolgt vom Filterausdruck. Mit der folgenden Abfrage werden beispielsweise ga:pageviews und ga:browser für die Ansicht (Profil) 12134 angefordert, wobei die Dimension ga:browser mit dem String Firefox beginnt:

https://www.googleapis.com/analytics/v3/data/ga
?ids=ga:12134
&dimensions=ga:browser
&metrics=ga:pageviews
&filters=ga:browser%3D~%5EFirefox
&start-date=2007-01-01
&end-date=2007-12-31

Gefilterte Abfragen schränken die Zeilen ein, die im Ergebnis enthalten sind oder nicht. Jede Zeile im Ergebnis wird anhand des Filters geprüft: Wenn der Filter übereinstimmt, wird die Zeile beibehalten. Ist dies nicht der Fall, wird die Zeile gelöscht.

  • URL-Codierung: Mit den Google API-Clientbibliotheken werden die Filteroperatoren automatisch codiert.
  • Dimensionsfilterung: Die Filterung wird vor der Zusammenfassung von Dimensionen durchgeführt. Die zurückgegebenen Messwerte stellen also nur die Gesamtsumme für die relevanten Dimensionen dar. Im obigen Beispiel würde die Anzahl der Seitenaufrufe nur die Seitenaufrufe umfassen, bei denen Firefox der Browser ist.
  • Messwertfilterung: Das Filtern von Messwerten erfolgt nach der Zusammenfassung.
  • Gültige Kombinationen: Sie können nach Dimensionen oder Messwerten filtern, die nicht Teil der Abfrage sind, sofern alle Dimensionen/Messwerte in der Anfrage und der Filter gültige Kombinationen sind. Sie können beispielsweise eine Liste mit datierten Seitenaufrufen abfragen und dabei nach einem bestimmten Browser filtern. Weitere Informationen finden Sie in der Referenz für Dimensionen und Messwerte.

Filtersyntax


Für einen einzelnen Filter wird folgendes Format verwendet:

ga:name operator expression

In dieser Syntax gilt:

  • name – Der Name der Dimension oder des Messwerts, nach der bzw. dem gefiltert werden soll. Beispiel: ga:pageviews filtert nach dem Messwert „Seitenaufrufe“.
  • operator – Hiermit wird der zu verwendende Typ der Filterübereinstimmung definiert. Operatoren sind entweder für Dimensionen oder für Messwerte spezifisch.
  • expression – gibt die Werte an, die in die Ergebnisse einbezogen oder von diesen ausgeschlossen werden sollen. Für Ausdrücke wird die Syntax regulärer Ausdrücke verwendet.

Filteroperatoren


Es gibt sechs Filteroperatoren für Dimensionen und sechs Filteroperatoren für Messwerte. Die Operatoren müssen URL-codiert sein, damit sie in URL-Abfragestrings verwendet werden können.

Tipp: Verwenden Sie den Data Feed Query Explorer, um Filter zu erstellen, für die eine URL-Codierung erforderlich ist, da der Query Explorer automatisch URLs codiert, die Strings und Leerzeichen enthalten.

Messwertfilter
Betreiber Beschreibung URL-codiertes Formular Beispiele
== Ist gleich %3D%3D Gibt Ergebnisse zurück, bei denen die Zeit auf der Seite genau zehn Sekunden beträgt:
filters=ga:timeOnPage%3D%3D10
!= Ist nicht gleich !%3D Ergebnisse zurückgeben, bei denen die Zeit auf der Seite nicht zehn Sekunden beträgt:
filters=ga:timeOnPage!%3D10
> Größer als %3E Gibt Ergebnisse zurück, bei denen die Zeit auf der Seite größer als zehn Sekunden ist:
filters=ga:timeOnPage%3E10
< Weniger als %3C Gibt Ergebnisse zurück, bei denen die Zeit auf der Seite grundsätzlich weniger als zehn Sekunden beträgt:
filters=ga:timeOnPage%3C10
>= Größer als oder gleich %3E%3D Gibt Ergebnisse zurück, bei denen die Zeit auf der Seite mindestens zehn Sekunden beträgt:
filters=ga:timeOnPage%3E%3D10
<= Kleiner als oder gleich %3C%3D Ergebnisse zurückgeben, bei denen die Zeit auf der Seite zehn Sekunden oder weniger beträgt:
filters=ga:timeOnPage%3C%3D10

Dimensionsfilter
Betreiber Beschreibung URL-codiertes Formular Beispiel
== Genaue Übereinstimmung %3D%3D Zusammengefasste Messwerte für die Stadt Irvine:
filters=ga:city%3D%3DIrvine
!= Stimmt nicht überein mit !%3D Zusammengefasste Messwerte, bei denen die Stadt nicht Irvine ist:
filters=ga:city!%3DIrvine
=@ Enthält Teilstring %3D@ Zusammengefasste Messwerte, bei denen die Stadt York enthält:
filters=ga:city%3D@York
!@ Enthält keine Teilzeichenfolge !@ Zusammengefasste Messwerte, bei denen York in der Stadt nicht enthalten ist:
filters=ga:city!@York
=~ Enthält eine Übereinstimmung mit dem regulären Ausdruck %3D~ Zusammengefasste Messwerte, bei denen die Stadt mit Neu beginnt:
filters=ga:city%3D~%5ENew.*
(%5E ist die URL, die aus dem Zeichen ^ codiert ist und ein Muster am Anfang des Strings verankert.)
!~ Keine Übereinstimmung mit regulärem Ausdruck !~ Zusammengefasste Messwerte, bei denen die Stadt nicht mit Neu beginnt:
filters=ga:city!~%5ENew.*

Filterausdrücke

Für Filterausdrücke gibt es einige wichtige Regeln:

  • Zeichen mit URL-Reservierung: Zeichen wie & müssen wie gewohnt URL-codiert werden.
  • Reservierte Zeichen: Das Semikolon und das Komma müssen mit einem umgekehrten Schrägstrich maskiert werden, wenn sie in einem Ausdruck verwendet werden:
    • Semikolon \;
    • Komma \,
  • Reguläre Ausdrücke: Sie können reguläre Ausdrücke auch mit den Operatoren =~ und !~ in Filterausdrücken verwenden. Ihre Syntax ähnelt den regulären Perl-Ausdrücken und weist folgende zusätzlichen Regeln auf:
    • Maximale Länge: 128 Zeichen: Reguläre Ausdrücke, die länger als 128 Zeichen sind, führen zu einem 400 Bad Request-Statuscode, der vom Server zurückgegeben wird.
    • Groß-/Kleinschreibung: Beim Abgleich regulärer Ausdrücke wird die Groß-/Kleinschreibung nicht berücksichtigt.

Filter kombinieren

Filter können mithilfe der booleschen Operatoren OR und AND kombiniert werden. Auf diese Weise können Sie die Beschränkung auf 128 Zeichen eines Filterausdrucks effektiv erweitern.

ODER

Der Operator OR wird durch ein Komma (,) definiert. Er hat Vorrang vor dem Operator AND und darf NICHT verwendet werden, um Dimensionen und Messwerte im selben Ausdruck zu kombinieren.

Beispiele: (jeweils URL-Codierung erforderlich)

Land ist entweder (USA ODER Kanada):
ga:country==United%20States,ga:country==Canada

Firefox-Nutzer mit Betriebssystemen (Windows ODER Macintosh):
ga:browser==Firefox;ga:operatingSystem==Windows,ga:operatingSystem==Macintosh

UND

Der Operator AND wird durch ein Semikolon (;) definiert. Ihm ist der Operator OR vorangestellt. Mit CAN können Dimensionen und Messwerte im selben Ausdruck kombiniert werden.

Beispiele: (jeweils URL-Codierung erforderlich)

Als Land sind die USA UND der Browser ist Firefox:
ga:country==United%20States;ga:browser==Firefox

Land ist USA UND die Sprache beginnt nicht mit „en“:
ga:country==United%20States;ga:language!~^en.*

Betriebssystem (Windows ODER Macintosh) UND Browser ist (Firefox ODER Chrome):
ga:operatingSystem==Windows,ga:operatingSystem==Macintosh;ga:browser==Firefox,ga:browser==Chrome

Land ist USA UND die Anzahl der Sitzungen beträgt mehr als 5:
ga:country==United%20States;ga:sessions>5



Segmentieren

segment=gaid::-10
segment=sessions::condition::ga:medium%3D%3Dreferral
segment=users::condition::ga:browser%3D%3DChrome
Optional.

Ausführliche Informationen zum Anfordern eines Segments über die Core Reporting API finden Sie im Segment-Entwicklungsleitfaden.

Eine konzeptionelle Übersicht über Segmente finden Sie in der Referenz zu Segmentfunktionen und in der Segmentfunktion in der Hilfe.

Dimensionen und Messwerte, die in Segmenten zulässig sind:
Nicht alle Dimensionen und Messwerte können in Segmenten verwendet werden. Im Dimensions and Metrics Explorer können Sie prüfen, welche Dimensionen und Messwerte in Segmenten zulässig sind.


samplingLevel

samplingLevel=DEFAULT
Optional.
Mit diesem Parameter legen Sie die Stichprobenebene (d.h. die Anzahl der Sitzungen, auf deren Grundlage das Ergebnis berechnet wird) für eine Berichtsabfrage fest. Die zulässigen Werte sind mit der Weboberfläche identisch und umfassen Folgendes:
  • DEFAULT: gibt die Antwort mit einer Stichprobengröße zurück, die ein Gleichgewicht zwischen Geschwindigkeit und Genauigkeit herstellt.
  • FASTER: gibt eine schnelle Antwort mit einer kleineren Stichprobengröße zurück.
  • HIGHER_PRECISION: Gibt mit einer großen Stichprobengröße eine genauere Antwort zurück. Dies kann jedoch dazu führen, dass die Antwort langsamer ist.
Wenn nicht angegeben, wird die Stichprobenebene von DEFAULT verwendet.
Weitere Informationen zum Berechnen des Prozentsatzes der Sitzungen, die für eine Abfrage verwendet wurden, finden Sie im Abschnitt Stichproben.

Leere-Zeilen-einschließen

include-empty-rows=true
Optional.
Die Standardeinstellung ist "true". Wenn sie auf "false" gesetzt ist, werden Zeilen, in denen alle Messwerte null sind, aus der Antwort entfernt. Wenn Sie beispielsweise mehr als einen Messwert in eine Abfrage einschließen, werden die Zeilen nur entfernt, wenn alle Messwerte null sind. Dies kann nützlich sein, wenn die Anzahl der gültigen Zeilen viel kleiner als die Anzahl der erwarteten Dimensionswerte bei einer Anfrage ist.

start-index

start-index=10
Optional.
Wenn nicht angegeben, ist der Startindex 1. (Ergebnisindexe sind 1-basiert. Die erste Zeile ist also die Zeile 1 und nicht die Zeile 0. Verwenden Sie diesen Parameter zusammen mit dem Parameter max-results als Paginierungsmechanismus, wenn totalResults den Wert 10.000 überschreitet und Sie Zeilen abrufen möchten, die einen Index ab 10.001 haben.

max-results

max-results=100
Optional.
Maximale Anzahl von Zeilen für diese Antwort. Sie können dies in Kombination mit start-index verwenden, um eine Teilmenge von Elementen abzurufen, oder es alleine verwenden, um die Anzahl der zurückgegebenen Elemente zu begrenzen, beginnend mit dem ersten. Wenn max-results nicht angegeben ist, gibt die Abfrage das standardmäßige Maximum von 1.000 Zeilen zurück.
Die Analytics Core Reporting API gibt maximal 10.000 Zeilen pro Anfrage zurück,unabhängig davon, wie viele Zeilen Sie anfordern. Möglicherweise werden auch weniger Zeilen als angefordert zurückgegeben, wenn nicht so viele Dimensionssegmente wie erwartet vorhanden sind. Für ga:country sind beispielsweise weniger als 300 Werte möglich. Wenn Sie also nur nach Land segmentieren, können Sie nicht mehr als 300 Zeilen erhalten, selbst wenn Sie für max-results einen höheren Wert festlegen.

output

output=dataTable
Optional.
Mit diesem Parameter können Sie den Ausgabetyp der in der Antwort zurückgegebenen Analytics-Daten festlegen. Folgende Werte sind zulässig:
  • json: Gibt das Standardattribut rows in der Antwort aus, das ein JSON-Objekt enthält.
  • dataTable: Gibt in der Antwort das Attribut dataTable aus, das ein Datentabellenobjekt enthält. Dieses Data Table -Objekt kann direkt mit Google Charts-Visualisierungen verwendet werden.
Wenn nicht angegeben, wird die Standard-JSON-Antwort verwendet.

Felder

fields=rows,columnHeaders(name,dataType)
Optional.

Gibt an, welche Felder in einer Teilantwort zurückgegeben werden. Wenn Sie nur einen Teil der Felder in der API-Antwort verwenden, können Sie mit dem Parameter fields angeben, welche Felder berücksichtigt werden sollen.

Das Format des Werts des Feldanfrageparameters basiert grob auf der XPath-Syntax. Die unterstützte Syntax ist unten zusammengefasst.

  • Zur Auswahl mehrerer Felder verwenden Sie eine durch Kommas getrennte Liste.
  • Verwenden Sie a/b, um das Feld b auszuwählen, das in Feld a verschachtelt ist. Verwenden Sie a/b/c, um das Feld c auszuwählen, das in Feld b verschachtelt ist.
  • Verwenden Sie ein untergeordnetes Auswahlzeichen, um eine Reihe bestimmter Unterfelder von Arrays oder Objekten anzufordern. Setzen Sie dazu Ausdrücke in Klammern: "( )".
    Beispiel: fields=columnHeaders(name,dataType) gibt nur die Felder name und dataType im Array columnHeaders zurück. Sie können auch ein einzelnes Teilfeld angeben, in dem fields=columnHeader(name) fields=columnHeader/name entspricht.

prettyPrint

prettyPrint=false
Optional.

Gibt die Antwort in einem für Menschen lesbaren Format zurück, wenn true. Standardwert: false.


quotaUser

quotaUser=4kh4r2h4
Optional.

Ermöglicht das Erzwingen von Kontingente pro Nutzer von einer serverseitigen Anwendung aus, auch wenn die IP-Adresse des Nutzers unbekannt ist. Dies kann beispielsweise bei Anwendungen der Fall sein, die Cronjobs in App Engine im Namen eines Nutzers ausführen. Sie können einen beliebigen String auswählen, der einen Nutzer eindeutig identifiziert. Er ist jedoch auf 40 Zeichen beschränkt.

Hiermit wird userIp überschrieben, wenn beide angegeben werden.


Antwort

Bei Erfolg gibt diese Anfrage einen Antworttext mit der unten definierten JSON-Struktur zurück. Wenn der Parameter output auf dataTable gesetzt ist, gibt die Anfrage einen Antworttext mit der unten definierten JSON-Struktur (Datentabelle) zurück.

Hinweis: Der Begriff "Ergebnisse" bezieht sich auf die gesamte Gruppe von Zeilen, die mit der Abfrage übereinstimmen, während "Antwort" sich auf die Reihe von Zeilen bezieht, die auf der aktuellen Ergebnisseite zurückgegeben werden. Sie können unterschiedlich sein, wenn die Gesamtzahl der Ergebnisse größer als die Seitengröße für die aktuelle Antwort ist, wie unter itemsPerPage erläutert.

JSON
{
  "kind": "analytics#gaData",
  "id": string,
  "selfLink": string,
  "containsSampledData": boolean,
  "query": {
    "start-date": string,
    "end-date": string,
    "ids": string,
    "dimensions": [
      string
    ],
    "metrics": [
      string
    ],
    "include-empty-rows": boolean
    "samplingLevel": string,
    "sort": [
      string
    ],
    "filters": string,
    "segment": string,
    "start-index": integer,
    "max-results": integer
  },
  "itemsPerPage": integer,
  "totalResults": integer,
  "previousLink": string,
  "nextLink": string,
  "profileInfo": {
    "profileId": string,
    "accountId": string,
    "webPropertyId": string,
    "internalWebPropertyId": string,
    "profileName": string,
    "tableId": string
  },
  "columnHeaders": [
    {
      "name": string,
      "columnType": string,
      "dataType": string
    }
  ],
  "rows": [
    [
      string
    ]
  ],
  "sampleSize": string,
  "sampleSpace": string,
  "totalsForAllResults": [
    {
      metricName: string,
      ...
    }
  ]
}

Antwortfelder

Die Eigenschaften der Antworttextstruktur sind wie folgt definiert:

Eigenschaftsname Wert Beschreibung
kind string Ressourcentyp. Der Wert ist „analytics#gaData“.
id string Eine ID für diese Datenantwort.
query object Dieses Objekt enthält alle Werte, die als Parameter an die Abfrage übergeben werden. Die Bedeutung der einzelnen Felder wird in der Beschreibung des entsprechenden Abfrageparameters erläutert.
query.start-date string Anfangsdatum.
query.end-date string Enddatum.
query.ids string Eindeutige Tabellen-ID.
query.dimensions[] list Liste der Analysedimensionen.
query.metrics[] list Liste der Analysemesswerte.
query.samplingLevel string Requested sampling level.
query.include-empty-rows boolean Die Standardeinstellung ist „true“. Wenn „false“ festgelegt ist, werden Zeilen, in denen alle Messwerte null sind, aus der Antwort ausgeschlossen.
query.sort[] list Liste der Messwerte oder Dimensionen, nach denen die Daten sortiert werden.
query.filters string Durch Kommas getrennte Liste von Messwert- oder Dimensionsfiltern.
query.segment string Analytics-Segment.
query.start-index integer Start index.
query.max-results integer Maximale Anzahl von Ergebnissen pro Seite.
startIndex integer Der Startindex der Zeilen, die durch den Abfrageparameter start-index angegeben werden. Der Standardwert ist 1.
itemsPerPage integer Die maximale Anzahl von Zeilen, die die Antwort enthalten kann, unabhängig von der tatsächlichen Anzahl der zurückgegebenen Zeilen. Wenn der Abfrageparameter max-results angegeben wird, ist der Wert von itemsPerPage entweder max-results oder 10.000, je nachdem, welcher Wert kleiner ist. Der Standardwert von itemsPerPage ist 1.000.
totalResults integer Die Gesamtzahl der Zeilen im Abfrageergebnis, unabhängig von der Anzahl der in der Antwort zurückgegebenen Zeilen. Bei Abfragen, die zu einer großen Anzahl von Zeilen führen, kann totalResults größer als itemsPerPage sein. Weitere Informationen zu totalResults und itemsPerPage für große Abfragen finden Sie unter Paging.
startDate string Startdatum für die Datenabfrage, wie durch den Parameter start-date angegeben.
endDate string Enddatum der Datenabfrage, wie durch den Parameter end-date angegeben.
profileInfo object Informationen zur Datenansicht (Profil), für die die Daten angefordert wurden. Datenansichts- bzw. Profildaten sind über die Google Analytics Management API verfügbar.
profileInfo.profileId string ID der Datenansicht (Profil), z. B. 1174
profileInfo.accountId string ID des Kontos, zu dem diese Datenansicht (Profil) gehört, z. B. 30481
profileInfo.webPropertyId string Die ID der Web-Property, zu der diese Datenansicht (Profil) gehört, z. B. UA-30481-1
profileInfo.internalWebPropertyId string Interne ID für die Web-Property, zu der diese Datenansicht (Profil) gehört, z. B. UA-30481-1.
profileInfo.profileName string Name der Datenansicht (Profil)
profileInfo.tableId string Tabellen-ID für Ansicht (Profil), bestehend aus „ga:“ gefolgt von der ID der Ansicht (Profil).
containsSampledData boolean „True“, wenn die Antwort Stichproben enthält.
sampleSize string Die Anzahl der Stichproben, die zur Berechnung der Stichproben verwendet werden.
sampleSpace string Die Gesamtfläche für die Stichprobenerhebung. Hier wird der gesamte verfügbare Stichprobenbereich angegeben, aus dem die Stichproben ausgewählt wurden.
columnHeaders[] list Spaltenüberschriften, in denen die Dimensionsnamen gefolgt von den Messwertnamen aufgeführt sind. Die Reihenfolge der Dimensionen und Messwerte entspricht der Reihenfolge, die in der Anfrage über die Parameter metrics und dimensions angegeben wurde. Die Anzahl der Header entspricht der Anzahl der Dimensionen + der Anzahl der Messwerte.
columnHeaders[].name string Name der Dimension oder des Messwerts.
columnHeaders[].columnType string Spaltentyp. Entweder „DIMENSION“ oder „MESSWERT“.
columnHeaders[].dataType string Datentyp. Die Spaltenüberschriften der Dimensionen haben nur den Datentyp „STRING“. Die Spaltenüberschriften der Messwerte enthalten Datentypen für Messwerte wie INTEGER, PERCENT, TIME, CURRENCY, FLOAT usw. Weitere Informationen zu allen möglichen Datentypen finden Sie in der Metadaten-API-Antwort.
totalsForAllResults object Gesamtwerte für die angeforderten Messwerte als Schlüssel/Wert-Paare aus Messwertnamen und -werten. Die Reihenfolge der Gesamtsummen der Messwerte entspricht der in der Anfrage angegebenen Reihenfolge.
rows[] list Analytics-Datenzeilen, wobei jede Zeile eine Liste von Dimensionswerten gefolgt von den Messwerten enthält. Die Reihenfolge der Dimensionen und Messwerte entspricht der in der Anfrage angegebenen Reihenfolge. Jede Zeile enthält eine Liste mit N Feldern, wobei N = die Anzahl der Dimensionen + die Anzahl der Messwerte ist.
JSON (Datentabelle)
{
  "kind": "analytics#gaData",
  "id": string,
  "selfLink": string,
  "containsSampledData": boolean,
  "query": {
    "start-date": string,
    "end-date": string,
    "ids": string,
    "dimensions": [
      string
    ],
    "metrics": [
      string
    ],
    "samplingLevel": string,
    "include-empty-rows": boolean,
    "sort": [
      string
    ],
    "filters": string,
    "segment": string,
    "start-index": integer,
    "max-results": integer
  },
  "itemsPerPage": integer,
  "totalResults": integer,
  "previousLink": string,
  "nextLink": string,
  "profileInfo": {
    "profileId": string,
    "accountId": string,
    "webPropertyId": string,
    "internalWebPropertyId": string,
    "profileName": string,
    "tableId": string
  },
  "columnHeaders": [
    {
      "name": string,
      "columnType": string,
      "dataType": string
    }
  ],
  "dataTable": {
    "cols": [
      {
        "id": string,
        "label": string,
        "type": string
      }
    ],
    "rows": [
      {
        "c": [
          {    
            "v": string
          }
        ]
      }   
    ]
  },
  "sampleSize": string,
  "sampleSpace": string,
  "totalsForAllResults": [
    {
      metricName: string,
      ...
    }
  ]
}

Antwortfelder

Die Eigenschaften der Antworttextstruktur sind wie folgt definiert:

Eigenschaftsname Wert Beschreibung
kind string Ressourcentyp. Der Wert ist „analytics#gaData“.
id string Eine ID für diese Datenantwort.
query object Dieses Objekt enthält alle Werte, die als Parameter an die Abfrage übergeben werden. Die Bedeutung der einzelnen Felder wird in der Beschreibung des entsprechenden Abfrageparameters erläutert.
query.start-date string Anfangsdatum.
query.end-date string Enddatum.
query.ids string Eindeutige Tabellen-ID.
query.dimensions[] list Liste der Analysedimensionen.
query.metrics[] list Liste der Analysemesswerte.
query.samplingLevel string Requested sampling level.
query.include-empty-rows boolean Die Standardeinstellung ist „true“. Wenn „false“ festgelegt ist, werden Zeilen, in denen alle Messwerte null sind, aus der Antwort ausgeschlossen.
query.sort[] list Liste der Messwerte oder Dimensionen, nach denen die Daten sortiert werden.
query.filters string Durch Kommas getrennte Liste von Messwert- oder Dimensionsfiltern.
query.segment string Analytics-Segment.
query.start-index integer Start index.
query.max-results integer Maximale Anzahl von Ergebnissen pro Seite.
startIndex integer Der Startindex der Zeilen, die durch den Abfrageparameter start-index angegeben werden. Der Standardwert ist 1.
itemsPerPage integer Die maximale Anzahl von Zeilen, die die Antwort enthalten kann, unabhängig von der tatsächlichen Anzahl der zurückgegebenen Zeilen. Wenn der Abfrageparameter max-results angegeben wird, ist der Wert von itemsPerPage entweder max-results oder 10.000, je nachdem, welcher Wert kleiner ist. Der Standardwert von itemsPerPage ist 1.000.
totalResults integer Die Gesamtzahl der Zeilen im Abfrageergebnis, unabhängig von der Anzahl der in der Antwort zurückgegebenen Zeilen. Bei Abfragen, die zu einer großen Anzahl von Zeilen führen, kann totalResults größer als itemsPerPage sein. Weitere Informationen zu totalResults und itemsPerPage für große Abfragen finden Sie unter Paging.
startDate string Startdatum für die Datenabfrage, wie durch den Parameter start-date angegeben.
endDate string Enddatum der Datenabfrage, wie durch den Parameter end-date angegeben.
profileInfo object Informationen zur Datenansicht (Profil), für die die Daten angefordert wurden. Datenansichts- bzw. Profildaten sind über die Google Analytics Management API verfügbar.
profileInfo.profileId string ID der Datenansicht (Profil), z. B. 1174
profileInfo.accountId string ID des Kontos, zu dem diese Datenansicht (Profil) gehört, z. B. 30481
profileInfo.webPropertyId string Die ID der Web-Property, zu der diese Datenansicht (Profil) gehört, z. B. UA-30481-1
profileInfo.internalWebPropertyId string Interne ID für die Web-Property, zu der diese Datenansicht (Profil) gehört, z. B. UA-30481-1.
profileInfo.profileName string Name der Datenansicht (Profil)
profileInfo.tableId string Tabellen-ID für Ansicht (Profil), bestehend aus „ga:“ gefolgt von der ID der Ansicht (Profil).
containsSampledData boolean „True“, wenn die Antwort Stichproben enthält.
sampleSize string Die Anzahl der Stichproben, die zur Berechnung der Stichproben verwendet werden.
sampleSpace string Die Gesamtfläche für die Stichprobenerhebung. Hier wird der gesamte verfügbare Stichprobenbereich angegeben, aus dem die Stichproben ausgewählt wurden.
columnHeaders[] list Spaltenüberschriften, in denen die Dimensionsnamen gefolgt von den Messwertnamen aufgeführt sind. Die Reihenfolge der Dimensionen und Messwerte entspricht der Reihenfolge, die in der Anfrage über die Parameter metrics und dimensions angegeben wurde. Die Anzahl der Header entspricht der Anzahl der Dimensionen + der Anzahl der Messwerte.
columnHeaders[].name string Name der Dimension oder des Messwerts.
columnHeaders[].columnType string Spaltentyp. Entweder „DIMENSION“ oder „MESSWERT“.
columnHeaders[].dataType string Datentyp. Die Spaltenüberschriften der Dimensionen haben nur den Datentyp „STRING“. Die Spaltenüberschriften der Messwerte enthalten Datentypen für Messwerte wie INTEGER, PERCENT, TIME, CURRENCY, FLOAT usw. Weitere Informationen zu allen möglichen Datentypen finden Sie in der Metadaten-API-Antwort.
totalsForAllResults object Gesamtwerte für die angeforderten Messwerte als Schlüssel/Wert-Paare aus Messwertnamen und -werten. Die Reihenfolge der Gesamtsummen der Messwerte entspricht der in der Anfrage angegebenen Reihenfolge.
dataTable object Ein Datentabellenobjekt, das mit Google Charts verwendet werden kann.
dataTable.cols[] list Eine Liste von Spaltendeskriptoren für Dimensionen, gefolgt von Messwerten. Die Reihenfolge der Dimensionen und Messwerte entspricht der Reihenfolge, die in der Anfrage über die Parameter metrics und dimensions angegeben wurde. Die Anzahl der Spalten entspricht der Anzahl der Dimensionen + der Anzahl der Messwerte.
dataTable.cols[].id string Eine ID, mit der auf eine bestimmte Spalte verwiesen werden kann (als Alternative zur Verwendung von Spaltenindexen). Die Dimensions- oder Messwert-ID wird verwendet, um diesen Wert festzulegen.
dataTable.cols[].label string Eine Beschriftung für die Spalte, die in einer Visualisierung angezeigt werden kann. Die Dimensions- oder Messwert-ID wird verwendet, um diesen Wert festzulegen.
dataTable.cols[].type string Der Datentyp für diese Spalte.
dataTable.rows[] list Analytics-Datenzeilen im Datentabellenformat, wobei jede Zeile ein Objekt ist, das eine Liste von Zellenwerten für Dimensionen enthält, gefolgt von Messwerten. Die Reihenfolge der Dimensionen und Messwerte entspricht der in der Anfrage angegebenen Reihenfolge. Jede Zelle enthält eine Liste mit N Feldern, wobei N = die Anzahl der Dimensionen + die Anzahl der Messwerte ist.

Fehlercodes

Die Core Reporting API gibt bei einer erfolgreichen Anfrage den HTTP-Statuscode 200 zurück. Wenn während der Verarbeitung einer Abfrage ein Fehler auftritt, gibt die API einen Fehlercode und eine Beschreibung zurück. Jede Anwendung, die die Analyse-API verwendet, muss eine ordnungsgemäße Fehlerbehandlungslogik implementieren. Ausführliche Informationen zu den Fehlercodes und deren Behebung finden Sie im Referenzhandbuch zu Fehlerantworten.

Testen!

Sie können Abfragen an die Core Reporting API testen.

  • Geben Sie Beispielwerte für die Parameter im Abfrage-Explorer ein, um die gültigen Kombinationen aus Messwerten und Dimensionen in einer Abfrage zu sehen. Die Ergebnisse der Beispielabfrage werden als Tabelle mit Werten für alle angegebenen Messwerte und Dimensionen dargestellt.

  • Wenn Sie eine Anfrage für Live-Daten stellen und die Antwort im JSON-Format sehen möchten, verwenden Sie die Methode analytics.data.ga.get im Google Data APIs Explorer.

Probenahme

In Google Analytics werden bestimmte Kombinationen von Dimensionen und Messwerten im laufenden Betrieb berechnet. Damit die Daten innerhalb eines angemessenen Zeitraums zurückgegeben werden können, wird in Google Analytics möglicherweise nur eine Stichprobe der Daten verarbeitet.

Sie können die Stichprobenebene für eine Anfrage angeben, indem Sie den Parameter samplingLevel festlegen.

Wenn eine Antwort der Core Reporting API Stichprobendaten enthält, hat das Antwortfeld containsSampledData den Wert true. Außerdem liefern zwei Attribute Informationen zur Stichprobenebene für die Abfrage: sampleSize und sampleSpace. Mit diesen beiden Werten können Sie den Prozentsatz der Sitzungen berechnen, die für die Abfrage verwendet wurden. Beispiel: Wenn für sampleSize der Wert 201,000 gilt und für sampleSpace der Wert 220,000, dann basiert der Bericht auf (201.000 ÷ 220.000) × 100 = 91,36% der Sitzungen.

Eine allgemeine Beschreibung der Stichprobenerhebung und ihrer Verwendung in Google Analytics finden Sie unter Stichprobenerhebung.


Umgang mit großen Datenergebnissen

Wenn Sie davon ausgehen, dass Ihre Abfrage eine große Ergebnismenge zurückgibt, verwenden Sie die folgenden Richtlinien, um Ihre API-Abfrage zu optimieren, Fehler zu vermeiden und die Kontingentüberschreitung zu minimieren. Hinweis: Wir legen eine Basisleistung fest, indem wir in einer API-Anfrage maximal 7 Dimensionen und 10 Messwerte zulassen. Obwohl die Verarbeitung mancher Abfragen, die eine große Anzahl von Messwerten und Dimensionen angeben, länger dauern kann als andere, reicht es unter Umständen nicht aus, die Anzahl der angeforderten Messwerte zu begrenzen, um die Abfrageleistung zu verbessern. Mit den folgenden Methoden erzielen Sie stattdessen die besten Ergebnisse.

Dimensionen pro Abfrage reduzieren

Mit der API können in einer Anfrage bis zu sieben Dimensionen angegeben werden. Häufig muss Google Analytics die Ergebnisse dieser komplexen Abfragen ohne Vorbereitung berechnen. Dies kann besonders zeitaufwendig sein, wenn die Anzahl der resultierenden Zeilen hoch ist. Beispielsweise kann die Abfrage von Keywords nach Stadt zu Stunde mit Millionen von Datenzeilen übereinstimmen. Sie können die Leistung verbessern, indem Sie die Anzahl der Zeilen reduzieren, die in Google Analytics verarbeitet werden müssen, indem Sie die Anzahl der Dimensionen in der Abfrage begrenzen.

Abfrage nach Datumsbereich aufteilen

Anstatt durch die datumsgebundenen Ergebnisse eines langen Zeitraums zu blättern, empfiehlt es sich, separate Abfragen für jeweils eine Woche oder sogar einen Tag zu erstellen. Bei einem großen Dataset kann selbst eine Anfrage für die Daten eines einzelnen Tages mehr als max-results zurückgeben. In diesem Fall können Seitenumbrüche nicht vermieden werden. Wenn jedoch die Anzahl der übereinstimmenden Zeilen für Ihre Abfrage größer als max-results ist, kann die Unterteilung des Zeitraums die Gesamtzeit für das Abrufen der Ergebnisse verkürzen. Dieser Ansatz kann die Leistung sowohl bei Einzelthread- als auch bei parallelen Abfragen verbessern.

Paging

Das Durchblättern von Ergebnissen kann eine nützliche Möglichkeit sein, große Ergebnismengen in überschaubare Blöcke aufzuteilen. Das Feld totalResults gibt an, wie viele übereinstimmende Zeilen vorhanden sind, und itemsPerPage gibt die maximale Anzahl von Zeilen an, die im Ergebnis zurückgegeben werden können. Wenn ein hohes Verhältnis von totalResults zu itemsPerPage vorliegt, dauern die einzelnen Abfragen möglicherweise länger als nötig. Wenn Sie nur eine begrenzte Anzahl von Zeilen benötigen, z. B. zu Anzeigezwecken, bietet es sich an, über den Parameter max-results eine explizite Beschränkung für die Antwortgröße festzulegen. Wenn Ihre Anwendung jedoch eine große Anzahl von Ergebnissen vollständig verarbeiten muss, ist es möglicherweise effizienter, die maximal zulässige Anzahl von Zeilen anzufordern.

gzip verwenden

Eine einfache und bequeme Möglichkeit, die für jede Anfrage benötigte Bandbreite zu reduzieren, ist die Aktivierung der gzip-Komprimierung. Obwohl die Dekomprimierung der Ergebnisse zusätzliche CPU-Zeit in Anspruch nimmt, lohnt sich dies in der Regel aufgrund des Kompromisses bei den Netzwerkkosten. Du musst zwei Schritte ausführen, um eine mit gzip codierte Antwort zu erhalten: Lege einen Accept-Encoding-Header fest und ändere den User-Agent so, dass er den String gzip enthält. Hier ein Beispiel für HTTP-Header im korrekten Format zur Aktivierung der gzip-Komprimierung:

Accept-Encoding: gzip
User-Agent: my program (gzip)