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:
metricNamenotoperatorcomparisonValue
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
fieldNamean. - Geben Sie die Sortierreihenfolge (
ASCENDINGoderDESCENDING) über das FeldsortOrderan.
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:
dimensionNamenotoperatorexpressionscaseSensitive
{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
fieldNamean. - Geben Sie die Sortierreihenfolge (
ASCENDINGoderDESCENDING) über das FeldsortOrderan.
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:segmentzur 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
SMALLfest, um eine schnelle Antwort mit einer kleineren Stichprobengröße zu erhalten. - Legen Sie den Wert auf
LARGEfest, um eine genauere, aber langsamere Antwort zu erhalten. - Legen Sie den Wert auf
DEFAULTfest, 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.