Dies ist ein Entwicklerleitfaden für die Analytics Reporting API Version 4. Eine ausführliche Referenz zur API finden Sie in der API-Referenz.
Berichte
Die Analytics Reporting API Version 4 bietet die Methode batchGet, um auf die Ressource Reports (Berichte) zuzugreifen.
In den folgenden Abschnitten wird die Struktur des Anfragetexts für batchGet
und die Struktur des Antworttexts von batchGet
beschrieben.
Anfragetext
Wenn Sie die Analytics Reporting API Version 4 zum Anfordern von Daten verwenden möchten, müssen Sie ein ReportRequest-Objekt erstellen, das die folgenden Mindestanforderungen erfüllt:
- Eine gültige Ansichts-ID für das Feld viewId.
- Mindestens ein gültiger Eintrag im Feld dateRanges.
- Mindestens ein gültiger Eintrag im Feld metrics
Wenn Sie eine Ansichts-ID ermitteln möchten, fragen Sie die Methode Kontozusammenfassungen ab oder verwenden Sie den Konto-Explorer.
Wenn kein Zeitraum angegeben ist, wird der Standardzeitraum wie folgt verwendet: {"startDate": "7daysAgo", "endDate": "yesterday"}
.
Hier ist eine Beispielanfrage mit den mindestens erforderlichen Feldern:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dateRanges": [{"startDate": "2014-11-01", "endDate": "2014-11-30"}],
"metrics": [{"expression": "ga:users"}]
}
]
}
Für die Methode batchGet
sind maximal fünf ReportRequest-Objekte zulässig. Alle Anfragen sollten denselben Wert für dateRange
, viewId
, segments
, samplingLevel
und cohortGroup
haben.
Antworttext
Der Antworttext der API-Anfrage besteht aus einem Array von Report-Objekten. Die Berichtsstruktur wird im Objekt ColumnHeader definiert, das die Dimensionen und Messwerte sowie deren Datentypen im Bericht beschreibt. Die Werte der Dimensionen und Messwerte werden im Feld data angegeben.
Hier eine Beispielantwort auf die obige Beispielanfrage:
{
"reports": [
{
"columnHeader": {
"metricHeader": {
"metricHeaderEntries": [
{
"name": "ga:users",
"type": "INTEGER"
}
]
}
},
"data": {
"isDataGolden": true,
"maximums": [
{
"values": [
"98"
]
}
],
"minimums": [
{
"values": [
"98"
]
}
],
"rowCount": 1,
"rows": [
{
"metrics": [
{
"values": [
"98"
]
}
]
}
],
"totals": [
{
"values": [
"98"
]
}
]
}
}
]
}
Messwerte
Messwerte sind quantitative Messungen. Für jede Anfrage ist mindestens ein Metric-Objekt erforderlich.
Im folgenden Beispiel wird der Messwert Sessions
für die Methode batchGet
bereitgestellt, um die Gesamtzahl der Sitzungen im angegebenen Zeitraum zu erhalten:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dateRanges": [{"startDate": "2014-11-01", "endDate": "2014-11-30"}],
"metrics": [{"expression": "ga:sessions"}]
}
]
}
Sie können den Explorer für Dimensionen und Messwerte oder die Metadata API verwenden, um die Liste der verfügbaren Dimensionen und Messwerte abzurufen.
Wird gefiltert
Wenn Sie eine batchGet
-Anfrage senden, können Sie festlegen, dass nur Messwerte zurückgegeben werden sollen, die bestimmte Kriterien erfüllen. Geben Sie zum Filtern von Messwerten im Anfragetext eine oder mehrere MetricFilterClauses an und definieren Sie in jedem MetricFilterClause
einen oder mehrere MetricFilters.
Geben Sie in jedem MetricFilter
die folgenden Werte an:
metricName
not
operator
comparisonValue
Lass {metricName}
den Messwert, {operator}
den operator
und {comparisonValue}
den comparisonValue
darstellen. Der Filter funktioniert dann so:
if {metricName} {operator} {comparisonValue}
return the metric
Wenn Sie true
für not
angeben, funktioniert der Filter so:
if {metricName} {operator} {comparisonValue}
do not return the metric
Im folgenden Beispiel gibt batchGet
nur Seitenaufrufe zurück, deren Wert größer als 2 ist:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"metrics": [
{"expression": "ga:pageviews"},
{"expression": "ga:sessions"}
],
"metricFilterClauses": [{
"filters": [{
"metricName": "ga:pageviews",
"operator": "GREATER_THAN",
"comparisonValue": "2"
}]
}]
}]
}
Ausdrücke
Ein Messwertausdruck ist ein mathematischer Ausdruck, den Sie für vorhandene Messwerte definieren. Er funktioniert wie dynamische berechnete Messwerte. Sie können einen Alias für den Messwertausdruck definieren. Beispiel:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"metrics":
[
{
"expression": "ga:goal1completions/ga:users",
"alias": "completions per user"
}
]
}
]
}
Sortierung
So sortieren Sie die Ergebnisse nach einem Messwert:
- Geben Sie den Namen oder Alias im Feld
fieldName
an. - Geben Sie die Sortierreihenfolge (
ASCENDING
oderDESCENDING
) über das FeldsortOrder
an.
Im folgenden Beispiel gibt batchGet
die Messwerte in absteigender Reihenfolge zuerst nach Sitzungen und dann nach Seitenaufrufen sortiert zurück:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"metrics":
[
{"expression": "ga:pageviews"},
{"expression": "ga:sessions"}
],
"orderBys":
[
{"fieldName": "ga:sessions", "sortOrder": "DESCENDING"},
{"fieldName": "ga:pageviews", "sortOrder": "DESCENDING"}
]
}
]
}
Abmessungen
Mit Dimensionen werden Eigenschaften von Ihren Nutzern sowie deren Sitzungen und Aktionen beschrieben.
Die Dimension „Stadt“ beschreibt beispielsweise eine Eigenschaft von Sitzungen und gibt die Stadt („Paris“ oder „New York“) an, von der die Sitzung gestartet wurde.
In einer batchGet
-Anfrage können Sie null oder mehr Dimensionsobjekte angeben. Beispiel:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dateRanges":
[
{"endDate": "2014-11-30", "startDate": "2014-11-01"}
],
"metrics":
[
{"expression": "ga:users"}
],
"dimensions":
[
{"name": "ga:city"}
]
}
]
}
Wird gefiltert
Wenn Sie eine batchGet
-Anfrage senden, können Sie festlegen, dass nur Dimensionen zurückgegeben werden sollen, die bestimmte Kriterien erfüllen. Geben Sie zum Filtern von Dimensionen im Anfragetext eine oder mehrere DimensionsFilterClauses an und definieren Sie in jedem DimensionsFilterClause
einen oder mehrere DimensionsFilters.
Geben Sie in jedem DimensionsFilters
die folgenden Werte an:
dimensionName
not
operator
expressions
caseSensitive
{dimensionName}
steht für die Dimension, {operator}
für operator
und {expressions}
für expressions
. Der Filter funktioniert dann so:
if {dimensionName} {operator} {expressions}
return the dimension
Wenn Sie true
für not
angeben, funktioniert der Filter so:
if {dimensionName} {operator} {expressions}
do not return the dimension
Im folgenden Beispiel gibt batchGet
Seitenaufrufe und Sitzungen in einem Chrome-Browser zurück:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dateRanges": [
{"endDate": "2014-11-30", "startDate": "2014-11-01"}
],
"metrics": [
{"expression": "ga:pageviews"},
{"expression": "ga:sessions"}
],
"dimensions": [{"name": "ga:browser"}, {"name": "ga:country"}],
"dimensionFilterClauses": [
{
"filters": [
{
"dimensionName": "ga:browser",
"operator": "EXACT",
"expressions": ["Chrome"]
}
]
}
]
}
]
}
Sortierung
So sortieren Sie die Ergebnisse nach einem Dimensionswert:
- Geben Sie den Namen über das Feld
fieldName
an. - Geben Sie die Sortierreihenfolge (
ASCENDING
oderDESCENDING
) über das FeldsortOrder
an.
Der folgende batchGet
gibt beispielsweise die Dimensionen nach Land und dann nach Browser sortiert zurück:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"metrics": [{"expression": "ga:sessions"}],
"dimensions": [{"name": "ga:country"},{"name": "ga:browser"}],
"orderBys": [
{"fieldName": "ga:country"},
{"fieldName": "ga:browser"}
]
}
]
}
Histogramm-Buckets
Bei Dimensionen mit ganzzahligen Werten ist es einfacher, ihre Eigenschaften zu verstehen, indem ihre Werte in Bereiche gruppiert werden. Verwenden Sie das Feld histogramBuckets
, um die Bereiche für die resultierenden Buckets zu definieren, und geben Sie HISTOGRAM_BUCKET
als Reihenfolgetyp an. Beispiel:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"metrics": [{"expression": "ga:sessions"}],
"dimensions": [
{
"name": "ga:sessionCount",
"histogramBuckets": ["1","10","100","200","400"]
}
],
"orderBys": [
{
"fieldName": "ga:sessionCount",
"orderType": "HISTOGRAM_BUCKET"
}
]
}
]
}
Mehrere Zeiträume
Mit der Google Analytics Reporting API Version 4 können Sie Daten für mehrere Zeiträume in einer einzigen Anfrage abrufen. Unabhängig davon, ob in der Anfrage ein oder zwei Zeiträume angegeben sind, werden die Daten im dateRangeValue-Objekt zurückgegeben. Beispiel:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dateRanges": [
{"startDate": "2014-11-01", "endDate": "2014-11-30"},
{"startDate": "2014-10-01", "endDate": "2014-10-30"}
],
"metrics": [
{"expression": "ga:pageviews"},
{"expression": "ga:sessions"}
],
"dimensions": [{"name": "ga:pageTitle"}]
}
]
}
Deltasortierung
Wenn Sie Messwerte in zwei Zeiträumen anfordern, können Sie die Ergebnisse nach der Differenz zwischen den Werten des Messwerts in den Zeiträumen sortieren. Beispiel:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dateRanges": [
{"startDate": "2014-11-01", "endDate": "2014-11-30"},
{"startDate": "2014-10-01", "endDate": "2014-10-30"}
],
"metrics": [
{"expression": "ga:pageviews"},
{"expression": "ga:sessions"}
],
"dimensions": [{"name": "ga:pageTitle"}],
"orderBys": [
{
"fieldName": "ga:sessions",
"orderType": "DELTA"
}
]
}
]
}
Verhalten der Datumsdimension
Wenn Sie eine Datums- oder Uhrzeitdimension anfordern, enthält das Objekt DateRangeValue nur Werte für die Tage, die in die entsprechenden Zeiträume fallen. Alle anderen Werte, die nicht in den angegebenen Zeiträumen liegen, sind 0
.
Angenommen, Sie haben eine Anfrage für die Dimension ga:date
und den Messwert ga:sessions
für zwei Zeiträume: Januar und Februar.
In der Antwort für die angeforderten Daten im Januar sind die Werte im Februar 0
. In der Antwort für die angeforderten Daten im Februar sind die Werte im Januar 0
.
Bericht für Januar
{
"dimensions": [
"20140101" # `ga:date` dimension value for January 1, 2014.
],
"metrics": [
{
"values": [ # January DateRangeValue.
"8"
]
},
{
"values": [ # February DateRangeValue.
"0"
]
}
]
},
...
Februar-Bericht
{
"dimensions": [
"20140201" # `ga:date` dimension value for February 1, 2014.
],
"metrics": [
{
"values": [ # January DateRangeValue.
"0"
]
},
{
"values": [ # February DateRangeValue.
"7"
]
}
]
},
...
Segmente
Wenn Sie eine Teilmenge Ihrer Analytics-Daten anfordern möchten, verwenden Sie Segmente. So können Sie beispielsweise Nutzer aus einem bestimmten Land oder einer bestimmten Stadt in einem Segment und Nutzer definieren, die einen bestimmten Teil Ihrer Website in einem anderen Segment besuchen. Filter geben nur Zeilen zurück, die eine Bedingung erfüllen, während Segmente Teilmengen von Nutzern, Sitzungen oder Ereignissen zurückgeben, die die Bedingungen mit den Segmenten erfüllen.
Achten Sie bei einer Anfrage mit Segmenten auf Folgendes:
- Jede ReportRequest innerhalb einer
batchGet
-Methode muss identische Segmentdefinitionen enthalten. - Sie fügen
ga:segment
zur Liste der Dimensionen hinzu.
Beispiel:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "XXXX",
"dimensions": [{"name": "ga:segment"}, {"name": "ga:browser"}],
"metrics": [{"expression": "ga:sessions"}],
"segments": [
{
"dynamicSegment":
{
"name": "Sessions with Safari browser",
"userSegment":
{
"segmentFilters": [
{
"simpleSegment":
{
"orFiltersForSegment": [
{
"segmentFilterClauses": [
{
"dimensionFilter":
{
"dimensionName": "ga:browser",
"operator": "EXACT",
"expressions": ["Safari"]
}
}]
}]
}
}]
}
}
}]
}]
}
Weitere Beispielanfragen mit Segmenten finden Sie unter Beispiele.
Segment-ID
Über das Feld segmentId
können Sie Segmente anfordern.
Sie können nicht gleichzeitig segmentId
und dynamicSegment
verwenden, um Segmente anzufordern.
Beispiel:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dimensions": [{"name": "ga:medium"}, {"name": "ga:segment"}],
"metrics": [{"expression": "ga:users"}],
"segments": [{"segmentId": "gaid::-3"}]
}
]
}
Probenahme
Eine Stichprobenerhebung kann sich auf die Ergebnisse Ihrer Daten auswirken und ist ein häufiger Grund dafür, dass die von der API zurückgegebenen Werte nicht mit der Weboberfläche übereinstimmen. Legen Sie über das Feld samplingLevel
die gewünschte Stichprobengröße fest.
- Legen Sie den Wert auf
SMALL
fest, um eine schnelle Antwort mit einer kleineren Stichprobengröße zu erhalten. - Legen Sie den Wert auf
LARGE
fest, um eine genauere, aber langsamere Antwort zu erhalten. - Legen Sie den Wert auf
DEFAULT
fest, um eine Antwort zu erhalten, bei der Geschwindigkeit und Genauigkeit ausgewogen sind.
Beispiel:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dimensions": [{"name": "ga:medium"}],
"metrics": [{"expression": "ga:sessions"}],
"samplingLevel": "LARGE"
}
]
}
Enthält ein Bericht Stichprobendaten, gibt Version 4 der Analytics Reporting API die Felder samplesReadCounts
und samplingSpaceSizes
zurück.
Wenn die Ergebnisse nicht auf Stichproben basieren, werden diese Felder nicht definiert.
Die folgende Beispielantwort enthält Stichprobendaten aus einer Anfrage mit zwei Zeiträumen. Die Ergebnisse wurden aus fast 500.000 Stichproben mit einer Stichprobengröße von etwa 15 Millionen Sitzungen berechnet:
{
"reports":
[
{
"columnHeader": {
...
},
"data": {
...
"samplesReadCounts": [ "499630","499630"],
"samplingSpaceSizes": ["15328013","15328013"],
}
}
]
}
Seitenumbruch
In der Analytics Reporting API Version 4 werden die Felder pageToken
und pageSize
für die Paginierung in Antwortergebnissen verwendet, die sich über mehrere Seiten erstrecken. Sie erhalten pageToken
aus dem Parameter nextPageToken
in der Antwort auf die Anfrage reports.batchGet
:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
...
# Taken from `nextPageToken` of a previous response.
"pageToken": "10000",
"pageSize": "10000",
}]
}
Nächster Schritt
Sie kennen jetzt die Grundlagen der Berichterstellung. Werfen Sie nun einen Blick auf die erweiterten Funktionen von API v4.