Google Analytics Data API v1 を使用すると、ピボット テーブルを生成できます。ピボット テーブルは、1 つ以上のディメンションでデータをピボット(回転)してテーブル内の情報を並べ替えることで、データを可視化するデータ要約ツールです。
例として、次の元データのテーブルについて考えてみましょう。
このデータを使用してピボット テーブルを作成し、国と言語のディメンションを追加のピボットとして選択した状態で、セッション データをブラウザ別に分割できます。
コアレポートとの共有機能
ピボット レポート リクエストには、多くの共有機能に対するコアレポート リクエストと同じセマンティクスがあります。たとえば、ページ設定、ディメンション フィルタ、ユーザー プロパティは、ピボット レポートではコアレポートと同じように動作します。このガイドでは、ピボット レポート機能を中心に説明します。Data API v1 の Core レポート機能の詳細については、レポートの基本ガイドと高度なユースケースをご覧ください。
ピボット レポート方法
Data API v1 では、次のレポート メソッドでピボット機能がサポートされています。
runPivotReport: このメソッドは、Google アナリティクス イベントデータのカスタマイズされたピボット レポートを返します。各ピボットは、レポート レスポンスに表示されるディメンションの列と行を表します。
batchRunPivotReports:
runPivotReport
メソッドのバッチ バージョンで、1 回の API 呼び出しで複数のレポートを生成できます。
報告エンティティの選択
Data API v1 のすべてのメソッドで、URL リクエストパス内に properties/GA4_PROPERTY_ID
の形式で Google アナリティクス 4 プロパティ識別子を指定する必要があります。次に例を示します。
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runPivotReport
レポートは、指定した Google アナリティクス 4 プロパティで収集された Google アナリティクス イベントデータに基づいて生成されます。
Data API クライアント ライブラリのいずれかを使用している場合は、リクエスト URL パスを手動で操作する必要はありません。ほとんどの API クライアントでは、文字列が properties/GA4_PROPERTY_ID
の形式の property
パラメータが提供されています。クライアント ライブラリの使用例については、クイック スタートガイドをご覧ください。
ピボット レポート リクエスト
ピボット テーブルを含むリクエストを作成するには、runPivotReport または batchRunPivotReports メソッドを使用します。
ピボットデータをリクエストするには、RunPivotReportRequest オブジェクトを作成します。まずは以下のリクエスト パラメータから始めることをおすすめします。
- dateRanges フィールドの有効なエントリ。
- ディメンション フィールドに有効なエントリが 1 つ以上ある。
- metrics フィールドの 1 つ以上の有効なエントリ。
- ピボット フィールドに有効なピボット エントリを 2 つ以上指定してください。
推奨されるフィールドを含むリクエストの例を次に示します。
HTTP
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_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 フィールド内で定義する必要があります。これらのディメンションがレポートに表示されるには、Pivot
オブジェクトの fieldNames フィールドでも含まれている必要があります。ディメンションは、ピボットクエリのピボットで使用されていない場合、レポートに表示されません。すべてのディメンションがピボットの 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 指標をご覧ください。
ピボット レポートのリクエストでは、Core Reporting メソッドと同様に、リクエスト本文の metrics
フィールドで指標を定義します。
次の例では、レポートの指標値として使用されるセッション数を指定しています。
"metrics": [
{
"name": "sessions"
}
],
指標の集計
各ピボットの集計された指標値を計算するには、Pivot オブジェクトの metricAggregations フィールドを使用します。
集計は、リクエストで metricAggregations フィールドが指定されている場合にのみ計算されます。
以下は、browser
ピボット ディメンションの合計をリクエストするクエリのスニペットです。
"pivots": [
{
"fieldNames": [
"browser"
],
"limit": 10,
"metricAggregations": [
"TOTAL",
]
},
...
計算指標は、RunPivotReportResponse オブジェクトの aggregates フィールドで返されます。集計された指標行の場合、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"
}
]
},
....
}
ページネーション
Core Reporting メソッドと同様に、ピボット リクエストでは、ピボット オブジェクトの limit フィールドと offset フィールドを指定して、ページ分割を実装できます。ページ分けの設定は、各ピボットに個別に適用されます。レポートの基数を制限するには、すべての Pivot
オブジェクトに limit
フィールドが必要です。
Data API v1 では、各ピボットの limit
パラメータの積が 100,000 を超えない限り、複数のピボットがサポートされます。
以下のスニペットは、offset
フィールドと limit
フィールドを使用して、オフセット 10 で次の 5 つの language
ディメンションを取得する方法を示しています。
{
"fieldNames": [
"language"
],
"offset": 10,
"limit": 5
}
フィルタリング
Core レポート機能と同様に、ピボット レポート リクエストでディメンション フィルタリングが必要な場合は、リクエスト スコープのディメンション フィルタを使用する必要があります。
並べ替え
ピボット レポート クエリの順序動作は、OrderBy オブジェクトのリストを含む Pivot オブジェクトの orderBys フィールドを使用して、ピボットごとに個別に制御できます。
すべての 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 などの Core Reporting メソッドのレスポンスと異なります。各ピボット レポート レスポンス行はテーブルの 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
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() ); } }
Python
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)
Node.js
// 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); }); }); }
デモ アプリケーション
JavaScript を使用してピボット レポートを作成して表示する方法の例については、Google Analytics API v1 ピボット レポートのデモ アプリケーションをご覧ください。