こちらはアナリティクス 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 つ以上の MetricFilterClause を指定し、各 MetricFilterClause
で 1 つ以上の MetricFilters を定義します。
各 MetricFilter
で次の値を指定します。
metricName
not
operator
comparisonValue
{metricName}
で metric を、{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"
}
]
}
]
}
並べ替え
指標の値で結果を並べ替えるには:
fieldName
フィールドを使用して、その名前またはエイリアスを指定します。sortOrder
フィールドを使用して、並べ替え順(ASCENDING
またはDESCENDING
)を指定します。
次の例では、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 個以上の dimension オブジェクトを指定できます。例を次に示します。
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 つ以上の DimensionsFilterClause を指定し、各 DimensionsFilterClause
で 1 つ以上の DimensionsFilter を定義します。
各 DimensionsFilters
で次の値を指定します。
dimensionName
not
operator
expressions
caseSensitive
{dimensionName}
で dimension を、{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"
]
}
]
},
...
セグメント
アナリティクス データのサブセットをリクエストするには、セグメント を使用します。 たとえば、特定の国や市区町村のユーザーをあるセグメントに定義し、 サイトの特定の部分にアクセスしたユーザーを別のセグメントに 定義できます。フィルタでは、条件を満たす行のみが返されるのに対して、セグメントでは、 そのセグメントが含まれた条件を満たすユーザー、セッション、または イベントのサブセットを返します。
セグメントを使用してリクエストを行うときは、次のことを確認してください。
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
フィールドを使用して、複数のページにまたがるレスポンス結果のページ設定を行います。pageToken
は、reports.batchGet
リクエストに対するレスポンスの nextPageToken
パラメータから取得します。
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
...
# Taken from `nextPageToken` of a previous response.
"pageToken": "10000",
"pageSize": "10000",
}]
}
次のステップ
レポート作成の基礎を学んだところで、次は API v4 の高度な機能を確認してください。