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(旧プロファイル ID)です。
start-date string はい アナリティクス データの取得を開始する日付。開始日には、YYYY-MM-DD 形式の日付を指定することも、todayyesterdayNdaysAgoN は正の整数)などの相対的な日付を指定することもできます。
end-date string はい アナリティクス データの取得を終了する日付。 終了日には、YYYY-MM-DD 形式の日付を指定することも、todayyesterdayNdaysAgoN は正の整数)などの相対的な日付を指定することもできます。
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 いいえ レスポンスで返されるアナリティクス データの希望の出力タイプ。 有効な値は jsondataTable です。デフォルト値は 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 アナリティクス Management API のビューリソースの id が提供されます。

start-date

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

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

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

end-date

end-date=2009-05-20
必須。
すべてのアナリティクス データ リクエストでは、期間を指定する必要があります。 start-date パラメータと end-date パラメータをリクエストに含めない場合、 サーバーからエラーが返されます。日付値は、YYYY-MM-DD のパターンを使用して特定の日付を表すことも、 todayyesterdayNdaysAgo パターン を使用して相対的な日付を表すこともできます。 値は [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:countryga:browser の順に、データを昇順で並べ替えます。

sort=ga:country,ga:browser

さらに、「最上位のブラウザは何か、どの国でそのブラウザが最も使用されているか」という同様の質問への回答を得るには、次のパラメータを使用してクエリを作成できます。このクエリでは、ga:countryga:browser の順に、データを昇順で並べ替えます。
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 のページビュー数のみが返されます。
  • 指標のフィルタ: 指標のフィルタは指標の集計後に行われます。
  • 有効な組み合わせ: リクエスト内のすべてのディメンションや指標とフィルタが有効な組み合わせである限り、クエリに含まれないディメンションまたは指標をフィルタすることができます。たとえば、特定のブラウザでフィルタを適用した日付付きのページビュー リストをクエリすることができます。詳細については、ディメンションと指標のリファレンスをご覧ください。

フィルタ構文


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

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

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

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

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

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

AND

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

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

国が米国で、かつ(AND)ブラウザが Firefox:
ga:country==United%20States;ga:browser==Firefox

国が米国で、かつ(AND)言語コードの先頭が「en」以外:
ga:country==United%20States;ga:language!~^en.*

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

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



segment

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 になります。 totalResults が 10,000 を超えるときに 10,001 以降のインデックスに 登録された行を取得したい場合は、max-results パラメータとともに、このパラメータを改ページ メカニズム として使用します。

max-results

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

output

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

Fields

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

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

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

  • 複数のフィールドを選択する場合は、カンマ区切りのリストを使用する。
  • フィールド a 内にネストされたフィールド b を選択するには a/b を使用し、フィールド b 内にネストされたフィールド c を選択するには a/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 も指定されている場合は userIp より優先されます。


レスポンス

正常終了すると、このリクエストは、次のように定義される JSON 構造を持つレスポンスの本文を返します。output パラメータが 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 といった指標の値に対応するデータタイプがあります。すべてのデータタイプについては、Metadata 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 といった指標の値に対応するデータタイプがあります。すべてのデータタイプについては、Metadata 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 または指標 ID を使用してこの値を設定します。
dataTable.cols[].type string この列のデータタイプ。
dataTable.rows[] list データ表形式のアナリティクスのデータ行。各行は、ディメンションとそれに続いて指標のセル値のリストを含むオブジェクトです。ディメンションと指標の順序は、リクエストで指定された順序と同じです。それぞれのセルには、N 個のフィールドのリストが含まれます。ここで、N はディメンションと指標を合計した数です。

エラーコード

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

試してみる

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

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

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

サンプリング

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

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

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

サンプリングの一般的な説明と、Google アナリティクスでの使用方法については、サンプリングを参照してください。


大量のデータ結果の処理

クエリから大量の結果が返されることが予想される場合、以下のガイドラインに従うことで、API クエリを最適化し、エラーを避け、割り当ての超過を最低限に抑えることができます。Google アナリティクスでは、1 つの API リクエストに最大 7 個のディメンションと 10 個の指標を許可することで、一定の成果を確保している点に注意してください。多数の指標とディメンションを指定したクエリは、他のクエリよりも処理に時間がかかる場合もありますが、リクエストする指標の数を制限すればクエリの性能が改善されるとは限りません。代わりに、次の手法を使用して、最適な結果を得ることができます。

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

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

期間によるクエリの分割

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

改ページ

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

gzip の使用

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

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