こちらはアナリティクス Reporting API v4 のデベロッパー ガイドです。API の詳細な リファレンスについては、API リファレンスをご覧ください。
レポート
アナリティクス Reporting API v4 には、レポート リソースにアクセスするための batchGet メソッドが用意されています。以降のセクションでは、batchGet のリクエスト本文の構造と、batchGet からのレスポンス本文の構造について説明します。
リクエストの本文
アナリティクス Reporting API v4 を使用してデータをリクエストするには、ReportRequest オブジェクトを 作成する必要があります。 このオブジェクトには、次に示す最低必要条件があります。
- viewId フィールドの有効なビュー ID。
- dateRanges フィールドの 1 つ以上の有効なエントリ。
- metrics フィールドの 1 つ以上の有効なエントリ。
ビュー ID を確認するには、アカウントの概要メソッドをクエリするか、Account Explorer を使用します。期間を指定しない場合、デフォルトの期間は {"startDate": "7daysAgo", "endDate": "yesterday"} になります。
最低限必要なフィールドを含むリクエストの例を次に示します。
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dateRanges": [{"startDate": "2014-11-01", "endDate": "2014-11-30"}],
"metrics": [{"expression": "ga:users"}]
}
]
}
batchGet メソッドは、最大 5 つの ReportRequest オブジェクトを受け入れます。リクエストはすべて同じ dateRange、viewId、segments、samplingLevel、cohortGroup を持つ必要があります。
レスポンスの本文
API リクエストのレスポンス本文は、Report オブジェクトの配列です。レポートの構造は ColumnHeader オブジェクトで定義されます。このオブジェクトは、レポートのディメンションと指標、およびそのデータ型を記述します。ディメンションと指標の値は、data フィールドで指定されています。
上記のリクエストの例に対するレスポンスの例を次に示します。
{
"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"
]
}
]
}
}
]
}
指標
指標は、定量的測定値です。すべてのリクエストには、1 つ以上の Metric オブジェクトが必要です。
次の例では、Sessions 指標を batchGet メソッドに渡して、指定した期間内のセッションの合計数を取得しています。
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dateRanges": [{"startDate": "2014-11-01", "endDate": "2014-11-30"}],
"metrics": [{"expression": "ga:sessions"}]
}
]
}
使用可能なディメンションと指標のリストを取得するには、ディメンションと指標のリファレンスまたは Metadata API を使用します。
フィルタリング
batchGet リクエストを送信するときに、特定の条件を満たす指標のみを返すようにリクエストできます。指標をフィルタリングするには、リクエスト本文で 1 つ以上の MetricFilterClauses を指定し、各 MetricFilterClause で 1 つ以上の MetricFilters を定義します。各 MetricFilter で、次の値を指定します。
metricNamenotoperatorcomparisonValue
{metricName} は指標、{operator} は operator、{comparisonValue} は comparisonValue を表します。フィルタは次のように記述します。
if {metricName} {operator} {comparisonValue}
return the metric
not に true を指定すると、フィルタは次のように機能します。
if {metricName} {operator} {comparisonValue}
do not return the metric
次の例では、batchGet は値が 2 より大きいページビューのみを返します。
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"
}]
}]
}]
}
式
指標式は、既存の指標に対して定義する数式です。動的な計算指標のように機能します。指標式を表すエイリアスを定義できます。次に例を示します。
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"metrics":
[
{
"expression": "ga:goal1completions/ga:users",
"alias": "completions per user"
}
]
}
]
}
並べ替え
指標の値で結果を並べ替えるには:
次の例では、batchGet は最初にセッション数、次にページビューで並べ替えられた指標を降順で返します。
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"}
]
}
]
}
ディメンション
ディメンションは、ユーザー、セッション、アクションの特性を表します。
たとえば「都市」ディメンションは、セッションの特性を表し、各セッションの起点となった都市（「パリ」や「ニューヨーク」）を示します。batchGet リクエストでは、0 個以上のディメンション オブジェクトを指定できます。次に例を示します。
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"}
]
}
]
}
フィルタリング
batchGet リクエストを送信するときに、特定の条件を満たすディメンションのみを返すようにリクエストできます。ディメンションをフィルタするには、リクエストの本文で 1 つ以上の DimensionsFilterClauses を指定し、各 DimensionsFilterClause で 1 つ以上の DimensionsFilters を定義します。各 DimensionsFilters で、次の値を指定します。
dimensionNamenotoperatorexpressionscaseSensitive
{dimensionName} をディメンション、{operator} を operator、{expressions} を expressions とします。フィルタは次のように記述します。
if {dimensionName} {operator} {expressions}
return the dimension
not に true を指定すると、フィルタは次のように機能します。
if {dimensionName} {operator} {expressions}
do not return the dimension
次の例では、batchGet は Chrome ブラウザでのページビューとセッションを返します。
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"]
}
]
}
]
}
]
}
並べ替え
ディメンションの値で結果を並べ替えるには、次の手順を実行します。
たとえば、次の batchGet は、国、次にブラウザで並べ替えられたディメンションを返します。
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"}
]
}
]
}
ヒストグラム バケット
値が整数のディメンションの場合は、それらの値をバケットで複数の範囲に分けると、特性を理解しやすくなります。histogramBuckets フィールドを使用して結果のバケットの範囲を定義し、注文タイプとして HISTOGRAM_BUCKET を指定します。次に例を示します。
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"
}
]
}
]
}
複数の期間
Google アナリティクス Reporting API v4 では、1 回のリクエストで複数の期間のデータを取得できます。リクエストで指定した期間が 1 つでも 2 つでも、データは dateRangeValue オブジェクトで返されます。次に例を示します。
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"}]
}
]
}
差分並べ替え
2 つの期間の指標値をリクエストする際に、その期間の指標値の差で結果を並べ替えることができます。次に例を示します。
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"
}
]
}
]
}
日付ディメンションの動作
日付または時刻に関連するディメンションをリクエストした場合、DateRangeValue オブジェクトは、それぞれの範囲内にある日付の値のみを保持します。指定された期間外の値はすべて 0 になります。
たとえば、1 月と 2 月という 2 つの期間で ga:date ディメンションと ga:sessions 指標をリクエストした場合、1 月にリクエストされたデータに対するレスポンスでは、2 月の値は 0 になります。2 月にリクエストされたデータに対するレスポンスでは、1 月の値は 0 になります。
1 月のレポート
{
"dimensions": [
"20140101" # `ga:date` dimension value for January 1, 2014.
],
"metrics": [
{
"values": [ # January DateRangeValue.
"8"
]
},
{
"values": [ # February DateRangeValue.
"0"
]
}
]
},
...
2 月のレポート
{
"dimensions": [
"20140201" # `ga:date` dimension value for February 1, 2014.
],
"metrics": [
{
"values": [ # January DateRangeValue.
"0"
]
},
{
"values": [ # February DateRangeValue.
"7"
]
}
]
},
...
セグメント
アナリティクス データのサブセットをリクエストするには、セグメントを使用します。たとえば、特定の国や都市のユーザーを 1 つのセグメントに定義し、サイトの特定の部分にアクセスするユーザーを別のセグメントに定義できます。フィルタでは、条件を満たす行のみが返されるのに対して、セグメントでは、 そのセグメントが含まれた条件を満たすユーザー、セッション、または イベントのサブセットを返します。
セグメントを使用してリクエストを行うときは、次のことを確認してください。
batchGetメソッド内のすべての ReportRequest には、同一のセグメント定義が含まれている必要があります。- ディメンションのリストに
ga:segmentを追加します。
次に例を示します。
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"]
}
}]
}]
}
}]
}
}
}]
}]
}
セグメントに対するリクエストの例について詳しくは、サンプルを参照してください。
セグメント ID
セグメントをリクエストするには、segmentId フィールドを使用します。segmentId と dynamicSegment の両方を使用してセグメントをリクエストすることはできません。
次に例を示します。
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"}]
}
]
}
サンプリング
サンプリングは、データの結果に影響を与える場合があり、API から返された値が管理画面に一致しない一般的な原因となります。samplingLevel フィールドを使用して、目的のサンプルサイズを設定します。
- サンプリングサイズを小さくしてレスポンスを高速にするには、値を
SMALLに設定します。 - レスポンスを低速にして精度を高めるには、値を
LARGEに設定します。 - 速度と精度のバランスが取れたレスポンスを得るには、値を
DEFAULTに設定します。
次に例を示します。
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dimensions": [{"name": "ga:medium"}],
"metrics": [{"expression": "ga:sessions"}],
"samplingLevel": "LARGE"
}
]
}
レポートにサンプリング データが含まれている場合、アナリティクス Reporting API v4 は samplesReadCounts フィールドと samplingSpaceSizes フィールドを返します。結果がサンプリングされない場合、これらのフィールドは定義されません。
2 つの期間が指定されたリクエストからのサンプルデータを含むレスポンスの例を 次に示します。この結果は、約 1,500 万セッションのサンプリング スペース サイズの ほぼ 500,000 件のサンプルから計算されました。
{
"reports":
[
{
"columnHeader": {
...
},
"data": {
...
"samplesReadCounts": [ "499630","499630"],
"samplingSpaceSizes": ["15328013","15328013"],
}
}
]
}
ページネーション
アナリティクス Reporting API v4 では、pageToken フィールドと pageSize フィールドを使用して、複数のページにまたがるレスポンス結果をページ分けします。reports.batchGet リクエストに対するレスポンスの nextPageToken パラメータから pageToken を取得します。
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
...
# Taken from `nextPageToken` of a previous response.
"pageToken": "10000",
"pageSize": "10000",
}]
}
次のステップ
レポート作成の基礎を学んだところで、次は API v4 の高度な機能を確認してください。