レポートの作成

こちらはアナリティクス 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 つ以上の 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"]
            }
          ]
        }
      ]
    }
  ]
}

並べ替え

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

  • 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 フィールドを使用して、複数のページにまたがるレスポンス結果のページ設定を行います。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 の高度な機能を確認してください。