概要

Google アナリティクス Data API v1 を使用すると、ピボットテーブルを生成できます。ピボットテーブルは、1 つ以上のディメンションでデータをピボット（回転）して、表の情報を再構成することでデータを可視化するデータ要約ツールです。

例として、次の生データテーブルを検討してください。

元データテーブル

このデータを使用すると、ブラウザ別にセッションデータを分類したピボットテーブルを作成できます。国と言語のディメンションは追加のピボットとして選択されています。

ピボット処理されたデータテーブル

コアレポートとの共有機能

ピボットレポート作成リクエストは、多くの共有機能でコアレポートリクエストと同じセマンティクスを持ちます。たとえば、ページネーション、ディメンションフィルタ、ユーザープロパティは、ピボットレポートとコアレポートで同じように動作します。このガイドでは、ピボットレポート作成機能に焦点を当てます。Data API v1 のコアレポート機能について詳しくは、レポート作成の基本ガイド、および高度なユースケースガイドをご覧ください。

ピボットレポート作成メソッド

Data API v1 では、次のレポート作成メソッドでピボット機能がサポートされています。

runPivotReport: このメソッドは、Google アナリティクスのイベントデータのカスタマイズされたピボットレポートを返します。各ピボットには、レポートレスポンスにディメンションの列と行が表示されます。
batchRunPivotReports: runPivotReport メソッドのバッチバージョンです。 1 回の API 呼び出しで複数のレポートを作成できます。

レポート作成エンティティを選択する

Data API v1 のすべてのメソッドでは、 Google アナリティクスのプロパティ ID を URL リクエストパス内に properties/GA_PROPERTY_ID の形式で指定する必要があります。例:

  POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runPivotReport

生成されるレポートは、指定された Google アナリティクスのプロパティで収集された Google アナリティクスイベントデータに基づいて作成されます。

Data API クライアントライブラリのいずれかを使用している場合は、リクエスト URL パスを手動で操作する必要はありません。ほとんどの API クライアントでは、文字列が properties/GA_PROPERTY_ID の形式の property パラメータが提供されています。クライアントライブラリの使用例については、クイックスタートガイドをご覧ください。

ピボットレポートリクエスト

ピボットテーブルを含むリクエストを作成するには、 runPivotReport メソッドまたは batchRunPivotReports メソッドを使用します。

ピボット処理されたデータをリクエストするには、RunPivotReportRequest オブジェクトを作成します。次のリクエストパラメータから始めることをおすすめします。

dateRanges フィールドの有効なエントリ。
dimensions フィールドの 1 つ以上の有効なエントリ。
metrics フィールドの 1 つ以上の有効なエントリ。
pivots フィールドの 2 つ以上の有効なピボットエントリ。

推奨フィールドを含むリクエストの例を次に示します。

HTTP

POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runPivotReport
  {
    "dateRanges": [{ "startDate": "2020-09-01", "endDate": "2020-09-15" }],
    "dimensions": [
        { "name": "browser" },
        { "name": "country" },
        { "name": "language" }
      ],
    "metrics": [{ "name": "sessions" }],
    "pivots": [
      {
        "fieldNames": [
          "browser"
        ],
        "limit": 5
      },
      {
        "fieldNames": [
          "country"
        ],
        "limit": 250
      },
      {
        "fieldNames": [
          "language"
        ],
        "limit": 15
      }
    ]
  }

ピボット

レポートのピボットを定義するには、リクエスト本文の pivot フィールドで Pivot オブジェクトを使用します。各 Pivot には、レポートレスポンスにディメンションの列と行が表示されます。

Data API v1 では、各ピボットの limit パラメータの積が 100,000 を超えない限り、複数のピボットがサポートされます。

次のスニペットは、pivots を使用して、browser ディメンションでピボット処理された国別セッション数のレポートを作成する方法を示しています。クエリで orderBysフィールドを使用して並べ替えを行い、limit フィールドとoffsetフィールドを使用してページネーションを実装する方法に注目してください。

    "pivots": [
      {
        "fieldNames": [
          "country"
        ],
        "limit": 250,
        "orderBys": [
          {
            "dimension": {
              "dimensionName": "country"
            }
          }
        ]
      },
      {
        "fieldNames": [
          "browser"
        ],
        "offset": 3,
        "limit": 3,
        "orderBys": [
          {
            "metric": {
              "metricName": "sessions"
            },
            "desc": true
          }
        ]
      }
    ],
    ...

ディメンション

ディメンションは、ウェブサイトまたはアプリのイベントデータを記述してグループ化します。たとえば、city ディメンションは、各イベントが発生した市区町村（「横浜」や「川崎」）を示します。レポートリクエストでは、ディメンションを 0 個以上指定できます。

ディメンションは、リクエスト本文の dimensions フィールド内で定義する必要があります。レポートに表示するには、それらのディメンションを fieldNames フィールドのPivotオブジェクトにもリストする必要があります。ピボットクエリのピボットオブジェクトで定義されていないディメンションは、レポートに表示されません。すべてのディメンションがピボットの fieldNames に存在する必要はありません。ディメンションはフィルタでのみ使用でき、ピボットの fieldNames では使用できません。

次のスニペットは、browser、country、language のピボットを含むテーブルの dimension フィールドと fieldNames フィールドの使用方法を示しています。

    "pivots": [
      {
        "fieldNames": [
          "browser"
        ],
        "limit": 5,
        "orderBys": [
          {
            "metric": {
              "metricName": "sessions"
            },
            "desc": true
          }
        ]
      },
      {
        "fieldNames": [
          "country"
        ],
        "limit": 250,
        "orderBys": [
          {
            "dimension": {
              "dimensionName": "country"
            }
          }
        ]
      },
      {
        "fieldNames": [
          "language"
        ],
        "limit": 10
      }
    ],

指標

指標は、ウェブサイトまたはアプリのイベントデータの定量的な測定値です。レポートリクエストでは、1 つ以上の指標を指定できます。リクエストで指定できる API 指標名の完全なリストについては、API 指標をご覧ください。

ピボットレポート作成リクエストでは、指標はmetricsフィールドを使用してリクエスト本文で定義されます。これは、コアレポート作成メソッドと同様です。

次の例では、レポートの指標値として使用するセッション数を指定しています。

    "metrics": [
      {
        "name": "sessions"
      }
    ],

指標の集計

各ピボットの集計指標値を計算するには、metricAggregations Pivot オブジェクトのフィールドを使用します。

集計は、リクエストで metricAggregations フィールドが指定されている場合にのみ計算されます。

次の例は、browser ピボットディメンションの合計をリクエストするクエリのスニペットです。

"pivots": [
  {
    "fieldNames": [
      "browser"
    ],
    "limit": 10,
    "metricAggregations": [
      "TOTAL",
    ]
  },
  ...

計算された指標は、aggregates フィールドの RunPivotReportResponse オブジェクトに返されます。集計された指標の行の場合、dimensionValues フィールドには RESERVED_TOTAL、RESERVED_MAX、RESERVED_MIN の特別な値が含まれます。

  "aggregates": [
    {
      "dimensionValues": [
        {
          "value": "Chrome"
        },
        {
          "value": "RESERVED_TOTAL"
        },
        {
          "value": "RESERVED_TOTAL"
        }
      ],
      "metricValues": [
        {
          "value": "4"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "Firefox"
        },
        {
          "value": "RESERVED_TOTAL"
        },
        {
          "value": "RESERVED_TOTAL"
        }
      ],
      "metricValues": [
        {
          "value": "6"
        }
      ]
    },
  ....

  }

ページネーション

コアレポート作成メソッドと同様に、ピボットリクエストでは、 Pivot オブジェクトの limit フィールドと offset フィールドを指定してページネーションを実装できます。ページネーションの設定は、ピボットごとに個別に適用されます。レポートのカーディナリティを制限するには、すべての Pivot オブジェクトに limit フィールドが必要です。

Data API v1 では、各ピボットの limit パラメータの積が 100,000 を超えない限り、複数のピボットがサポートされます。

次のスニペットは、offset フィールドと limit フィールドを使用して、オフセット 10 で次の 5 つの language ディメンションを取得する方法を示しています。

      {
        "fieldNames": [
          "language"
        ],
        "offset": 10,
        "limit": 5
      }

フィルタリング

コアレポート作成機能と同様に、ピボットレポート作成リクエストでディメンションのフィルタ処理を行う場合は、リクエストスコープのディメンションフィルタを使用する必要があります。

並べ替え

ピボットレポート作成クエリの並べ替え動作は、ピボットごとに個別に orderBys フィールドを使用して制御できます。このフィールドには、Pivotオブジェクトの OrderByオブジェクトのリストが含まれています。

すべての OrderBy には、次のいずれかを含めることができます。

DimensionOrderBy: 結果をディメンションの値で並べ替えます。
MetricOrderBy: 結果を指標の値で並べ替えます。
PivotOrderBy: ピボットクエリグループ内で使用されます。結果をピボット列グループ内で指標の値で並べ替えます。

この例は、レポートを browser ディメンションでピボット処理し、結果を sessions 指標で降順に並べ替えるピボット定義のスニペットを示しています。

      {
        "fieldNames": [
          "browser"
        ],
        "limit": 5,
        "orderBys": [
          {
            "metric": {
              "metricName": "sessions"
            },
            "desc": true
          }
        ]
      }

レポートレスポンス

ピボットレポート API リクエストのピボットレポートレスポンスは、主にヘッダーと行で構成されます。

レスポンスヘッダー

ピボットレポートのヘッダーは、PivotHeaders、 DimensionHeaders と MetricHeaders で構成され、ピボットレポートの列を一覧表示します。

たとえば、browser、country、language のピボットディメンションと sessions 指標を含むレポートでは、次のようなヘッダーが生成されます。

{
  "pivotHeaders": [
    {
      "pivotDimensionHeaders": [
        {
          "dimensionValues": [
            {
              "value": "Chrome"
            }
          ]
        },
        {
          "dimensionValues": [
            {
              "value": "Firefox"
            }
          ]
        },
        ...

      ],
      ...
    },
    {
      "pivotDimensionHeaders": [
        {
          "dimensionValues": [
            {
              "value": "United States"
            }
          ]
        },
        {
          "dimensionValues": [
            {
              "value": "Canada"
            }
          ]
        },
        ...

      ],
      ...
    },
    {
      "pivotDimensionHeaders": [
        {
          "dimensionValues": [
            {
              "value": "English"
            }
          ]
        },
        {
          "dimensionValues": [
            {
              "value": "French"
            }
          ]
        },
        ...

      ],
      ...
    }
  ],
  "dimensionHeaders": [
    {
      "name": "browser"
    },
    {
      "name": "country"
    },
    {
      "name": "language"
    }
  ],
  "metricHeaders": [
    {
      "name": "sessions",
      "type": "TYPE_INTEGER"
    }
  ],
  ...

}

次の図は、ピボットレポートのレンダリングにおけるピボットレポートレスポンスの各コンポーネントの役割を示しています。

元データテーブル

レスポンスの行

runPivotReport メソッドと batchRunPivotReports メソッドのピボットレポートレスポンスは、runReport や batchRunReports などのコアレポート作成メソッドのレスポンスとは異なり、各ピボットレポートレスポンスの行は表の 1 つのセルを表します。通常のレポートでは、1 つのレスポンス行が表の行全体を表します。

次の例は、browser、country、language のピボットディメンションと sessions 指標を含むクエリのピボットレポートレスポンスのフラグメントを示しています。ピボットレポートの各セルは個別に返されます。

  "rows": [
    {
      "dimensionValues": [
        {
          "value": "Chrome"
        },
        {
          "value": "United States"
        },
        {
          "value": "English"
        }
      ],
      "metricValues": [
        {
          "value": "1"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "Firefox"
        },
        {
          "value": "Canada"
        },
        {
          "value": "French"
        }
      ],
      "metricValues": [
        {
          "value": "3"
        }
      ]
    },
    ...

  ]

このデータは、次の表でハイライト表示されている 2 つのセルに対応しています。

元データテーブル

クライアントライブラリ

クライアントライブラリのインストールと構成の方法については、クイックスタートガイドをご覧ください。

次の例では、クライアントライブラリを使用してピボットクエリを実行し、ブラウザディメンションでピボット処理された国別セッション数のレポートを作成します。

PHP

google-analytics-data/src/run_pivot_report.php

Cloud Shell で開く GitHub で表示

use Google\Analytics\Data\V1beta\Client\BetaAnalyticsDataClient;
use Google\Analytics\Data\V1beta\DateRange;
use Google\Analytics\Data\V1beta\Dimension;
use Google\Analytics\Data\V1beta\Metric;
use Google\Analytics\Data\V1beta\OrderBy;
use Google\Analytics\Data\V1beta\OrderBy\DimensionOrderBy;
use Google\Analytics\Data\V1beta\OrderBy\MetricOrderBy;
use Google\Analytics\Data\V1beta\Pivot;
use Google\Analytics\Data\V1beta\RunPivotReportRequest;
use Google\Analytics\Data\V1beta\RunPivotReportResponse;

/**
 * Runs a pivot query to build a report of session counts by country,
 * pivoted by the browser dimension.
 * @param string $propertyId Your GA-4 Property ID
 */
function run_pivot_report(string $propertyId)
{
    // Create an instance of the Google Analytics Data API client library.
    $client = new BetaAnalyticsDataClient();

    // Make an API call.
    $request = (new RunPivotReportRequest())
        ->setProperty('properties/' . $propertyId)
        ->setDateRanges([new DateRange([
            'start_date' => '2021-01-01',
            'end_date' => '2021-01-30',
            ]),
        ])
        ->setPivots([
            new Pivot([
                'field_names' => ['country'],
                'limit' => 250,
                'order_bys' => [new OrderBy([
                    'dimension' => new DimensionOrderBy([
                        'dimension_name' => 'country',
                    ]),
                ])],
            ]),
            new Pivot([
                'field_names' => ['browser'],
                'offset' => 3,
                'limit' => 3,
                'order_bys' => [new OrderBy([
                    'metric' => new MetricOrderBy([
                        'metric_name' => 'sessions',
                    ]),
                    'desc' => true,
                ])],
            ]),
        ])
        ->setMetrics([new Metric(['name' => 'sessions'])])
        ->setDimensions([
            new Dimension(['name' => 'country']),
            new Dimension(['name' => 'browser']),
        ]);
    $response = $client->runPivotReport($request);

    printPivotReportResponse($response);
}

/**
 * Print results of a runPivotReport call.
 * @param RunPivotReportResponse $response
 */
function printPivotReportResponse(RunPivotReportResponse $response)
{
    print 'Report result: ' . PHP_EOL;

    foreach ($response->getRows() as $row) {
        printf(
            '%s %s' . PHP_EOL,
            $row->getDimensionValues()[0]->getValue(),
            $row->getMetricValues()[0]->getValue()
        );
    }
}run_pivot_report.php

Python

google-analytics-data/run_pivot_report.py

Cloud Shell で開く GitHub で表示

from google.analytics.data_v1beta import BetaAnalyticsDataClient
from google.analytics.data_v1beta.types import (
    DateRange,
    Dimension,
    Metric,
    OrderBy,
    Pivot,
    RunPivotReportRequest,
)


def run_sample():
    """Runs the sample."""
    # TODO(developer): Replace this variable with your Google Analytics 4
    #  property ID before running the sample.
    property_id = "YOUR-GA4-PROPERTY-ID"
    run_pivot_report(property_id)


def run_pivot_report(property_id="YOUR-GA4-PROPERTY-ID"):
    """Runs a pivot query to build a report of session counts by country,
    pivoted by the browser dimension."""
    client = BetaAnalyticsDataClient()

    request = RunPivotReportRequest(
        property=f"properties/{property_id}",
        date_ranges=[DateRange(start_date="2021-01-01", end_date="2021-01-30")],
        pivots=[
            Pivot(
                field_names=["country"],
                limit=250,
                order_bys=[
                    OrderBy(
                        dimension=OrderBy.DimensionOrderBy(dimension_name="country")
                    )
                ],
            ),
            Pivot(
                field_names=["browser"],
                offset=3,
                limit=3,
                order_bys=[
                    OrderBy(
                        metric=OrderBy.MetricOrderBy(metric_name="sessions"), desc=True
                    )
                ],
            ),
        ],
        metrics=[Metric(name="sessions")],
        dimensions=[Dimension(name="country"), Dimension(name="browser")],
    )
    response = client.run_pivot_report(request)
    print_run_pivot_report_response(response)


def print_run_pivot_report_response(response):
    """Prints results of a runPivotReport call."""
    print("Report result:")
    for row in response.rows:
        for dimension_value in row.dimension_values:
            print(dimension_value.value)

        for metric_value in row.metric_values:
            print(metric_value.value)

run_pivot_report.py

Node.js

google-analytics-data/run_pivot_report.js

Cloud Shell で開く GitHub で表示

  // TODO(developer): Uncomment this variable and replace with your
  // Google Analytics 4 property ID before running the sample.
  // propertyId = 'YOUR-GA4-PROPERTY-ID';

  // Imports the Google Analytics Data API client library.
  const {BetaAnalyticsDataClient} = require('@google-analytics/data');

  // Initialize client that will be used to send requests. This client only
  // needs to be created once, and can be reused for multiple requests.
  const analyticsDataClient = new BetaAnalyticsDataClient();

  // Runs a pivot query to build a report of session counts by country, pivoted
  // by the browser dimension.
  async function runPivotReport() {
    const [response] = await analyticsDataClient.runPivotReport({
      property: `properties/${propertyId}`,
      dateRanges: [
        {
          startDate: '2021-01-01',
          endDate: '2021-01-30',
        },
      ],
      pivots: [
        {
          fieldNames: ['country'],
          limit: 250,
          orderBys: [
            {
              dimension: {
                dimensionName: 'country',
              },
            },
          ],
        },
        {
          fieldNames: ['browser'],
          offset: 3,
          limit: 3,
          orderBys: [
            {
              metric: {
                metricName: 'sessions',
              },
              desc: true,
            },
          ],
        },
      ],
      metrics: [
        {
          name: 'sessions',
        },
      ],
      dimensions: [
        {
          name: 'country',
        },
        {
          name: 'browser',
        },
      ],
    });
    printPivotReportResponse(response);
  }

  runPivotReport();

  // Prints results of a runReport call.
  function printPivotReportResponse(response) {
    console.log('Report result:');
    response.rows.forEach((row) => {
      row.dimensionValues.forEach((dimensionValue) => {
        console.log(dimensionValue.value);
      });

      row.metricValues.forEach((metricValue) => {
        console.log(metricValue.value);
      });
    });
  }run_pivot_report.js

デモアプリケーション

JavaScript を使用してピボットレポートを作成して表示する方法の例については、Google アナリティクス API v1 ピボットレポートデモアプリケーションをご覧ください。

概要 コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

コアレポートとの共有機能

ピボット レポート作成メソッド

レポート作成エンティティを選択する

ピボット レポート リクエスト

HTTP

ピボット

ディメンション

指標

指標の集計

ページネーション

フィルタリング

並べ替え

レポート レスポンス

レスポンス ヘッダー

レスポンスの行

クライアント ライブラリ

PHP

Python

Node.js

デモ アプリケーション

概要

ピボットレポート作成メソッド

ピボットレポートリクエスト

レポートレスポンス

レスポンスヘッダー

クライアントライブラリ

デモアプリケーション