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.

Einleitung

Sie fragen die Core Reporting API für Google Analytics-Berichtsdaten ab. Für jede Abfrage sind eine Datenansichts- bzw. Profil-ID, ein Start- und Enddatum sowie mindestens ein Messwert erforderlich. Sie können auch zusätzliche Suchparameter wie Dimensionen, Filter und Segmente angeben, um Ihre Abfrage zu verfeinern. In der Übersicht erfährst du, wie all diese Konzepte zusammenhängen.

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 Abfrageparameter

In der folgenden Tabelle sind alle Abfrageparameter zusammengefasst, die von der Core Reporting API akzeptiert werden. Klicken Sie auf die einzelnen Parameternamen, um eine ausführliche Beschreibung aufzurufen.

Name Wert Erforderlich Zusammenfassung
ids string ja Die eindeutige Tabellen-ID im Format ga:XXXX, wobei XXXX die ID der Analytics-Datenansicht (Profils) ist, für die mit der Abfrage die Daten 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 als 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 Segmentiert die für Ihre Anfrage zurückgegebenen Daten.
samplingLevel string nein Gewünschte Stichprobenerhebung. 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 bei 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 Sie „false“ festlegen, werden Zeilen aus der Antwort ausgelassen, in denen alle Messwerte null sind.
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 Analytics-Daten, die in der Antwort zurückgegeben werden. 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 begrenzen.
quotaUser string nein Alternative zur userIp, wenn 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 anzugeben, dass die Anwendung das Kontingent erhält. Beispiel: key=AldefliuhSFADSfasdfasdfASdf.

Details zu Abfrageparametern

ids

ids=ga:12345
Erforderlich.
Die eindeutige ID, mit der die Analytics-Daten abgerufen werden. 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 werden. Wenn Sie die Parameter start-date und end-date nicht in die Anfrage aufnehmen, gibt der Server einen Fehler zurück. Datumswerte können für ein bestimmtes Datum mit dem Muster YYYY-MM-DD oder relativ nach today, yesterday oder dem Muster NdaysAgo gelten. Die 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. Es gibt keine Obergrenze für das Startdatum.
Relative Datumsangaben beziehen sich immer auf das aktuelle Datum zum Zeitpunkt der Abfrage und basieren auf der Zeitzone der in der Abfrage angegebenen Ansicht (Profil).

Beispiel für einen Zeitraum für die letzten 7 Tage (beginnend gestern) mit relativen Daten:

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

Enddatum

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

Beispiel für einen Zeitraum für die letzten 10 Tage (ab heute) mit relativen Daten:

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

Dimensionen

dimensions=ga:browser,ga:city
Optional.
Mit dem Parameter dimensions werden Messwerte nach gemeinsamen Kriterien aufgeschlüsselt, z. B. nach ga:browser oder ga:city. Sie können zwar die Gesamtzahl der Seitenaufrufe Ihrer Website abfragen, es ist jedoch möglicherweise interessanter, die Anzahl der Seitenaufrufe aufgeschlüsselt nach Browser zu fragen. In diesem Fall wird die Anzahl der Seitenaufrufe von Firefox, Internet Explorer, Chrome usw. angezeigt.

Wenn Sie dimensions in einer Datenanfrage verwenden, beachten Sie die folgenden Einschränkungen:

  • 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 einer Abfrage können nur bestimmte Dimensionen abgefragt werden. Mit dem gültigen Kombinationstool in 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 enthält, 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. Beispiel: Die mit ga:country angeforderte ga:pageviews gibt die Gesamtzahl der Seitenaufrufe pro Land zurück. Beachten Sie beim Anfordern von Messwerten Folgendes:
  • Jede Anfrage muss mindestens einen Messwert enthalten. Eine Anfrage kann nicht nur aus Dimensionen bestehen.
  • Sie können für jede Abfrage maximal zehn Messwerte angeben.
  • Die meisten Kombinationen von Messwerten aus mehreren Kategorien können zusammen verwendet werden, sofern keine Dimensionen angegeben sind.
  • Ein Messwert kann mit anderen Dimensionen oder Messwerten kombiniert werden, sofern für diesen Messwert gültige Kombinationen zutreffen. Weitere Informationen finden Sie in der Referenz für Dimensionen und Messwerte.

sort

sort=ga:country,ga:browser
Optional.

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

  • Die Sortierreihenfolge wird durch die von links nach rechts angegebene Reihenfolge der aufgeführten Messwerte und Dimensionen festgelegt.
  • Die Sortierung nach direction erfolgt standardmäßig in aufsteigender Reihenfolge und kann mithilfe eines Minuszeichens (-) im angeforderten Feld in absteigend geändert werden.

Durch das Sortieren der Ergebnisse einer Abfrage 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

Zur Beantwortung der Frage „Was sind meine beliebtesten Browser und in welchen Ländern sie am häufigsten?“ können Sie eine Abfrage mit dem folgenden Parameter erstellen. Es wird zuerst 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 für die Sprache en-US sortiert.
  • Zahlen werden standardmäßig in aufsteigender numerischer Reihenfolge sortiert.
  • Daten werden standardmäßig in aufsteigender Reihenfolge nach Datum sortiert.

Filter

filters=ga:medium%3D%3Dreferral
  1. Filtersyntax
  2. Filteroperatoren
  3. Filterausdrücke
  4. Filter kombinieren
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

Mit gefilterten Abfragen werden die Zeilen eingeschränkt, die im Ergebnis enthalten sind oder nicht. Jede Zeile im Ergebnis wird anhand des Filters getestet: Wenn der Filter übereinstimmt, wird die Zeile beibehalten, und falls sie nicht übereinstimmt, 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: Messwerte werden gefiltert, nachdem die Messwerte zusammengefasst wurden.
  • Gültige Kombinationen: Sie können nach Dimensionen oder Messwerten filtern, die nicht in der Abfrage enthalten sind, sofern alle Dimensionen/Messwerte in der Anfrage und der Filter gültige Kombinationen sind. Sie können beispielsweise eine Liste von Seitenaufrufen mit Datum abfragen und nach einem bestimmten Browser filtern. Weitere Informationen finden Sie in der Referenz für Dimensionen und Messwerte.

Filtersyntax


Für einen einzelnen Filter wird das folgende Format verwendet:

ga:name operator expression

In dieser Syntax:

  • name – Der Name der Dimension oder des Messwerts, nach 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 aus den Ergebnissen 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 eingefügt werden können.

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

Messwertfilter
Operator Beschreibung URL-codiertes Format Beispiele
== Ist gleich %3D%3D Ergebnisse zurückgeben, 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 grundsätzlich mehr als zehn Sekunden beträgt:
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 Ergebnisse zurückgeben, 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 maximal zehn Sekunden beträgt:
filters=ga:timeOnPage%3C%3D10

Dimensionsfilter
Operator Beschreibung URL-codiertes Format Beispiel
== Genaue Übereinstimmung %3D%3D Zusammengefasste Messwerte mit der 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 aus dem Zeichen ^ codierte URL, die 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

Es gibt einige wichtige Regeln für Filterausdrücke:

  • Zeichen mit URL-Reservierung: Zeichen wie & müssen wie gewohnt URL-codiert werden.
  • Reservierte Zeichen: Das Semikolon und das Komma müssen mit Escape-Zeichen versehen sein, 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 umfasst diese zusätzlichen Regeln:
    • Maximale Länge: 128 Zeichen: Für reguläre Ausdrücke, die länger als 128 Zeichen sind, wird der Statuscode 400 Bad Request vom Server zurückgegeben.
    • Groß-/Kleinschreibung: Beim Abgleich regulärer Ausdrücke wird die Groß-/Kleinschreibung nicht berücksichtigt.

Filter kombinieren

Filter können mit der booleschen Logik OR und AND kombiniert werden. Auf diese Weise können Sie die Beschränkung von 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-codiert)

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

Firefox-Nutzer mit Windows- ODER Macintosh-Betriebssystemen:
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-codiert)

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

Land ist USA UND 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 Sitzungen sind größer 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 dazu, wie Sie ein Segment über die Core Reporting API anfordern, finden Sie im Entwicklungsleitfaden für Segmente.

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

Dimensionen und Messwerte, die in Segmenten zulässig sind.
Nicht alle Dimensionen und Messwerte können in Segmenten verwendet werden. Welche Dimensionen und Messwerte in Segmenten zulässig sind, sehen Sie im Dimensions and Metrics Explorer.

samplingLevel

samplingLevel=DEFAULT
Optional.
Mit diesem Parameter legen Sie die Stichprobenerhebung für eine Berichtsabfrage fest, also die Anzahl der Sitzungen, auf deren Grundlage das Ergebnis berechnet wird. Die zulässigen Werte sind mit der Weboberfläche konsistent 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 bei 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 aus der Antwort ausgelassen, in denen alle Messwerte null sind. Wenn Sie beispielsweise mehr als einen Messwert in eine Abfrage aufnehmen, werden die Zeilen nur entfernt, wenn alle Messwerte null sind. Das kann nützlich sein, wenn bei einer Anfrage erwartet wird, dass die Anzahl der gültigen Zeilen viel kleiner ist als die Anzahl der erwarteten Dimensionswerte.

start-index

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

max-results

max-results=100
Optional.
Maximale Anzahl von Zeilen, die in dieser Antwort enthalten sein können. Sie können dieses Element zusammen mit start-index verwenden, um eine Teilmenge von Elementen abzurufen, oder es allein verwenden, um die Anzahl der zurückgegebenen Elemente zu beschränken, beginnend mit dem ersten. Wenn max-results nicht angegeben wird, gibt die Abfrage standardmäßig das 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 angefordert werden. Es können auch weniger Zeilen als angefordert zurückgegeben werden, wenn nicht so viele Dimensionssegmente wie erwartet vorhanden sind. Wenn für ga:country beispielsweise weniger als 300 Werte möglich sind, können Sie bei einer reinen Segmentierung nach Land nicht mehr als 300 Zeilen erhalten, auch wenn Sie für max-results einen höheren Wert festlegen.

output

output=dataTable
Optional.
Mit diesem Parameter können Sie den Ausgabetyp der Analytics-Daten festlegen, die in der Antwort zurückgegeben werden. Folgende Werte sind zulässig:
  • json: Gibt die Standardeigenschaft rows in der Antwort aus, die 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 sollen. Wenn Sie nur einen Teil der Felder in der API-Antwort verwenden, können Sie mit dem Parameter fields angeben, welche Felder enthalten sein sollen.

Das Format des Parameterwerts für die Feldanfrage ist grob an die XPath-Syntax angelehnt. Die unterstützte Syntax ist unten zusammengefasst.

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

prettyPrint

prettyPrint=false
Optional.

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

quotaUser

quotaUser=4kh4r2h4
Optional.

Damit können Sie von einer serverseitigen Anwendung Kontingente pro Nutzer erzwingen, 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 sind.

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 der Abfrage entsprechen, während "Antwort" sich auf die Gruppe von Zeilen bezieht, die auf der aktuellen Ergebnisseite zurückgegeben werden. Sie können sich unterscheiden, 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 Analytics-Dimensionen.
query.metrics[] list Liste der Analysemesswerte.
query.samplingLevel string Requested sampling level.
query.include-empty-rows boolean Der Standardwert ist „true“. Wenn dieser Wert auf „false“ gesetzt ist, werden Zeilen aus der Antwort ausgelassen, in denen alle Messwerte null sind.
query.sort[] list Liste der Messwerte oder Dimensionen, nach denen die Daten sortiert sind.
query.filters string Durch Kommas getrennte Liste von Messwert- oder Dimensionsfiltern.
query.segment string Analytics-Segment.
query.start-index integer Index starten.
query.max-results integer Maximale Anzahl von Ergebnissen pro Seite.
startIndex integer Der Startindex der durch den Abfrageparameter start-index angegebenen Zeilen. 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 der kleinere Wert max-results oder 10.000. 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 im Parameter start-date angegeben.
endDate string Enddatum für die Datenabfrage, wie im Parameter end-date angegeben.
profileInfo object Informationen zur Datenansicht (Profil), für die die Daten angefordert wurden. Datenansichtsdaten (Profil) 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 die Ansicht (Profil), bestehend aus „ga:“ gefolgt von der ID der Ansicht (Profil).
containsSampledData boolean „True“, wenn die Antwort Stichprobendaten enthält.
sampleSize string Die Anzahl der Stichproben, die zur Berechnung der Stichprobendaten verwendet werden.
sampleSpace string Der gesamte Stichprobenbereich. Gibt die Gesamtgröße der verfügbaren Stichprobenflächen an, aus denen die Stichproben ausgewählt wurden.
columnHeaders[] list Spaltenüberschriften, in denen die Namen der Dimensionen 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 Überschriften 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 Der 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. Eine Liste aller 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 der Messwerte.
rows[] list Analytics-Datenzeilen, bei denen jede Zeile eine Liste von Dimensionswerten gefolgt von den Messwerten enthält. Die Reihenfolge der Dimensionen und Messwerte entspricht der Reihenfolge in der Anfrage. 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 Analytics-Dimensionen.
query.metrics[] list Liste der Analysemesswerte.
query.samplingLevel string Requested sampling level.
query.include-empty-rows boolean Der Standardwert ist „true“. Wenn dieser Wert auf „false“ gesetzt ist, werden Zeilen aus der Antwort ausgelassen, in denen alle Messwerte null sind.
query.sort[] list Liste der Messwerte oder Dimensionen, nach denen die Daten sortiert sind.
query.filters string Durch Kommas getrennte Liste von Messwert- oder Dimensionsfiltern.
query.segment string Analytics-Segment.
query.start-index integer Index starten.
query.max-results integer Maximale Anzahl von Ergebnissen pro Seite.
startIndex integer Der Startindex der durch den Abfrageparameter start-index angegebenen Zeilen. 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 der kleinere Wert max-results oder 10.000. 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 im Parameter start-date angegeben.
endDate string Enddatum für die Datenabfrage, wie im Parameter end-date angegeben.
profileInfo object Informationen zur Datenansicht (Profil), für die die Daten angefordert wurden. Datenansichtsdaten (Profil) 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 die Ansicht (Profil), bestehend aus „ga:“ gefolgt von der ID der Ansicht (Profil).
containsSampledData boolean „True“, wenn die Antwort Stichprobendaten enthält.
sampleSize string Die Anzahl der Stichproben, die zur Berechnung der Stichprobendaten verwendet werden.
sampleSpace string Der gesamte Stichprobenbereich. Gibt die Gesamtgröße der verfügbaren Stichprobenflächen an, aus denen die Stichproben ausgewählt wurden.
columnHeaders[] list Spaltenüberschriften, in denen die Namen der Dimensionen 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 Überschriften 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 Der 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. Eine Liste aller 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 der Messwerte.
dataTable object Ein Datentabellenobjekt, das mit Google Charts verwendet werden kann.
dataTable.cols[] list Eine Liste von Spaltenbeschreibungen 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 Analysedatenzeilen im Datentabellenformat, wobei jede Zeile ein Objekt ist, das eine Liste von Zellenwerten für Dimensionen gefolgt von Messwerten enthält. Die Reihenfolge der Dimensionen und Messwerte entspricht der Reihenfolge in der Anfrage. 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 für die Core Reporting API testen.

  • Geben Sie im Abfrage-Explorer Beispielwerte für die Parameter ein, um gültige 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 zu 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 direkt 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 Stichproben enthält, enthält das Antwortfeld containsSampledData den Wert true. Darüber hinaus 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 sampleSize den Wert 201,000 hat und sampleSpace den Wert 220,000 hat, 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 Stichproben.


Verarbeitung umfangreicher Datenergebnisse

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 Kontingentüberschreitungen zu minimieren. Für eine Baseline für die Leistung sind maximal 7 Dimensionen und 10 Messwerte pro API-Anfrage zulässig. Obwohl einige Abfragen, die eine große Anzahl von Messwerten und Dimensionen angeben, länger dauern als andere, reicht die Begrenzung der Anzahl der angeforderten Messwerte unter Umständen nicht aus, um die Abfrageleistung zu verbessern. Mit den folgenden Verfahren erzielen Sie die besten Ergebnisse.

Dimensionen pro Abfrage reduzieren

Mit der API können in einer Anfrage bis zu sieben Dimensionen angegeben werden. In vielen Fällen muss Google Analytics die Ergebnisse dieser komplexen Suchanfragen direkt berechnen. Dies kann besonders zeitaufwändig sein, wenn die Anzahl der resultierenden Zeilen hoch ist. Beispielsweise können bei der Abfrage von Keywords nach Stadt zu Stunde Millionen von Datenzeilen zurückgegeben werden. Sie können die Leistung verbessern, indem Sie die Anzahl der Zeilen reduzieren, die Google Analytics verarbeiten muss. Dazu begrenzen Sie einfach die Anzahl der Dimensionen in der Abfrage.

Abfrage nach Datumsbereich aufteilen

Anstatt durch die Ergebnisse eines langen Zeitraums datumsgebunden zu blättern, können Sie separate Abfragen für jeweils eine Woche oder sogar einen Tag erstellen. Bei einem großen Datensatz kann selbst eine Anfrage nach den 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 höher als max-results ist, kann die Aufteilung des Zeitraums die Gesamtzeit zum Abrufen der Ergebnisse verkürzen. Dieser Ansatz kann die Leistung sowohl bei Single-Threaded- als auch bei parallelen Abfragen verbessern.

Paging

Das Durchblättern von Ergebnissen kann hilfreich sein, um 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, können die einzelnen Abfragen länger als nötig dauern. 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 Größe der Antwort festzulegen. Wenn Ihre Anwendung jedoch eine große Menge von Ergebnissen vollständig verarbeiten muss, ist das Anfordern der maximal zulässigen Zeilen möglicherweise effizienter.

gzip verwenden

Eine einfache und bequeme Möglichkeit, die für jede Anfrage benötigte Bandbreite zu reduzieren, ist die Aktivierung der gzip-Komprimierung. Auch wenn die Dekomprimierung der Ergebnisse zusätzliche CPU-Zeit in Anspruch nimmt, lohnt sich dies aufgrund der geringeren Netzwerkkosten in der Regel sehr. 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 korrekt formatierte HTTP-Header zum Aktivieren der gzip-Komprimierung:

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