このドキュメントでは、既存のコードを Google アナリティクス Reporting API v4 から Google アナリティクス Data API v1 に移行する方法と、これら 2 つの API の主な相違点についての概要を説明します。
移行が必要な理由
Reporting API v4 ではユニバーサル アナリティクスで作成されたプロパティにしかアクセスできません。そのため、アプリケーションが Google アナリティクス 4 プロパティのデータにアクセスする場合、コードを更新して Data API v1 を使用するようにする必要があります。
前提条件
クイック スタートガイドを読んで、Data API v1 の基本を理解しておくこと
はじめに
まず Google アナリティクス 4 プロパティを準備し、Data API v1 を有効にしてから、プラットフォームに適した API クライアント ライブラリを設定します。
Google アナリティクス 4 プロパティを準備する
Google アナリティクス 4 プロパティを使用できるようにウェブサイトを移行してから、Data API v1 がサポートされるようコードを移行する必要があります。ユニバーサル アナリティクス プロパティの過去のデータで Google アナリティクス 4 プロパティをバックフィルすることはできません。
API を有効にする
以下のリンクをクリックすると、選択した Google Cloud プロジェクトで Data API v1 が自動的に有効になります。
Google アナリティクス Data API v1 を有効にするクライアント ライブラリを使用する
クライアント ライブラリをインストールする
クライアント ライブラリを使用する場合は、各プログラミング言語用の Data API v1 クライアント ライブラリをインストールする必要があります。
Java
Python
Node.js
.NET
PHP
Go
go get google.golang.org/genproto/googleapis/analytics/data/v1beta
クライアント ライブラリを初期化する
Data API v1 クライアント ライブラリは、すぐに使用を開始できるように設計されています。 デフォルトでは、クライアント ライブラリはサービス アカウントの認証情報を自動的に検索します。
サービス アカウントの認証情報を提供する最も簡単な方法は、GOOGLE_APPLICATION_CREDENTIALS 環境変数を設定することです。API クライアントは、この変数の値を使用してサービス アカウント キーの JSON ファイルを見つけます。
たとえば、サービス アカウントの認証情報を設定するには、サービス アカウントの JSON ファイルのパスを使って次のコマンドを実行します。
export GOOGLE_APPLICATION_CREDENTIALS="[PATH]"
以下は、Data API v1 クライアント ライブラリの初期化に一般的に使用されるコード スニペットです。
Java
// Using a default constructor instructs the client to use the credentials
// specified in GOOGLE_APPLICATION_CREDENTIALS environment variable.
try (BetaAnalyticsDataClient analyticsData = BetaAnalyticsDataClient.create()) {
Python
# Using a default constructor instructs the client to use the credentials
# specified in GOOGLE_APPLICATION_CREDENTIALS environment variable.
client = BetaAnalyticsDataClient()
.NET
// Using a default constructor instructs the client to use the credentials
// specified in GOOGLE_APPLICATION_CREDENTIALS environment variable.
BetaAnalyticsDataClient client = BetaAnalyticsDataClient.Create();
PHP
// Using a default constructor instructs the client to use the credentials // specified in GOOGLE_APPLICATION_CREDENTIALS environment variable. $client = new BetaAnalyticsDataClient();
Node.js
// Imports the Google Analytics Data API client library.
const {BetaAnalyticsDataClient} = require('@google-analytics/data');
// Using a default constructor instructs the client to use the credentials
// specified in GOOGLE_APPLICATION_CREDENTIALS environment variable.
const analyticsDataClient = new BetaAnalyticsDataClient();
環境変数を使用する代わりに、初期化中に認証情報を API クライアント インスタンスに明示的に渡すこともできます。以下のコード スニペットを使って明示的に認証情報を渡して、Data API v1 クライアント ライブラリを初期化します。
Java
// Explicitly use service account credentials by specifying
// the private key file.
GoogleCredentials credentials =
GoogleCredentials.fromStream(new FileInputStream(credentialsJsonPath));
BetaAnalyticsDataSettings betaAnalyticsDataSettings =
BetaAnalyticsDataSettings.newBuilder()
.setCredentialsProvider(FixedCredentialsProvider.create(credentials))
.build();
try (BetaAnalyticsDataClient analyticsData =
BetaAnalyticsDataClient.create(betaAnalyticsDataSettings)) {
Python
# TODO(developer): Uncomment this variable and replace with a valid path to
# the credentials.json file for your service account downloaded from the
# Cloud Console.
# credentials_json_path = "/path/to/credentials.json"
# Explicitly use service account credentials by specifying
# the private key file.
client = BetaAnalyticsDataClient.from_service_account_json(credentials_json_path)
.NET
/**
* TODO(developer): Uncomment this variable and replace with a valid path to
* the credentials.json file for your service account downloaded from the
* Cloud Console.
* Otherwise, default service account credentials will be derived from
* the GOOGLE_APPLICATION_CREDENTIALS environment variable.
*/
// credentialsJsonPath = "/path/to/credentials.json";
// Explicitly use service account credentials by specifying
// the private key file.
BetaAnalyticsDataClient client = new BetaAnalyticsDataClientBuilder
{
CredentialsPath = credentialsJsonPath
}.Build();
PHP
/**
* @param string $credentialsJsonPath Valid path to the credentials.json file for your service
* account downloaded from the Cloud Console.
* Example: "/path/to/credentials.json"
*/
function client_from_json_credentials(string $credentialsJsonPath)
{
// Explicitly use service account credentials by specifying
// the private key file.
$client = new BetaAnalyticsDataClient([
'credentials' => $credentialsJsonPath
]);
return $client;
}
Node.js
/** TODO(developer): Uncomment this variable and replace with a valid path to
* the credentials.json file for your service account downloaded from the
* Cloud Console.
*/
// credentialsJsonPath = '/path/to/credentials.json';
// Imports the Google Analytics Data API client library.
const {BetaAnalyticsDataClient} = require('@google-analytics/data');
// Explicitly use service account credentials by specifying
// the private key file.
const analyticsDataClient = new BetaAnalyticsDataClient({
keyFilename: credentialsJsonPath,
});
クライアント ライブラリを使用していない場合
Reporting API v4 をクライアント ライブラリなしで使用していて Data API v1 でも引き続き使用しない場合でも、認証情報を使用できます。
Data API によって提供される新しい HTTP エンドポイントとディスカバリ ドキュメントを使用する必要があります。
コードでディスカバリ ドキュメントを使用している場合は、Data API v1 によって提供されるディスカバリ ドキュメントに更新する必要があります。
エンドポイントを更新したら、Data API の新しいリクエスト構造と概念をよく理解してから JSON クエリを更新してください。
コアレポート作成機能
利用可能なレポート作成メソッド
コアレポート作成機能を利用するには、Reporting API v4 では batchGet メソッドだけが提供されていましたが、Data API v1 では次のメソッドが提供されています。
- runReport: このメソッドは、Google アナリティクス イベント データのカスタム レポートを返します。ピボット機能はサポートされていないため、単純なレポートクエリに適しています。
- runPivotReport: このメソッドは、Google アナリティクス イベント データのカスタマイズされたピボット レポートを返します。Reporting API v4 のピボットと同様に、各ピボットにはレポート レスポンスにディメンションの列と行が表示されます。
- batchRunReports:
runReportメソッドのバッチ バージョンです。1 回の API 呼び出しで複数のレポートを作成できます。 - batchRunPivotReports:
runPivotReportメソッドのバッチ バージョンです。1 回の API 呼び出しで複数のレポートを作成できます。
ユーザーの便宜を図って、いくつかのレポート作成機能が用意されてします。ピボットやバッチよりも複雑な機能をサポートするメソッドもありますが、それ以外の場合はリクエストは類似した構造になっています。
API スキーマの変更
Reporting API と Data API の両方のレポート作成能力は、それぞれのスキーマ（レポート作成クエリでサポートされるディメンションと指標）によって主に決まります。ユニバーサル アナリティクスと Google アナリティクス 4 には概念的に違いがあるため、2 つの API ではそのスキーマに大きな違いがあります。
- Data API でサポートされている最新のディメンションと指標のリストをよく理解しておいてください。現時点では、すべてのディメンションと指標の間に互換性があります。そのため、Dimensions & Metrics Explorer を使用して、互換性のある組み合わせを判断する必要はありませんが、将来的には必要となります。
- Google アナリティクス 4 のカスタム ディメンションにアクセスするには、Reporting API v4 の ga:dimensionXX ディメンション スロットの代わりに、Data API v1 のカスタム ディメンション構文を使用します。
- Google アナリティクス 4 のカスタム指標にアクセスするには、Reporting API v4 の ga:metricXX 指標スロットの代わりに、Data API v1 のカスタム指標構文を使用します。
- ユニバーサル アナリティクスのディメンションと指標の中には、Google アナリティクス 4 に直接対応するものがあります。詳しくは、ユニバーサル アナリティクス / Google アナリティクス 4 API スキーマ対応表をご覧ください。
- Google アナリティクス 4 では、ディメンション名と指標名に
ga:接頭辞がなくなりました。 - ユニバーサル アナリティクスの一部の機能（キャンペーン マネージャー、ディスプレイ＆ビデオ 360、検索広告 360 との統合など）は、Google アナリティクス 4 ではまだご利用いただけません。この機能が Google アナリティクス 4 で導入されると、Data API でもこの機能がサポートされ、新しいディメンションと指標が API スキーマに追加されます。
Entities
Google アナリティクス 4 には、ユニバーサル アナリティクスに導入されているビュー（旧プロファイル）の概念がありません。そのため、Data API v1 のレポート作成リクエストに viewId パラメータはありません。Data API v1 メソッドを呼び出す際には、代わりに Google アナリティクス 4 プロパティ ID（数値）をリクエスト URL パスに指定する必要があります。この動作は、ビュー ID（旧プロファイル ID）によってレポート エンティティを識別する Reporting API v4 の場合とは異なります。
Data API v1
Data API v1 の場合、Google アナリティクス 4 プロパティ ID（数値）を URL パスに指定する必要があります。
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
Reporting API v4
Reporting API v4 では、レポートクエリの本文にユニバーサル アナリティクスのビュー ID（旧プロファイル ID）を指定する必要があります。
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
....
Data API クライアント ライブラリのいずれかを使用している場合は、リクエスト URL パスを手動で操作する必要はありません。ほとんどの API クライアントでは、文字列が properties/GA4_PROPERTY_ID の形式の property パラメータが提供されています。クライアント ライブラリの使用例については、クイック スタートガイドをご覧ください。
期間
Reporting API v4 と Data API v1 のどちらも、レポート作成リクエストの dateRanges フィールドを使用して複数の期間を指定できます。どちらの API も同じ日付入力形式を使用し、YYYY-MM-DD 形式の絶対日付値、または yesderday、today、7daysAgo などの相対日付を指定できます。
Data API v1 のリクエストでは期間を 4 件まで指定できますが、Reporting API v4 では 1 回のレポート作成リクエストで 2 件まで指定できます。
Data API v1 の各 dateRange には、オプションで name フィールドを含めることができます。このフィールドを使って、レスポンス内の対応する期間を参照できます。name を指定しない場合、期間名が自動的に生成されます。
Data API v1 リクエストで複数の期間が指定されると、新しい dateRange ディメンションがレスポンスに自動的に追加され、期間名がディメンション値として使用されます。この動作は、期間のデータを各行内の指標値のグループとして返す Reporting API v4 の場合とは異なります。
Data API v1 のリクエスト
オプションの name フィールドは、リクエスト内の各 dateRange 値に使用されます。この期間名はレスポンスの dateRange ディメンションの値として使用されます。
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"metrics": [
{
"name": "sessions"
}
],
"dimensions": [
{
"name": "country"
}
],
"dateRanges": [
{
"startDate": "2020-01-01",
"endDate": "2020-01-31",
"name": "year_ago"
},
{
"startDate": "2021-01-01",
"endDate": "2021-01-31",
"name": "current_year"
}
]
}
Data API v1 のレスポンス
追加の dateRange ディメンションは自動的にレスポンスに含まれます。dateRange ディメンション値には、dateRange.name フィールドから取得した期間名、または自動的に生成された期間名が含まれています。
....
"dimensionHeaders": [
{
"name": "country"
},
{
"name": "dateRange"
}
],
....
"rows": [
....
{
"dimensionValues": [
{
"value": "Japan"
},
{
"value": "year_ago"
}
],
"metricValues": [
{
"value": "253286"
}
]
},
{
"dimensionValues": [
{
"value": "Japan"
},
{
"value": "current_year"
}
],
"metricValues": [
{
"value": "272582"
}
]
},
....
Reporting API v4 のリクエスト
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"dateRanges": [
{
"startDate": "2020-01-01",
"endDate": "2020-01-31",
},
{
"startDate": "2021-01-01",
"endDate": "2021-01-31",
}
],
"metrics": [
{
"expression": "ga:sessions"
}
],
"dimensions": [
{
"name": "ga:country"
}
]
}
]
}
Reporting API v4 のレスポンス
Reporting API v4 では、各期間の値は metrics フィールド内にグループ化されます。
{
"dimensions": [
"Japan"
],
"metrics": [
{
"values": [
"253286"
]
},
{
"values": [
"272582"
]
}
]
},
並べ替え
Data API v1 レポートクエリの並べ替え動作は、Reporting API v4 の orderBys フィールド と類似した orderBys フィールドを使って制御できます。
Data API v1 の OrderBy 仕様が変更され、すべての OrderBy には次のいずれかを含めることができます。
- DimensionOrderBy: 結果をディメンションの値で並べ替えます。
- MetricOrderBy: 結果を指標の値で並べ替えます。
- PivotOrderBy: ピボットクエリ グループ内で使用されます。結果をピボット列グループ内で指標の値で並べ替えます。
Reporting API v4 でサポートされている DELTA、SMART、HISTOGRAM_BUCKET 並べ替えタイプは、Data API v1 では実装されていません。
Data API v1 の OrderType.NUMERIC 並べ替えタイプは、Reporting API v4 の OrderType.DIMENSION_AS_INTEGER の値と同等になります。
Data API v1 のリクエスト
以下は、国別のセッション数のレポートを作成し、sessions 指標の行を降順で並べ替えるサンプルクエリです。
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"metrics": [
{
"name": "sessions"
}
],
"dimensions": [
{
"name": "country"
}
],
"dateRanges": [
{
"startDate": "yesterday",
"endDate": "today"
}
],
"orderBys": [
{
"metric": {
"metricName": "sessions"
},
"desc": true
}
]
}
Data API v1 のレスポンス
{
"dimensionHeaders": [
{
"name": "country"
}
],
"metricHeaders": [
{
"name": "sessions",
"type": "TYPE_INTEGER"
}
],
"rows": [
{
"dimensionValues": [
{
"value": "United States"
}
],
"metricValues": [
{
"value": "510449"
}
]
},
{
"dimensionValues": [
{
"value": "Japan"
}
],
"metricValues": [
{
"value": "283430"
}
]
},
....
],
"totalSize": 212,
"metadata": {}
}
Reporting API v4 のリクエスト
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"dateRanges": [
{
"startDate": "yesterday",
"endDate": "today"
}
],
"metrics": [
{
"expression": "ga:sessions"
}
],
"dimensions": [
{
"name": "ga:country"
}
],
"orderBys": [
{
"fieldName": "ga:sessions",
"sortOrder": "DESCENDING"
}
]
}
]
}
Reporting API v4 のレスポンス
{
"reports": [
{
....
"data": {
"rows": [
{
"dimensions": [
"United States"
],
"metrics": [
{
"values": [
"510449"
]
}
]
},
{
"dimensions": [
"Japan"
],
"metrics": [
{
"values": [
"283430"
]
}
]
},
....
}
]
}
フィルタ処理
Data API v1 では、dimensionFilter と metricFilter 句を使用して、特定のディメンションまたは指標の値のデータのみを返すように API に要求できます。これは、Reporting API v4 の dimensionFilterClauses と metricFilterClauses に似ています。
Data API v1 では、Reporting API v4 の filtersExpression 句のようなフィルタ文字列はサポートされていません。これらの式は、dimensionFilter 句と metricFilter 句を使用して書き換える必要があります。
Data API v1 のリクエスト
以下のサンプル リクエストでは、ユーザーがアクセスした特定のページパスのセッション数のリストを返します。
dimensionFilter 句は、pagePath ディメンション値が /webstore/ で始まり、文字列 action=a12345 を含む行のみを返すために使用されています。
metricFilter 句は、sessions 指標値が 1,000 より大きい行のみを返すよう runReport メソッドに要求するために使用されています。
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"metrics": [
{
"name": "sessions"
}
],
"dimensions": [
{
"name": "pagePath"
}
],
"dimensionFilter": {
"andGroup": {
"expressions": [
{
"filter": {
"stringFilter": {
"value": "/webstore/",
"matchType": "BEGINS_WITH"
},
"fieldName": "pagePath"
}
},
{
"filter": {
"stringFilter": {
"matchType": "CONTAINS",
"value": "action=a12345"
},
"fieldName": "pagePath"
}
}
]
}
},
"metricFilter": {
"filter": {
"numericFilter": {
"value": {
"int64Value": 1000
},
"operation": "GREATER_THAN"
},
"fieldName": "sessions"
}
},
"dateRanges": [
{
"startDate": "yesterday",
"endDate": "today"
}
]
}
Reporting API v4 のリクエスト
以下のサンプル リクエストは上記の Data API v1 のサンプルと同様、ユーザーがアクセスした特定のページパスのセッション数のリストを返します。
dimensionFilterClauses 句は、pagePath ディメンション値が /webstore/ で始まり文字列 action=a12345 を含む行のみを返すために使用されています。
metricFilterClauses フィールドは、ga:sessions 指標値が 1,000 より大きい行のみを返すために使用されています。
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"metrics": [
{
"expression": "ga:sessions"
}
],
"dimensions": [
{
"name": "ga:pagePath"
}
],
"metricFilterClauses": [
{
"filters": [
{
"metricName": "ga:sessions",
"operator": "GREATER_THAN",
"comparisonValue": "1000"
}
]
}
],
"dimensionFilterClauses": [
{
"filters": [
{
"dimensionName": "ga:pagePath",
"operator": "BEGINS_WITH",
"expressions": [
"/webstore/"
]
},
{
"dimensionName": "ga:pagePath",
"operator": "PARTIAL",
"expressions": [
"action=a12345"
]
}
],
"operator": "AND"
}
],
"dateRanges": [
{
"startDate": "yesterday",
"endDate": "today"
}
]
}
]
}
ページ分け
複数のページにまたがるレスポンスの結果のページ分けは、Reporting API v4 では pageToken と pageSize を使用しますが、Data API v1 では、limit フィールドと offset フィールドを使用します。
Data API v1 のピボット作成リクエストでは、Pivot オブジェクトの limit フィールドと offset フィールドを使用して、ピボットごとにページ分けを実装する必要があります。limit フィールドがすべての Pivot オブジェクトに必須になりました。
デフォルトでは、Data API v1 は最大で最初の 10,000 行のイベントデータを返します（Reporting API v4 のデフォルト値は 1,000 行）。
Data API v1 のレスポンスで rowCount フィールドを使用すると、クエリに一致する合計数の行が返されます。この点は、Reporting API v4 の場合と似ています。
Data API v1 のリクエスト
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"dateRanges": [
....
],
"metrics": [
....
],
"dimensions": [
....
],
"limit": 5,
"offset": 15
}
Data API v1 のレスポンス
{
"dimensionHeaders": [
....
],
"metricHeaders": [
....
],
"rows": [
....
],
"rowCount": 228,
}
Reporting API v4 のリクエスト
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"dateRanges": [
....
],
"metrics": [
....
],
"dimensions": [
....
],
"pageSize": 5,
"pageToken": "5"
}
]
}
Reporting API v4 のレスポンス
{
"reports": [
{
....
"data": {
"rows": [
....
],
....
"rowCount": 225,
},
"nextPageToken": "15"
}
]
}
指標の集計
Data API v1 では、リクエストで metricAggregations フィールドが指定されている場合にのみ、集計値が計算されます。一方 Reporting API v4 では、hideTotals および hideValueRanges フィールドが true に設定されていない限り、各指標の合計、最小値、最大値がデフォルトで返されます。
Data API v1 のリクエスト
集計は、リクエストで metricAggregations フィールドが指定されている場合にのみ計算されます。
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"metricAggregations": [
"TOTAL",
"MAXIMUM",
"MINIMUM"
],
"metrics": [
{
"name": "sessions"
}
],
"dimensions": [
{
"name": "country"
}
],
"dateRanges": [
{
"startDate": "yesterday",
"endDate": "today"
}
]
}
Data API v1 のレスポンス
集計された指標の行は、レスポンスの totals、minimum、maximum フィールドに返されます。集計された指標の行では、dimensionValues フィールドには RESERVED_TOTAL、RESERVED_MAX、RESERVED_MIN という特別な値が含まれます。
{
"dimensionHeaders": [
....
],
"metricHeaders": [
....
],
"rows": [
....
],
"totals": [
{
"dimensionValues": [
{
"value": "RESERVED_TOTAL"
},
{
"value": "RESERVED_TOTAL"
}
],
"metricValues": [
{
"value": "6026053"
}
]
}
],
"maximums": [
{
"dimensionValues": [
{
"value": "RESERVED_MAX"
},
{
"value": "RESERVED_MAX"
}
],
"metricValues": [
{
"value": "493655"
}
]
}
],
"minimums": [
{
"dimensionValues": [
{
"value": "RESERVED_MIN"
},
{
"value": "RESERVED_MIN"
}
],
"metricValues": [
{
"value": "1"
}
]
}
],
....
}
Reporting API v4 のリクエスト
国別のセッション数を返すサンプル リクエストは次のとおりです。
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"dateRanges": [
{
"startDate": "yesterday",
"endDate": "today"
}
],
"metrics": [
{
"expression": "ga:sessions"
}
],
"dimensions": [
{
"name": "ga:country"
}
],
}
]
}
Reporting API v4 のレスポンス
Reporting API v4 のレスポンスには、デフォルトで totals、minimums、maximums の各フィールドが含まれています。
{
"reports": [
{
"columnHeader": {
....
},
"data": {
"rows": [
....
],
....
"totals": [
{
"values": [
"4493363"
]
}
],
"minimums": [
{
"values": [
"1"
]
}
],
"maximums": [
{
"values": [
"684005"
]
}
]
}
}
]
}
ピボット
Data API v1 では、runPivotReport および batchRunPivotReports のレポート作成メソッドでピボット機能がサポートされています。
Reporting API v4 では、batchGet メソッドを使用してレポート作成クエリにピボットを含めることができます。
Data API v1 でのピボットの実装は、レスポンスの各行が表の 1 つのセルを表しているのに対し、Reporting API v4 ではレスポンスの各行が表の行全体を表しているという点で異なっています。
Data API v1
以下は、runPivotReport クエリに対する Data API v1 レスポンスのフラグメントです。ピボット レポートの各セルは個別に返されます。
"rows": [
{
"dimensionValues": [
{
"value": "Albania"
},
{
"value": "Edge"
}
],
"metricValues": [
{
"value": "1701"
}
]
},
Reporting API v4
以下は、batchGet クエリに対する Reporting API v4 レスポンスのフラグメントです。1 つのレスポンス行は、pivotValueRegions のピボットのすべての指標値を格納した、表の行全体を表します。
"data": {
"rows": [
{
"dimensions": [
"Albania"
],
"metrics": [
{
"values": [
"42394"
],
"pivotValueRegions": [
{
"values": [
"24658",
"17208",
"132"
]
}
]
}
]
},
Data API v1 では、runPivotReport クエリまたは batchRunPivotReports クエリのすべてのディメンションがピボット オブジェクト内で定義されている必要があります。ピボットクエリのピボット オブジェクトで定義されていないディメンションは、レポートに表示されません。
Data API v1 のピボット列は、Reporting API v4 の dimensions フィールドの代わりに fieldNames フィールドを使って指定されます。
Data API v1 のレポート作成リクエストでディメンションのフィルタ処理が必要な場合は、リクエスト スコープのディメンション フィルタを使用する必要があります。これは、ピボット オブジェクトの dimensionFilterClauses 仕様を受け入れる Reporting API v4 の場合とは異なります。
Data API v1 の offset フィールドは、Reporting API v4 の startGroup フィールドと同じように機能します。
Data API v1 の limit フィールドは、Reporting API v4 の maxGroupCount に類似しており、レポート カーディナリティを制限するために使用します。
Data API v1 では、各ピボットの limit パラメータの積が 100,000 を超えない限り、複数のピボットがサポートされます。Reporting API v4 では、1 つのピボット ディメンションのみがサポートされます。
デフォルトでは、Data API v1 はレポートの最初の指標に基づいてピボット内のディメンションを並べ替えます。この動作は、ピボットがリクエストされた指標の「合計」を降順で並べ替える Reporting API v4 の場合とは異なります。 Data API v1 で並べ替え順を指定するには、Pivot 仕様の orderBys フィールドを使用します。
Data API v1 のリクエスト
以下の Data API v1 のピボットクエリでは、国別セッション数のレポートを browser ディメンションでピボット表示できます。Reporting API v4 クエリと類似する動作を再現して、並べ替え設定とページ分け設定を保持するために、以下のクエリで orderBys、limit、offset フィールドをどのように使用しているかにご留意ください。
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runPivotReport
{
"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"
}
]
}
Data API v1 のレスポンス
{
"pivotHeaders": [
{
"pivotDimensionHeaders": [
{
"dimensionValues": [
{
"value": "(not set)"
}
]
},
{
"dimensionValues": [
{
"value": "Albania"
}
]
},
{
"dimensionValues": [
{
"value": "Algeria"
}
]
}
],
"rowCount": 234
},
{
"pivotDimensionHeaders": [
{
"dimensionValues": [
{
"value": "Safari"
}
]
},
{
"dimensionValues": [
{
"value": "Edge"
}
]
},
{
"dimensionValues": [
{
"value": "Opera"
}
]
}
],
"rowCount": 124
}
],
"dimensionHeaders": [
{
"name": "country"
},
{
"name": "browser"
}
],
"metricHeaders": [
{
"name": "sessions",
"type": "TYPE_INTEGER"
}
],
"rows": [
{
"dimensionValues": [
{
"value": "(not set)"
},
{
"value": "Safari"
}
],
"metricValues": [
{
"value": "2531"
}
]
},
{
"dimensionValues": [
{
"value": "(not set)"
},
{
"value": "Edge"
}
],
"metricValues": [
{
"value": "1701"
}
]
},
{
"dimensionValues": [
{
"value": "(not set)"
},
{
"value": "Opera"
}
],
"metricValues": [
{
"value": "1564"
}
]
},
{
"dimensionValues": [
{
"value": "Albania"
},
{
"value": "Safari"
}
],
"metricValues": [
{
"value": "2531"
}
]
},
{
"dimensionValues": [
{
"value": "Albania"
},
{
"value": "Edge"
}
],
"metricValues": [
{
"value": "1701"
}
]
},
{
"dimensionValues": [
{
"value": "Albania"
},
{
"value": "Opera"
}
],
"metricValues": [
{
"value": "1564"
}
]
},
{
"dimensionValues": [
{
"value": "Algeria"
},
{
"value": "Safari"
}
],
"metricValues": [
{
"value": "237"
}
]
},
{
"dimensionValues": [
{
"value": "Algeria"
},
{
"value": "Edge"
}
],
"metricValues": [
{
"value": "44"
}
]
},
{
"dimensionValues": [
{
"value": "Algeria"
},
{
"value": "Opera"
}
],
"metricValues": [
{
"value": "22"
}
]
},
....
],
....
}
Reporting API v4 のリクエスト
以下の Reporting API v4 のピボットクエリでは、国別セッション数のレポートを ga:browser ディメンションでピボット表示できます。
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"dateRanges": [
{
"startDate": "2021-01-01",
"endDate": "2021-01-30"
}
],
"metrics": [
{
"expression": "ga:sessions"
}
],
"dimensions": [
{
"name": "ga:country"
}
],
"pivots": [
{
"dimensions": [
{
"name": "ga:browser"
}
],
"startGroup": 3,
"maxGroupCount": 3,
"metrics": [
{
"expression": "ga:sessions"
}
]
}
]
}
]
}
Reporting API v4 のレスポンス
{
"reports": [
{
"columnHeader": {
"dimensions": [
"ga:country"
],
"metricHeader": {
"metricHeaderEntries": [
{
"name": "ga:sessions",
"type": "INTEGER"
}
],
"pivotHeaders": [
{
"pivotHeaderEntries": [
{
"dimensionNames": [
"ga:browser"
],
"dimensionValues": [
"Edge"
],
"metric": {
"name": "ga:sessions",
"type": "INTEGER"
}
},
{
"dimensionNames": [
"ga:browser"
],
"dimensionValues": [
"Opera"
],
"metric": {
"name": "ga:sessions",
"type": "INTEGER"
}
},
{
"dimensionNames": [
"ga:browser"
],
"dimensionValues": [
"Samsung Internet"
],
"metric": {
"name": "ga:sessions",
"type": "INTEGER"
}
}
],
"totalPivotGroupsCount": 19
}
]
}
},
"data": {
"rows": [
{
"dimensions": [
"(not set)"
],
"metrics": [
{
"values": [
"781283"
],
"pivotValueRegions": [
{
"values": [
"6923",
"1385",
"66"
]
}
]
}
]
},
{
"dimensions": [
"Albania"
],
"metrics": [
{
"values": [
"42394"
],
"pivotValueRegions": [
{
"values": [
"24658",
"17208",
"132"
]
}
]
}
]
},
{
"dimensions": [
"Algeria"
],
"metrics": [
{
"values": [
"23208"
],
"pivotValueRegions": [
{
"values": [
"19252",
"66",
"1582"
]
}
]
}
]
},
....
],
....
}
}
]
}
コホート
Data API v1 では、CohortSpec 仕様を使用してコホート レポートを設定します。これは、Reporting API v4 の CohortGroup 仕様に似ています。
Data API v1 では現在、利用可能な指標はすべてコホートクエリに対応していますが、Reporting API v4 では特別な指標のサブセットのみコホートクエリに使用できます。
Data API v1 のコホート リクエストでは、指標 cohortActiveUsers は必須です。
Data API v1 と Reporting API v4 のどちらも、1 回のリクエストで最大 12 個のコホートを使用できます。
Data API v1 は現在、ライフタイム バリュー（LTV）指標に対応していません。
コホートの指標の同等値
下記の表で示すように、Reporting API v4 で定義されているコホート指標のほとんどは、式で置き換えて Data API v1 で同等の結果を得ることができます。
| Reporting API v4 の指標名 | Data API v1 の指標名または式 |
|---|---|
| ga:cohortActiveUsers | cohortActiveUsers |
| ga:cohortTotalUsers | cohortTotalUsers |
| ga:cohortRetentionRate | "expression": "cohortActiveUsers/cohortTotalUsers" |
| ga:cohortRevenuePerUser | "expression": "totalRevenue/cohortActiveUsers" |
| ga:cohortVisitDurationPerUser | "expression": "userEngagementDuration/cohortActiveUsers" |
| ga:cohortAppviewsPerUser | "expression": "screenPageViews/cohortActiveUsers" |
| ga:cohortPageviewsPerUser | "expression": "screenPageViews/cohortActiveUsers" |
| ga:cohortSessionsPerUser | "expression": "sessions/cohortActiveUsers" |
| ga:cohortGoalCompletionsPerUser | "expression": "eventCount/cohortActiveUsers"。希望する目標完了イベントに対応する eventName によるディメンション フィルタに加える。 |
Data API v1 のリクエスト
以下は、2021 年 1 月 3 日の週に最初のセッションが発生したユーザーのコホートを設定するサンプルクエリです。コホートのアクティブ ユーザー数とユーザー維持率は、WEEKLY 粒度を使用して 5 週間にわたって計算されます。
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"cohortSpec": {
"cohorts": [
{
"dimension": "firstSessionDate",
"name": "cohort",
"dateRange": {
"startDate": "2021-01-03",
"endDate": "2021-01-09"
}
}
],
"cohortsRange": {
"startOffset": 0,
"endOffset": 4,
"granularity": "WEEKLY"
}
},
"metrics": [
{
"name": "cohortActiveUsers"
},
{
"expression": "cohortActiveUsers/cohortTotalUsers",
"name": "cohortRetentionRate"
}
],
"dimensions": [
{
"name": "cohort"
},
{
"name": "cohortNthWeek"
}
]
}
Data API v1 のレスポンス
{
"dimensionHeaders": [
{
"name": "cohort"
},
{
"name": "cohortNthWeek"
}
],
"metricHeaders": [
{
"name": "cohortActiveUsers",
"type": "TYPE_INTEGER"
},
{
"name": "cohortRetentionRate",
"type": "TYPE_FLOAT"
}
],
"rows": [
{
"dimensionValues": [
{
"value": "cohort"
},
{
"value": "0000"
}
],
"metricValues": [
{
"value": "4268816"
},
{
"value": "0.999913800857494"
}
]
},
{
"dimensionValues": [
{
"value": "cohort"
},
{
"value": "0001"
}
],
"metricValues": [
{
"value": "241580"
},
{
"value": "0.056586926213534013"
}
]
},
{
"dimensionValues": [
{
"value": "cohort"
},
{
"value": "0002"
}
],
"metricValues": [
{
"value": "159390"
},
{
"value": "0.037335003597877253"
}
]
},
{
"dimensionValues": [
{
"value": "cohort"
},
{
"value": "0003"
}
],
"metricValues": [
{
"value": "131512"
},
{
"value": "0.030804950079453122"
}
]
},
{
"dimensionValues": [
{
"value": "cohort"
},
{
"value": "0004"
}
],
"metricValues": [
{
"value": "96793"
},
{
"value": "0.022672482610259947"
}
]
}
],
"totalSize": 5,
"metadata": {}
}
Reporting API v4 のリクエスト
以下は、2021 年 1 月 3 日の週に最初のセッションが発生したユーザーのコホートを設定するサンプルクエリです。コホートのアクティブ ユーザー数とユーザー維持率は、WEEKLY 粒度を使用して 5 週間にわたって計算されます。
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"dimensions": [
{
"name": "ga:cohort"
},
{
"name": "ga:cohortNthWeek"
}
],
"metrics": [
{
"expression": "ga:cohortActiveUsers"
},
{
"expression": "ga:cohortRetentionRate"
}
],
"cohortGroup": {
"cohorts": [
{
"name": "cohort",
"type": "FIRST_VISIT_DATE",
"dateRange": {
"startDate": "2021-01-03",
"endDate": "2021-01-09"
}
}
]
}
}
]
}
Reporting API v4 のレスポンス
{
"reports": [
{
"columnHeader": {
"dimensions": [
"ga:cohort",
"ga:cohortNthWeek"
],
"metricHeader": {
"metricHeaderEntries": [
{
"name": "ga:cohortActiveUsers",
"type": "INTEGER"
},
{
"name": "ga:cohortRetentionRate",
"type": "PERCENT"
}
]
}
},
"data": {
"rows": [
{
"dimensions": [
"cohort",
"0000"
],
"metrics": [
{
"values": [
"40793",
"100.0"
]
}
]
},
{
"dimensions": [
"cohort",
"0001"
],
"metrics": [
{
"values": [
"3883",
"9.518789988478416"
]
}
]
},
{
"dimensions": [
"cohort",
"0002"
],
"metrics": [
{
"values": [
"2165",
"5.307283112298679"
]
}
]
},
{
"dimensions": [
"cohort",
"0003"
],
"metrics": [
{
"values": [
"1703",
"4.174735861544873"
]
}
]
},
{
"dimensions": [
"cohort",
"0004"
],
"metrics": [
{
"values": [
"1484",
"3.637879047875861"
]
}
]
},
{
"dimensions": [
"cohort",
"0005"
],
"metrics": [
{
"values": [
"1103",
"2.7038952761503197"
]
}
]
},
{
"dimensions": [
"cohort",
"0006"
],
"metrics": [
{
"values": [
"933",
"2.28715711028853"
]
}
]
},
{
"dimensions": [
"cohort",
"0007"
],
"metrics": [
{
"values": [
"336",
"0.8236707278209496"
]
}
]
}
],
"totals": [
{
"values": [
"52400",
"16.056676390557204"
]
}
],
"rowCount": 8,
"minimums": [
{
"values": [
"336",
"0.8236707278209496"
]
}
],
"maximums": [
{
"values": [
"40793",
"100.0"
]
}
],
"isDataGolden": true
}
}
]
}
サンプリング
Data API v1 では、基数の上限によってデータ品質が低下することが予想される場合、データ サンプリングが自動的に使用されます。日付範囲の結果をサンプリングする場合、RunReportResponse の metadata には、対応する SamplingMetadata が含まれます。これは、Reporting API v4 に存在していた samplingLevel フィールドと同様です。
データの更新速度
Reporting API v4 でレポートのすべてのヒットの処理が完了したかどうかを示すために使用されていた isDataGolden フィールドに相当するものは、Data API にはありません。追加処理のため後日クエリされた場合も、同じレポートで異なる結果を返すことが可能です。
（サポート対象外）セグメント
Data API v1 では現在、セグメントはサポートされていません。
リアルタイム レポート
Data API v1 の properties.runRealtimeReport メソッドを使用して、Google アナリティクス 4 プロパティのリアルタイム レポートを生成します。ユニバーサル アナリティクス プロパティのリアルタイム レポート機能は、Google Analytics API v3 の data.realtime.get メソッドで提供されていました。
ユニバーサル アナリティクスと Google アナリティクス 4 の概念の違いにより、Data API のリアルタイム レポート作成スキーマはアナリティクス API v3 のリアルタイム レポート作成スキーマとは異なります。
Data API v1 のリクエスト
次のサンプルでは、Google Analytics API v3 のデフォルトの並べ替え動作を維持するため、オプションの orderBy 要素がサンプルの Data API v1 クエリに追加されています。
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runRealtimeReport
{
"dimensions": [{ "name": "country" }],
"metrics": [{ "name": "activeUsers" }],
"orderBys": [
{
"dimension": {
"dimensionName": "country"
}
}
]
}
Data API v1 のレスポンス
{
"dimensionHeaders": [
{
"name": "country"
}
],
"metricHeaders": [
{
"name": "activeUsers",
"type": "TYPE_INTEGER"
}
],
"rows": [
{
"dimensionValues": [
{
"value": ""
}
],
"metricValues": [
{
"value": "199"
}
]
},
{
"dimensionValues": [
{
"value": "Afghanistan"
}
],
"metricValues": [
{
"value": "4"
}
]
},
{
"dimensionValues": [
{
"value": "Albania"
}
],
"metricValues": [
{
"value": "136"
}
]
},
....
],
"rowCount": 172
}
Google Analytics API v3 のリクエスト
GET https://analytics.googleapis.com/analytics/v3/data/realtime?ids=ga:UA_VIEW_ID&metrics=rt:activeUsers&dimensions=rt:country
Google Analytics API v3 のレスポンス
{
"kind": "analytics#realtimeData",
"id": "https://www.googleapis.com/analytics/v3/data/realtime?ids=ga:UA_VIEW_ID&dimensions=rt:country&metrics=rt:activeUsers",
"query": {
"ids": "ga:UA_VIEW_ID",
"dimensions": "rt:country",
"metrics": [
"rt:activeUsers"
],
"max-results": 10
},
"totalResults": 178,
"profileInfo": {
"profileId": "XXXXXX",
"accountId": "XXXXXX",
"webPropertyId": "UA-XXXXXX",
"profileName": "View Name",
},
"columnHeaders": [
{
"name": "rt:country",
"columnType": "DIMENSION",
"dataType": "STRING"
},
{
"name": "rt:activeUsers",
"columnType": "METRIC",
"dataType": "INTEGER"
}
],
"totalsForAllResults": {
"rt:activeUsers": "80351"
},
"rows": [
[
"(not set)",
"97"
],
[
"Afghanistan",
"2"
],
[
"Albania",
"78"
],
....
]
}
（サポート対象外）ユーザー アクティビティ レポート
Data API v1 では現在、Reporting API v4 の userActivity.search メソッドに類似した、個々のユーザー アクティビティのレポートを作成する機能はサポートされていません。
API の割り当ての変更
コア割り当てとリアルタイム割り当てのカテゴリ
割り当ての目的上、Data API にはコアとリアルタイムの 2 つのリクエスト カテゴリがあります。コアレポート作成メソッド（runReport、getMetadata、runPivotReport、batchRunReports、batchRunPivotReports）への API リクエストは、コア割り当てを消費します。runRealtimeReport メソッドに対する API リクエストは、リアルタイム割り当てを消費します。
トークン割り当て
プロジェクトの割り当てに加えて、クエリの複雑さに応じて課金されるプロパティ トークン割り当てが各リクエストにより消費されます。API の割り当てと制限の詳細については、Data API v1 の割り当てに関するドキュメントをご覧ください。
コアまたはリアルタイムのレポート作成リクエストで returnPropertyQuota を true に設定することで、アナリティクスのプロパティのすべての割り当ての現在の状態を取得できます。割り当て状態は PropertyQuota で返されます。
（サポート対象外）リソースベースの割り当て
Google アナリティクス 4 の主要なレポートはすべて非サンプリング データに基づいているため、Reporting API v4 で導入されたリソースベースの割り当ては適用されなくなりました。また、Data API v1 レポート リクエストに存在する useResourceQuotas フィールドに相当するものはありません。
（サポート対象外）1 日のビュー（旧プロファイル）あたりのリクエストに基づく割り当て
Google アナリティクス 4 にはビューがないため、requests per view (profile) per day 割り当ては Data API v1 には存在せず、トークンの割り当てに置き換えられます。