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:
|
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
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
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.
start-date
ist 2005-01-01
.
Es gibt keine Obergrenze für das Startdatum.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
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.
end-date
ist 2005-01-01
. Es gibt keine Obergrenze für den end-date
. 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
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
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
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
odermetrics
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
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.
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 |
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
\,
- Semikolon
- 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.
- Maximale Länge: 128 Zeichen: Für reguläre Ausdrücke, die länger als 128 Zeichen sind, wird der Statuscode
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
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
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.
DEFAULT
verwendet.leere-Zeilen-einschließen
include-empty-rows=true
start-index
start-index=10
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
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.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
json
: Gibt die Standardeigenschaftrows
in der Antwort aus, die ein JSON-Objekt enthält.dataTable
: Gibt in der Antwort das AttributdataTable
aus, das ein Datentabellenobjekt enthält. DiesesData Table
-Objekt kann direkt mit Google Charts-Visualisierungen verwendet werden.
Felder
fields=rows,columnHeaders(name,dataType)
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. Verwendea/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 Feldername
unddataType
im ArraycolumnHeaders
zurück. Du kannst auch ein einzelnes Teilfeld angeben, in demfields=columnHeader(name)
fields=columnHeader/name
entspricht.
prettyPrint
prettyPrint=false
Gibt die Antwort in einem visuell lesbaren Format zurück, wenn true
.
Standardwert: false
.
quotaUser
quotaUser=4kh4r2h4
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.
{
"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. |
selfLink |
string |
Link zu dieser Seite mit Ergebnissen für diese Datenabfrage. |
previousLink |
string |
Link zur vorherigen Ergebnisseite für diese Datenabfrage. |
nextLink |
string |
Link zur nächsten Seite mit Ergebnissen für diese Datenabfrage. |
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. |
{
"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. |
selfLink |
string |
Link zu dieser Seite mit Ergebnissen für diese Datenabfrage. |
previousLink |
string |
Link zur vorherigen Ergebnisseite für diese Datenabfrage. |
nextLink |
string |
Link zur nächsten Seite mit Ergebnissen für diese Datenabfrage. |
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)