Core Reporting API - リファレンス ガイド

コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

このドキュメントでは、Core Reporting API バージョン 3.0 のすべてのクエリと レスポンスについて説明します。

はじめに

Google アナリティクスのレポートデータをクエリするには、Core Reporting API を使用します。それぞれのクエリには、ビュー ID(旧プロファイル ID)、開始日と終了日、1 つ以上の指標を指定する必要があります。また、クエリをさらに絞り込むために、ディメンション、フィルタ、セグメントなどのクエリ パラメータを追加することもできます。これらの概念がどのように連携するかについては、概要ガイドをご覧ください。

リクエスト

この API には、データをリクエストするためのメソッドが 1 つ用意されています。

analytics.data.ga.get()

このメソッドは、各種のクライアント ライブラリで公開されており、クエリ パラメータを設定するための言語固有のインターフェースを持っています。

この API は、REST 対応のエンドポイントとしてクエリすることもできます。

Authorization: Bearer {oauth2-token}

GET https://www.googleapis.com/analytics/v3/data/ga
  ?ids=ga:12345
  &start-date=2008-10-01
  &end-date=2008-10-31
  &metrics=ga:sessions,ga:bounces

各 URL クエリ パラメータは、API クエリ パラメータを指定します。API クエリ パラメータは、URL エンコードされている必要があります

クエリ パラメータの概要

次の表に、Core Reporting API で使用できるすべてのクエリ パラメータを示します。各パラメータ名をクリックすると、詳しい説明が表示されます。

名前 必須 まとめ
ids string 必須 ga:XXXX という形式の一意のテーブル ID。ここで XXXX は、クエリがデータを取得するアナリティクスのビュー(プロファイル)ID です。
start-date string 必須 アナリティクス データの取得を開始する日付。リクエストでは、開始日を YYYY-MM-DD の形式、または相対的な日付(例:todayyesterday、または NdaysAgoN は正の整数)です。
end-date string 必須 アナリティクス データの取得を終了する日付。リクエストでは、YYYY-MM-DD のような終了日、または相対的な日付(例:todayyesterday、または NdaysAgoN は正の整数)です。
metrics string 必須 カンマ区切りの指標のリスト(ga:sessions,ga:bounces など)。
dimensions string なし アナリティクス データのカンマ区切りディメンションのリスト(例: ga:browser,ga:city)。
sort string なし 返されるデータの並べ替え順と並べ替え方向を示す、ディメンションと指標のカンマ区切りリスト。
filters string なし リクエストに対して返されるデータを制限するディメンション フィルタまたは指標フィルタ。
segment string なし リクエストに対して返されたデータをセグメント化します。
samplingLevel string なし 希望するサンプリング レベル。使用できる値:
  • DEFAULT - 速度と精度のバランスがとれたサンプルサイズで レスポンスが返されます。
  • FASTER - サンプルサイズを小さくすることにより、 高速なレスポンスが返されます。
  • HIGHER_PRECISION - サンプルサイズを大きく することにより、より正確なレスポンスが返されますが、 レスポンス速度が低下する可能性があります。
include-empty-rows boolean なし デフォルトは true です。false に設定すると、すべての指標値がゼロである行はレスポンスから除外されます。
start-index integer なし 取得するデータの最初の行。1 から始まります。このパラメータをページ設定メカニズムとして max-results パラメータとともに使用します。
max-results integer なし レスポンスに含める行の最大数。
output string なし レスポンスで返されるアナリティクス データの望ましい出力タイプ。指定できる値は json および dataTable です。デフォルト: json
fields string なし レスポンスに含めるフィールドのサブセットを指定するセレクタ。
prettyPrint string なし インデントと改行を含むレスポンスを返します。デフォルトは false です。
userIp string なし API 呼び出しが行われるエンドユーザーの IP アドレスを指定します。IP あたりの使用量の上限を設定するために使用されます。
quotaUser string なし ユーザーの IP アドレスが不明な場合に userIp の代わりに使用します。
access_token string なし OAuth 2.0 トークンの送信に使用できる方法の 1 つ。
callback string なし レスポンスを処理する JavaScript コールバック関数の名前。 JavaScript JSON-P リクエストで使用します。
key string なし アプリケーションを指定して割り当て量を取得するために OAuth 1.0a の承認で使用します。例: key=AldefliuhSFADSfasdfasdfASdf

クエリ パラメータの詳細

ids

ids=ga:12345
必須。
アナリティクス データの取得に使用される一意の ID。この ID は、名前空間 ga: とアナリティクスのビュー(プロファイル)ID を連結したものです。ビュー(プロファイル)ID を取得するには、analytics.management.profiles.list メソッドを使用します。このメソッドは、Google Analytics Management API のビュー(プロファイル)リソースに id を提供します。

start-date

start-date=2009-04-20
必須。
アナリティクスのすべてのデータ リクエストでは、期間を指定する必要があります。リクエストに start-date パラメータと end-date パラメータを含めないと、サーバーはエラーを返します。日付値は、YYYY-MM-DD パターンを使用して特定の日付を指定することも、todayyesterday または NdaysAgo パターンを使用して相対値を指定することもできます。値は [0-9]{4}-[0-9]{2}-[0-9]{2}|today|yesterday|[0-9]+(daysAgo) と一致する必要があります。
最も早く有効な start-date2005-01-01 です。開始日に上限はありません。
相対的な日付は、常に現在のクエリからの相対日時で、クエリで指定されたビュー(プロファイル)のタイムゾーンに基づきます。

相対的な日付を使用して(昨日を基準に)過去 7 日間の期間を指定する例を 次に示します。

  &start-date=7daysAgo
  &end-date=yesterday

end-date

end-date=2009-05-20
必須。
アナリティクスのすべてのデータ リクエストでは、期間を指定する必要があります。リクエストに start-date パラメータと end-date パラメータを含めないと、サーバーはエラーを返します。日付値は、YYYY-MM-DD パターンを使用して特定の日付を指定することも、todayyesterday または NdaysAgo パターンを使用して相対値を指定することもできます。値は [0-9]{4}-[0-9]{2}-[0-9]{2}|today|yesterday|[0-9]+(daysAgo) と一致する必要があります。
最も早い有効な end-date2005-01-01 です。end-date に上限はありません。
相対的な日付は、常に現在のクエリからの相対日時で、クエリで指定されたビュー(プロファイル)のタイムゾーンに基づきます。

相対的な日付を使用して(今日を基準に)過去 10 日間の期間を指定する例を 次に示します。

  &start-date=9daysAgo
  &end-date=today

dimensions

dimensions=ga:browser,ga:city
省略可。
dimensions パラメータは、共通の基準(ga:browserga:city など)で指標を分類します。サイトへのページビューの総数をリクエストすることもできますが、ブラウザ別のページビュー数を確認する方が便利な場合もあります。この場合、Firefox、Internet Explorer、Chrome などからのページビュー数が表示されます。

データ リクエストで dimensions を使用する場合は、次の制約に注意してください。

  • クエリで指定できるディメンションは最大 7 個です。
  • ディメンションのみで構成されたクエリを送信することは できません。リクエストするディメンションと少なくとも 1 つの指標を 組み合わせる必要があります。
  • 同じクエリ内で照会できるのは特定のディメンションのみです。使用できる ディメンションの組み合わせを、 ディメンションと指標のリファレンスにある有効な組み合わせ ツールで確認してください。


metrics

metrics=ga:sessions,ga:bounces
必須。
クリック数やページビュー数など、サイトでのユーザー アクションの集計統計情報です。クエリに dimensions パラメータがない場合、返される指標には、リクエストされた期間の合計値(全体的なページビューや合計直帰数など)が示されます。ただし、ディメンションを リクエストした場合、値はディメンション値ごとにセグメント化 されます。たとえば、ga:country とリクエストされた ga:pageviews は、国ごとの合計ページビューを返します。指標をリクエストするときは、次の点に注意してください。
  • どのリクエストでも少なくとも 1 つの指標を指定する必要があります。ディメンションのみで リクエストを構成することはできません。
  • クエリには指標を 10 個まで指定できます。
  • ディメンションを指定していない限り、複数のカテゴリのほとんどの指標を 組み合わせて使用することができます。
  • 指標は、他のディメンションや指標と組み合わせて使用できますが、その指標に適切な組み合わせがある場合に限ります。 詳しくは、ディメンションと指標のリファレンスをご覧ください。


sort

sort=ga:country,ga:browser
省略可。

取得するデータの並べ替え順序と方向を示す指標とディメンションのリストです。

  • 並べ替えの順序は、表示される指標とディメンションの左から右の順に指定されます。
  • 並べ替えの方向はデフォルトで昇順になりますが、降順に変更するには、リクエストされたフィールドでマイナス記号(-)を付加します。

クエリの結果を並べ替えることにより、データをさまざまな角度から見ることができます。たとえば、「おすすめの国は何か」、「どのブラウザを最も使用しているか」という疑問に対処するには、次のパラメータを使用してクエリを実行できます。最初に ga:country で、次に ga:browser で、昇順で並べ替えられます。

sort=ga:country,ga:browser

関連するパラメータ「どのブラウザが最も使用されているのか」、「どの国が最も使用されているか」に答えるには、以下のパラメータを使用してクエリを行います。最初に ga:browser で、次に ga:country で並べ替えられ、どちらも昇順です。
sort=ga:browser,ga:country

sort パラメータを使用するときは、次の点に注意してください。

  • dimensions または metrics パラメータで使用したディメンションまたは指標の値で並べ替えるだけです。dimensions パラメータまたは metrics パラメータで指定されていないフィールドを基に並べ替えるようリクエストすると、エラーが返されます。
  • en-US の言語 / 地域では、デフォルトで、文字列がアルファベットの昇順で並べ替えられます。
  • 数値は、デフォルトで昇順で並べ替えられます。
  • 日付は、デフォルトで昇順で並べ替えられます。

filters

filters=ga:medium%3D%3Dreferral
省略可。

filters クエリ文字列パラメータは、リクエストから返されるデータを制限します。filters パラメータを使用するには、フィルタを適用するディメンションまたは指標を指定し、続けてフィルタ式を指定します。たとえば、次のクエリはビュー(プロファイル)12134ga:pageviewsga:browser をリクエストします。ここで、ga:browser ディメンションは文字列 Firefox で始まります。

https://www.googleapis.com/analytics/v3/data/ga
?ids=ga:12134
&dimensions=ga:browser
&metrics=ga:pageviews
&filters=ga:browser%3D~%5EFirefox
&start-date=2007-01-01
&end-date=2007-12-31

フィルタを適用したクエリでは、結果に含める(または含めない)行が制限されます。結果の各行はフィルタに対してテストされます。フィルタが一致すると行が維持され、一致しないと行が削除されます。

  • URL エンコード: Google API クライアント ライブラリによってフィルタ演算子が自動的にエンコードされます。
  • ディメンションのフィルタ: フィルタはディメンションの集計前に行われるため、返される指標は該当するディメンションの合計を表します。上記の例では、ブラウザが Firefox のページビュー数のみが返されます。
  • 指標のフィルタリング: 指標のフィルタリングは、指標が集計された後に行われます。
  • 有効な組み合わせ: クエリ内のすべてのディメンションまたは指標、およびそのフィルタが有効な組み合わせであれば、クエリに含まれないディメンションまたは指標でフィルタできます。たとえば、特定のブラウザでフィルタを適用した日付付きのページビュー リストをクエリすることができます。詳しくは、ディメンションと指標のリファレンスをご覧ください。

フィルタ構文


1 つのフィルタには次の形式を使用します。

ga:name operator expression

この構文の説明は次のとおりです。

  • name - フィルタを適用するディメンションまたは指標の名前です。たとえば、ga:pageviews はページビュー指標でフィルタします。
  • operator - 使用するフィルタの一致タイプを定義します。演算子はディメンションまたは指標に固有です。
  • expression - 結果に含める値または結果から除外する値を記述します。式には正規表現構文を使用します。

フィルタ演算子


ディメンション用と指標用にそれぞれ 6 つのフィルタ演算子があります。演算子を URL クエリ文字列に含めるには URL エンコードする必要があります。

ヒント: URL エンコードが必要なフィルタを設計するには、Data Feed Query Explorer を使用します。Query Explorer は、文字列と空白を含む URL を自動的にエンコードします。

指標フィルタ
オペレーター 説明 URL エンコード形式
== 次の値と等しい %3D%3D ページ上の時刻がちょうど 10 秒の結果を返します。
filters=ga:timeOnPage%3D%3D10
!= 次と等しくない !%3D ページ上の時間が 10 秒以外の結果を返します。
filters=ga:timeOnPage!%3D10
> 次より大きい %3E ページの表示時間が厳密に 10 秒を超えた結果を返します。
filters=ga:timeOnPage%3E10
< 次より小さい %3C ページ滞在時間が厳密に 10 秒未満の結果を返します。
filters=ga:timeOnPage%3C10
>= 以上 %3E%3D ページ滞在時間が 10 秒以上の結果を返します。
filters=ga:timeOnPage%3E%3D10
<= 以下 %3C%3D ページ滞在時間が 10 秒以下の結果を返します。
filters=ga:timeOnPage%3C%3D10

ディメンション フィルタ
オペレーター 説明 URL エンコード形式
== 完全一致 %3D%3D 市区町村が Irvine である指標を集計します。
filters=ga:city%3D%3DIrvine
!= 一致しない !%3D 市区町村が Irvine 以外の指標を集計します。
filters=ga:city!%3DIrvine
=@ 文字列の一部に一致 %3D@ 都市に York を含む指標を集計します。
filters=ga:city%3D@York
!@ 文字列の一部に一致しない !@ 都市に York が含まれない指標を集計します。
filters=ga:city!@York
=~ 正規表現の一致を含む %3D~ 都市が New で始まる指標指標を集計します。
filters=ga:city%3D~%5ENew.*
(%5E は、パターンを文字列の先頭に固定する ^ 文字からエンコードされた URL です。)
!~ 次の正規表現に一致する場合を除く !~ 市区町村が New で始まっていない指標を集計します。
filters=ga:city!~%5ENew.*

フィルタ式

フィルタ式にはいくつか重要な規則があります。

  • URL 予約文字 - & などの文字は、通常どおり URL エンコードする必要があります。
  • 予約文字 - セミコロンとカンマが式に出現するときに、バックスラッシュをエスケープする必要があります。
    • セミコロン \;
    • カンマ \,
  • 正規表現 - =~!~ 演算子を使用して、フィルタ式で正規表現を使用することもできます。構文は Perl 正規表現に類似しており、次のルールがあります。
    • 最大 128 文字 - 正規表現が 128 文字を超える場合、サーバーから 400 Bad Request ステータス コードが返されます。
    • 大文字と小文字の区別 - 正規表現一致では大文字と小文字は区別されません。

フィルタの組み合わせ

フィルタはブール論理演算の ORAND を使用して組み合わせることができます。これにより、 フィルタ式の 128 文字の制限を事実上拡張できます。

または

OR 演算子はカンマ(,)を使用して定義します。これは、AND 演算子よりも優先されます。同じ式内でディメンションと指標を組み合わせるためには使用できません。

例: (それぞれ URL エンコードする必要があります)

国が米国またはカナダのいずれかである:
ga:country==United%20States,ga:country==Canada

(Windows または Macintosh)オペレーティング システム上の Firefox ユーザー:
ga:browser==Firefox;ga:operatingSystem==Windows,ga:operatingSystem==Macintosh

AND

AND 演算子はセミコロン(;)を使って定義します。先頭に OR 演算子を付けます。この演算子を使用して、同じ式内でディメンションと指標を組み合わせることができます。

例: (それぞれ URL エンコードする必要があります)

国が米国で、ブラウザが Firefox の場合:
ga:country==United%20States;ga:browser==Firefox

国が米国で、言語が 'en&#39 で始まっていない:
ga:country==United%20States;ga:language!~^en.*

オペレーティング システム(Windows または Macintosh)かつ(ブラウザ)Firefox(または Chrome)の場合:
ga:operatingSystem==Windows,ga:operatingSystem==Macintosh;ga:browser==Firefox,ga:browser==Chrome

国が米国で、かつセッションが 5 件を超えている:
ga:country==United%20States;ga:sessions>5



分割

segment=gaid::-10
segment=sessions::condition::ga:medium%3D%3Dreferral
segment=users::condition::ga:browser%3D%3DChrome
省略可。

Core Reporting API でセグメントをリクエストする方法の詳細については、セグメントのデベロッパー ガイドをご覧ください。

セグメントの概念については、セグメント - 機能のリファレンスおよびヘルプセンターのセグメントをご覧ください。

セグメントで使用できるディメンションと指標
すべてのディメンションと指標をセグメントで使用できるわけではありません。セグメントで使用できるディメンションと指標を確認するには、ディメンションと指標のリファレンスをご覧ください。


samplingLevel

samplingLevel=DEFAULT
省略可。
このパラメータを使用して、レポートクエリのサンプリング レベル(結果の計算に使用されるセッション数)を設定します。使用可能な値はウェブ インターフェースと一致し、次の値が含まれます。
  • DEFAULT - 速度と精度のバランスがとれたサンプルサイズでレスポンスが返されます。
  • FASTER - サンプルサイズを小さくすることにより、高速なレスポンスが返されます。
  • HIGHER_PRECISION - サンプルサイズを大きくすることにより、より正確なレスポンスが返されますが、レスポンス速度が低下する可能性があります。
指定しない場合、DEFAULT のサンプリング レベルが使用されます。
クエリに使用されたセッションの割合を計算する方法について詳しくは、サンプリング セクションをご覧ください。

include-empty-rows

include-empty-rows=true
省略可。
デフォルトは true です。false に設定すると、すべての指標値がゼロである行はレスポンスから除外されます。たとえば、クエリに 複数の指標を含めた場合、すべての指標値がゼロの場合 にのみ行が削除されます。これは、有効な行数が期待されるディメンション値の数よりもはるかに少ないと想定されるリクエストを実行する場合に便利です。

start-index

start-index=10
省略可。
指定されていない場合、開始インデックスは 1 です。結果の インデックスは 1 から始まります。つまり、最初の行は行 0 ではなく、行 1 です。0 が 10,000 を超え、10,001 からインデックスが付けられた行を取得する場合は、このパラメータをページ設定メカニズムとして max-results パラメータとともに使用します。

max-results

max-results=100
省略可。
このレスポンスに含める行の最大数。これを start-index と組み合わせて使用すると、要素のサブセットを取得できます。また、このディメンションのみを使用して、先頭から返される要素の数を制限することもできます。max-results を指定しない場合、デフォルトで最大 1, 000 行が返されます。
Analytics Core Reporting API では、リクエストの数に関係なく、リクエストごとに最大 10,000 行が返されます。ディメンション セグメントの数が予想より少ない場合、リクエストしたよりも少ない行数が返されます。たとえば、ga:country で使用できる値は 300 個に満たないため、国のみでセグメント化する場合は、max-results に 300 を超える値を設定しても、300 行を超えるデータを取得することはできません。

出力

output=dataTable
省略可。
このパラメータは、レスポンスで返されるアナリティクス データの出力タイプを設定します。指定できる値は次のとおりです。
  • json - レスポンスのデフォルトの rows プロパティを出力します。このプロパティには JSON オブジェクトが含まれます。
  • dataTable - データテーブル オブジェクトを含むレスポンスの dataTable プロパティを出力します。この Data Table オブジェクトは、Google Charts のビジュアリゼーションで直接使用できます。
指定しない場合、デフォルトの JSON レスポンスが使用されます。

fields

fields=rows,columnHeaders(name,dataType)
省略可。

部分レスポンスで返すフィールドを指定します。API レスポンスでフィールドのサブセットのみを使用する場合は、fields パラメータを使用して、含めるフィールドを指定できます。

fields リクエスト パラメータ値の形式はほぼ XPath の構文に基づいています。サポートされる構文の概要を次に示します。

  • 複数のフィールドを選択するには、カンマ区切りのリストを使用します。
  • a/b を使用して、フィールド a 内にネストされたフィールド b を選択します。a/b/c を使用して、b 内にネストされたフィールド c を選択します。
  • 配列またはオブジェクトの特定のサブフィールド セットをリクエストするには、サブセレクタを使用し、かっこ "( )" 内に式を配置します。
    たとえば、fields=columnHeaders(name,dataType)columnHeaders 配列の name フィールドと dataType フィールドのみを返します。 サブフィールドは 1 つだけでもかまいません。たとえば、fields=columnHeader(name) と指定するのと fields=columnHeader/name と指定するのは同じことです。

prettyPrint

prettyPrint=false
省略可。

true の場合、人が読める形式でレスポンスを返します。デフォルト値: false


quotaUser

quotaUser=4kh4r2h4
省略可。

ユーザーの IP アドレスが不明な場合でも、サーバーサイド アプリケーションからユーザー 1 人あたりの割り当て量を適用できます。これはたとえば、アプリケーションがユーザーに代わって App Engine で cron ジョブを実行する場合に使用します。ユーザーを一意に識別する任意の文字列を選択できますが、上限は 40 文字です。

両方が指定されている場合、これは userIp をオーバーライドします。


レスポンス

正常終了すると、このリクエストは、次のように定義される JSON 構造を持つレスポンスの本文を返します。出力パラメータが dataTable に設定されている場合、リクエストは、以下に定義されている JSON(データテーブル)構造を持つレスポンスの本文を返します。

: 「結果」という用語は、クエリに一致する行セット全体を表します。「レスポンス」という用語は、結果の現在のページで返される行のセットを表します。結果の合計が現在のレスポンスのページサイズより大きい場合は、これらの数値が異なることがあります(itemsPerPage をご覧ください)。

JSON
{
  "kind": "analytics#gaData",
  "id": string,
  "selfLink": string,
  "containsSampledData": boolean,
  "query": {
    "start-date": string,
    "end-date": string,
    "ids": string,
    "dimensions": [
      string
    ],
    "metrics": [
      string
    ],
    "include-empty-rows": boolean
    "samplingLevel": string,
    "sort": [
      string
    ],
    "filters": string,
    "segment": string,
    "start-index": integer,
    "max-results": integer
  },
  "itemsPerPage": integer,
  "totalResults": integer,
  "previousLink": string,
  "nextLink": string,
  "profileInfo": {
    "profileId": string,
    "accountId": string,
    "webPropertyId": string,
    "internalWebPropertyId": string,
    "profileName": string,
    "tableId": string
  },
  "columnHeaders": [
    {
      "name": string,
      "columnType": string,
      "dataType": string
    }
  ],
  "rows": [
    [
      string
    ]
  ],
  "sampleSize": string,
  "sampleSpace": string,
  "totalsForAllResults": [
    {
      metricName: string,
      ...
    }
  ]
}

レスポンスのフィールド

レスポンス本文の構造のプロパティは次のように定義されています。

プロパティ名 説明
kind string リソースのタイプ。値は "analytics#gaData" です。
id string このデータ レスポンスの ID。
query object このオブジェクトは、パラメータとしてクエリに渡されるすべての値を格納します。各フィールドの意味については、対応するクエリ パラメータの説明をご覧ください。
query.start-date string 開始日。
query.end-date string 終了日。
query.ids string 固有の表 ID。
query.dimensions[] list アナリティクス ディメンションのリスト。
query.metrics[] list アナリティクス指標のリスト。
query.samplingLevel string Requested sampling level.
query.include-empty-rows boolean デフォルト値は true です。false に設定すると、すべての指標値が ゼロの行はレスポンスから除外されます。
query.sort[] list データの並べ替えに使用する指標またはディメンションのリスト。
query.filters string 指標フィルタまたはディメンション フィルタのカンマ区切りリスト。
query.segment string アナリティクス セグメント。
query.start-index integer 開始インデックス。
query.max-results integer ページあたりの結果の最大数。
startIndex integer start-index クエリ パラメータで指定された行の開始インデックス。デフォルト値は 1 です。
itemsPerPage integer 実際に返される行の数に関係なく、レスポンスに含めることができる最大行数。max-results クエリ パラメータを指定した場合、itemsPerPage の値は max-results または 10,000 のいずれか小さい方になります。itemsPerPage のデフォルト値は 1,000 です。
totalResults integer クエリ結果の合計行数。レスポンスで返される行数は考慮されません。多数の行が返されるクエリの場合、totalResultsitemsPerPage より大きくできます。大規模なクエリの totalResultsitemsPerPage の詳細については、ページングをご覧ください。
startDate string start-date パラメータで指定されたデータクエリの開始日。
endDate string end-date パラメータで指定されたデータクエリの終了日。
profileInfo object データがリクエストされたビューに関する情報。ビューデータは、Google アナリティクス Management API を使用して入手できます。
profileInfo.profileId string ビュー ID (1174 など)。
profileInfo.accountId string このビュー(旧プロファイル)が属しているアカウント ID (30481 など)。
profileInfo.webPropertyId string このビュー(ウェブ プロファイル)が属するウェブ プロパティ ID(例: UA-30481-1)。
profileInfo.internalWebPropertyId string このビュー(旧プロファイル)が属するウェブ プロパティの内部 ID(UA-30481-1 など)。
profileInfo.profileName string ビュー(旧プロファイル)の名前。
profileInfo.tableId string ビューの表 ID。"ga:" の後にビュー ID を続ける形で構成されます。
containsSampledData boolean レスポンスにサンプルデータが含まれる場合は True。
sampleSize string サンプルデータの計算に使用されたサンプルの数。
sampleSpace string 合計サンプリング スペース サイズ。これは、サンプルが選択された使用可能なサンプル スペース サイズの合計を示します。
columnHeaders[] list 列ヘッダー。ディメンション名に続けて指標名が一覧表示されます。ディメンションと指標の順序は、metrics パラメータと dimensions パラメータを介してリクエストで指定された順序と同じです。ヘッダーの数は、ディメンションの数と指標の数を合計した数になります。
columnHeaders[].name string ディメンションまたは指標の名前。
columnHeaders[].columnType string 列のタイプ。値は "DIMENSION" か "METRIC" です。
columnHeaders[].dataType string データタイプ。ディメンションの列ヘッダーのデータタイプは、STRING のみです。指標の列ヘッダーには、INTEGERPERCENTTIMECURRENCYFLOAT などの指標の値のデータ型があります。使用可能なすべてのデータ型については、メタデータ API レスポンスをご覧ください。
totalsForAllResults object 指標の名前と値の Key-Value ペアとしての、リクエストした指標の合計値。指標の合計が表示される順序は、リクエストで指定された指標の順序と同じです。
rows[] list アナリティクスのデータ行。各行にはディメンション値とそれに続いて指標値が記載されたリストが含まれます。ディメンションと指標の順序は、リクエストで指定されている順序と同じです。各行に N 個のフィールドのリストがあります。N はディメンションの数 + 指標の数を表します。
JSON(データテーブル)
{
  "kind": "analytics#gaData",
  "id": string,
  "selfLink": string,
  "containsSampledData": boolean,
  "query": {
    "start-date": string,
    "end-date": string,
    "ids": string,
    "dimensions": [
      string
    ],
    "metrics": [
      string
    ],
    "samplingLevel": string,
    "include-empty-rows": boolean,
    "sort": [
      string
    ],
    "filters": string,
    "segment": string,
    "start-index": integer,
    "max-results": integer
  },
  "itemsPerPage": integer,
  "totalResults": integer,
  "previousLink": string,
  "nextLink": string,
  "profileInfo": {
    "profileId": string,
    "accountId": string,
    "webPropertyId": string,
    "internalWebPropertyId": string,
    "profileName": string,
    "tableId": string
  },
  "columnHeaders": [
    {
      "name": string,
      "columnType": string,
      "dataType": string
    }
  ],
  "dataTable": {
    "cols": [
      {
        "id": string,
        "label": string,
        "type": string
      }
    ],
    "rows": [
      {
        "c": [
          {    
            "v": string
          }
        ]
      }   
    ]
  },
  "sampleSize": string,
  "sampleSpace": string,
  "totalsForAllResults": [
    {
      metricName: string,
      ...
    }
  ]
}

レスポンスのフィールド

レスポンス本文の構造のプロパティは次のように定義されています。

プロパティ名 説明
kind string リソースのタイプ。値は "analytics#gaData" です。
id string このデータ レスポンスの ID。
query object このオブジェクトは、パラメータとしてクエリに渡されるすべての値を格納します。各フィールドの意味については、対応するクエリ パラメータの説明をご覧ください。
query.start-date string 開始日。
query.end-date string 終了日。
query.ids string 固有の表 ID。
query.dimensions[] list アナリティクス ディメンションのリスト。
query.metrics[] list アナリティクス指標のリスト。
query.samplingLevel string Requested sampling level.
query.include-empty-rows boolean デフォルト値は true です。false に設定すると、すべての指標値が ゼロの行はレスポンスから除外されます。
query.sort[] list データの並べ替えに使用する指標またはディメンションのリスト。
query.filters string 指標フィルタまたはディメンション フィルタのカンマ区切りリスト。
query.segment string アナリティクス セグメント。
query.start-index integer 開始インデックス。
query.max-results integer ページあたりの結果の最大数。
startIndex integer start-index クエリ パラメータで指定された行の開始インデックス。デフォルト値は 1 です。
itemsPerPage integer 実際に返される行の数に関係なく、レスポンスに含めることができる最大行数。max-results クエリ パラメータを指定した場合、itemsPerPage の値は max-results または 10,000 のいずれか小さい方になります。itemsPerPage のデフォルト値は 1,000 です。
totalResults integer クエリ結果の合計行数。レスポンスで返される行数は考慮されません。多数の行が返されるクエリの場合、totalResultsitemsPerPage より大きくできます。大規模なクエリの totalResultsitemsPerPage の詳細については、ページングをご覧ください。
startDate string start-date パラメータで指定されたデータクエリの開始日。
endDate string end-date パラメータで指定されたデータクエリの終了日。
profileInfo object データがリクエストされたビューに関する情報。ビューデータは、Google アナリティクス Management API を使用して入手できます。
profileInfo.profileId string ビュー ID (1174 など)。
profileInfo.accountId string このビュー(旧プロファイル)が属しているアカウント ID (30481 など)。
profileInfo.webPropertyId string このビュー(ウェブ プロファイル)が属するウェブ プロパティ ID(例: UA-30481-1)。
profileInfo.internalWebPropertyId string このビュー(旧プロファイル)が属するウェブ プロパティの内部 ID(UA-30481-1 など)。
profileInfo.profileName string ビュー(旧プロファイル)の名前。
profileInfo.tableId string ビューの表 ID。"ga:" の後にビュー ID を続ける形で構成されます。
containsSampledData boolean レスポンスにサンプルデータが含まれる場合は True。
sampleSize string サンプルデータの計算に使用されたサンプルの数。
sampleSpace string 合計サンプリング スペース サイズ。これは、サンプルが選択された使用可能なサンプル スペース サイズの合計を示します。
columnHeaders[] list 列ヘッダー。ディメンション名に続けて指標名が一覧表示されます。ディメンションと指標の順序は、metrics パラメータと dimensions パラメータを介してリクエストで指定された順序と同じです。ヘッダーの数は、ディメンションの数と指標の数を合計した数になります。
columnHeaders[].name string ディメンションまたは指標の名前。
columnHeaders[].columnType string 列のタイプ。値は "DIMENSION" か "METRIC" です。
columnHeaders[].dataType string データタイプ。ディメンションの列ヘッダーのデータタイプは、STRING のみです。指標の列ヘッダーには、INTEGERPERCENTTIMECURRENCYFLOAT などの指標の値のデータ型があります。使用可能なすべてのデータ型については、メタデータ API レスポンスをご覧ください。
totalsForAllResults object 指標の名前と値の Key-Value ペアとしての、リクエストした指標の合計値。指標の合計が表示される順序は、リクエストで指定された指標の順序と同じです。
dataTable object Google グラフ で使用できる Data Table オブジェクト。
dataTable.cols[] list ディメンションとそれに続く指標の列記述子のリスト。ディメンションと指標の順序は、リクエスト内で metrics パラメータと dimensions パラメータで指定された順序と同じです。列の数は、ディメンションの数と指標の数を合計した数になります。
dataTable.cols[].id string ID。(列インデックスを使用する代わりに)特定の列を参照するために使用できます。ディメンション ID または指標 ID を使用してこの値を設定します。
dataTable.cols[].label string 列のラベル(ビジュアリゼーションによって表示される場合があります)。ディメンションまたは指標の ID を使用して、この値が設定されます。
dataTable.cols[].type string この列のデータタイプ。
dataTable.rows[] list データ表形式のアナリティクスのデータ行。各行は、ディメンションとそれに続いて指標のセル値のリストを含むオブジェクトです。ディメンションと指標の順序は、リクエストで指定されている順序と同じです。各セルには N 個のフィールドのリストが含まれます。N = ディメンション数 + 指標数。

エラーコード

Core Reporting API は、リクエストが正常に処理されると 200 HTTP ステータス コードを返します。クエリの処理中にエラーが発生した場合、API はエラーコードと説明を返します。Analytics API を使用する各アプリケーションは、適切なエラー処理ロジックを実装する必要があります。エラーコードとその処理方法について詳しくは、エラー レスポンス リファレンス ガイドをご覧ください。

試してみる

Core Reporting API に対するクエリを試すことができます。

  • クエリの指標とディメンションの有効な組み合わせを確認するには、Query Explorer にパラメータのサンプル値を入力します。サンプルクエリの結果は、指定されたすべての指標とディメンションの値を示すテーブルとして表示されます。

  • ライブデータに対するリクエストを行い、JSON 形式のレスポンスを確認するには、Google Data API Exploreranalytics.data.ga.get メソッドをお試しください。

サンプリング

Google アナリティクスでは、ディメンションと指標の特定の組み合わせがその場で計算されます。妥当な時間内にデータを返すために、Google アナリティクスではデータのサンプルのみを処理する場合があります。

リクエストに使用するサンプリング レベルを指定するには、sampleLevel パラメータを設定します。

Core Reporting API のレスポンスにサンプリング データが含まれている場合、containsSampledData レスポンス フィールドは true になります。 さらに、sampleSizesampleSpace の 2 つのプロパティを使用して、クエリのサンプリング レベルに関する情報を取得できます。これら 2 つの値を使用して、クエリに使用されたセッションの割合を計算できます。たとえば、sampleSize201,000sampleSpace220,000 の場合、レポートは(201,000 ÷ 220,000)× 100 = セッションの 91.36% に基づくようになります。

サンプリングに関する一般的な説明と、Google アナリティクスでの使用方法の詳細については、サンプリングをご覧ください。


大量のデータ結果の処理

クエリが大容量の結果セットを返すことが予想される場合は、次のガイドラインに沿って、API クエリの最適化、エラーの回避、割り当ての超過を最小限に抑えてください。1 つの API リクエストで最大 7 個のディメンションと指標と 10 個の指標を許可することで、パフォーマンス ベースラインを設定しています。 多数の指標とディメンションを指定するクエリの中には、他の指標よりも処理に時間がかかるものがありますが、リクエストされた指標の数を制限するだけではクエリのパフォーマンスを向上させることはできません。 代わりに、次の方法を使用して最善のパフォーマンスを得ることができます。

クエリあたりのディメンション数の削減

API では、1 回のリクエストで最大 7 個までディメンションを指定できます。多くの場合、Google アナリティクスはこのような複雑なクエリの結果をすぐに計算する必要があります。結果の行数が大きい場合は、特に時間がかかることがあります。たとえば、都市ごとにキーワードでクエリを実行すると、数百万行のデータに一致する場合があります。クエリのディメンションの数を制限して Google アナリティクスで処理する必要がある行数を減らすことにより、クエリの性能を改善することができます。

期間によるクエリの分割

1 つの長い期間の日付付きの結果を改ページする代わりに、1 週間または 1 日ごとにクエリを分けることを検討してください。もちろん、大規模なデータセットの場合、1 日のデータに対するリクエストでも max-results を超えることがあります。この場合、ページングを避けることはできません。ただし、いずれの場合も、クエリに一致する行数が max-results よりも多い場合、期間を分割すると、結果を取得する合計時間が短縮される可能性があります。この方法により、単一スレッドのクエリと並列クエリの両方においてクエリの性能を改善することができます。

改ページ

結果を改ページすることで、大量の結果を管理しやすいセグメントに分割することができます。totalResults フィールドは、一致する行の数を示し、itemsPerPage は、結果で返されることができる最大行数を表します。totalResultsitemsPerPage の割合が高い場合、個々のクエリに必要以上に時間がかかる可能性があります。表示目的などのために限られた数の行のみが必要な場合は、max-results パラメータを使用してレスポンス サイズに明示的な上限を設定すると便利です。ただし、アプリケーションで大きな結果セット全体を処理する必要がある場合は、許可された最大行数をリクエストする方が効率的です。

gzip の使用

gzip 圧縮を有効にすると、各リクエストが消費する帯域幅を手早く低減できます。これには、結果を圧縮解除するために追加の CPU 時間が必要ですが、ネットワークのコストを大きく削減できます。gzip でエンコードされたレスポンスを受け取るには、2 つの準備作業が必要です。1 つは、Accept-Encoding ヘッダーを設定すること、もう 1 つは、ユーザー エージェントに gzip という文字列を追加することです。 以下に、gzip 圧縮を有効にするための正しい形式の HTTP ヘッダーの例を示します。

Accept-Encoding: gzip
User-Agent: my program (gzip)