レポートの作成

こちらはアナリティクス 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 オブジェクトを 受け入れます。すべてのリクエストに同じ dateRangeviewIdsegmentssamplingLevelcohortGroup が含まれている必要があります。

レスポンス本文

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 で次の値を指定します。

  • 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"]
            }
          ]
        }
      ]
    }
  ]
}

並べ替え

ディメンションの値で結果を並べ替えるには、次の手順を実行します。

  • fieldName フィールドを使用して、その名前を指定します。
  • sortOrder フィールドを使用して、並べ替え順(ASCENDING または DESCENDING)を指定します。

たとえば、次の 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 フィールドを使用します。 セグメントをリクエストするときに segmentIddynamicSegment の両方を使用することはできません。

例:

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 の高度な機能を 確認してください。