Bericht erstellen

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

In Version 4 der Analytics Reporting API gibt es die Methode batchGet, um auf die Ressource 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

Sie können die ID der Datenansicht ermitteln, indem Sie die Methode Kontozusammenfassung abfragen oder den Konto-Explorer verwenden. Wenn kein Zeitraum angegeben ist, gilt der Standardzeitraum: {"startDate": "7daysAgo", "endDate": "yesterday"}.

Hier eine Beispielanfrage mit 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 werden maximal fünf ReportRequest-Objekte akzeptiert. Alle Anfragen sollten die gleichen Werte für dateRange, viewId, segments, samplingLevel und cohortGroup haben.

Antworttext

Der Antworttext der API-Anfrage ist ein 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 ist eine Beispielantwort für 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 an die Methode batchGet übergeben, um die Gesamtzahl der Sitzungen im angegebenen Zeitraum abzurufen:

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 Dimensions and Metrics Explorer 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 einen oder mehrere MetricFilterClauses an und definieren Sie in jedem MetricFilterClause einen oder mehrere MetricFilters. Geben Sie in jeder MetricFilter die folgenden Werte an:

  • metricName
  • not
  • operator
  • comparisonValue

{metricName} steht für den Messwert, {operator} für operator und {comparisonValue} für comparisonValue. Dann funktioniert der Filter 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 definieren, der den Messwertausdruck darstellt. 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 über das Feld fieldName an.
  • Geben Sie die Sortierreihenfolge (ASCENDING oder DESCENDING) über das Feld sortOrder 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 jeder 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. Dann funktioniert der Filter 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 oder DESCENDING) über das Feld sortOrder an.

Beispiel: Die folgende batchGet gibt 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 Ganzzahlwerten ist es einfacher, ihre Eigenschaften zu verstehen, wenn die Werte in Bereiche gruppiert werden. Verwenden Sie das Feld histogramBuckets, um die Bereiche für die resultierenden Buckets zu definieren und HISTOGRAM_BUCKET als Reihenfolgetyp anzugeben. 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 mit einer einzigen Anfrage abrufen. Unabhängig davon, ob in der Anfrage ein oder zwei Zeiträume angegeben sind, werden die Daten im Objekt dateRangeValue 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.

Nehmen wir beispielsweise eine Anfrage für die Dimension ga:date und den Messwert ga:sessions für zwei Zeiträume: Januar und Februar. In der Antwort auf die angeforderten Daten im Januar sind die Werte im Februar 0 und in der Antwort auf die im Februar angeforderten Daten 0.

Bericht für Januar

{
    "dimensions": [
        "20140101" # `ga:date` dimension value for January 1, 2014.
    ],
    "metrics": [
        {
            "values": [ # January DateRangeValue.
                "8"
            ]
        },
        {
            "values": [ # February DateRangeValue.
                "0"
            ]
        }
    ]
},
...

Bericht für Februar

{
    "dimensions": [
        "20140201"  # `ga:date` dimension value for February 1, 2014.
    ],
    "metrics": [
        {
            "values": [ # January DateRangeValue.
                "0"
            ]
        },
        {
            "values": [ # February DateRangeValue.
                "7"
            ]
        }
    ]
},
...

Segmente

Wenn Sie einen Teil der 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 definieren und Nutzer, die einen bestimmten Bereich Ihrer Website in einem anderen Segment besuchen. Filter geben nur Zeilen zurück, die eine Bedingung erfüllen, während für Segmente Teilmengen von Nutzern, Sitzungen oder Ereignissen zurückgegeben werden, die die Bedingungen erfüllen, in denen die Segmente enthalten sind.

Achten Sie bei einer Anfrage mit Segmenten auf Folgendes:

  • Jeder 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 ausbalancierte Antwort auf Schnelligkeit und Genauigkeit zu erhalten.

Beispiel:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dimensions": [{"name": "ga:medium"}],
      "metrics": [{"expression": "ga:sessions"}],
      "samplingLevel":  "LARGE"
    }
  ]
}

Falls ein Bericht Stichprobendaten enthält, gibt die Analytics Reporting API Version 4 die Felder samplesReadCounts und samplingSpaceSizes zurück. Wenn keine Stichproben der Ergebnisse vorliegen, 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 Version 4 der Analytics Reporting API werden die Felder pageToken und pageSize verwendet, um durch Antwortergebnisse zu blättern, 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

Nachdem Sie nun die Grundlagen zum Erstellen eines Berichts kennen, können Sie sich die erweiterten Funktionen von API Version 4 ansehen.