このドキュメントでは、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 形式の日付を指定することも、today 、yesterday 、NdaysAgo (N は正の整数)などの相対的な日付を指定することもできます。
|
end-date |
string |
はい |
アナリティクス データの取得を終了する日付。 終了日には、YYYY-MM-DD 形式の日付を指定することも、today 、yesterday 、NdaysAgo (N は正の整数)などの相対的な日付を指定することもできます。
|
metrics |
string |
はい | ga:sessions,ga:bounces など、カンマ区切りの指標のリスト。
|
dimensions |
string |
いいえ | ga:browser,ga:city など、アナリティクス データのカンマ区切りのディメンションのリスト。
|
sort |
string |
いいえ | 取得するデータの並べ替え順序と方向を示す、カンマ区切りのディメンションと指標のリスト。 |
filters |
string |
いいえ | リクエストに対して返されるデータを制限するディメンションまたは指標フィルタ。 |
segment |
string |
いいえ | リクエストに対して返されるデータをセグメント化します。 |
samplingLevel |
string |
いいえ | 希望するサンプリング レベル。利用可能な値を次に示します。
|
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
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
のパターンを使用して特定の日付を表すことも、
today
、yesterday
、NdaysAgo
パターン
を使用して相対的な日付を表すこともできます。
値は
[0-9]{4}-[0-9]{2}-[0-9]{2}|today|yesterday|[0-9]+(daysAgo)
と一致する必要があります。
start-date
は 2005-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
のパターンを使用して特定の日付を表すことも、
today
、yesterday
、NdaysAgo
パターン
を使用して相対的な日付を表すこともできます。
値は
[0-9]{4}-[0-9]{2}-[0-9]{2}|today|yesterday|[0-9]+(daysAgo)
と一致する必要があります。
end-date
は 2005-01-01
以降です。end-date
に上限はありません。相対的な日付を使用して(今日を基準に)過去 10 日間の期間を指定する例を 次に示します。
&start-date=9daysAgo &end-date=today
dimensions
dimensions=ga:browser,ga:city
dimensions
パラメータは、一般的な条件(たとえば、ga:browser
や ga: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:country
、ga:browser
の順に、データを昇順で並べ替えます。sort=ga:browser,ga:country
sort
パラメータを使用する場合は、次の点に注意してください。
- 並べ替えには、
dimensions
パラメータまたはmetrics
パラメータに使用したディメンション値または指標値のみを使用します。dimensions パラメータまたは metrics パラメータで指定されていないフィールドを基に並べ替えるようリクエストすると、エラーが返されます。 - en-US の言語 / 地域では、デフォルトで、文字列がアルファベットの昇順で並べ替えられます。
- 数値は、デフォルトで昇順で並べ替えられます。
- 日付は、デフォルトで昇順で並べ替えられます。
filters
filters=ga:medium%3D%3Dreferral
filters
クエリ文字列パラメータは、リクエストから返されるデータを制限します。filters
パラメータを使用するには、フィルタを適用するディメンションまたは指標を指定した後、フィルタ式を指定します。たとえば、次のクエリでは、ビュー 12134
の ga:pageviews
と ga: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
ステータス コードがサーバーから返されます。 - 大文字と小文字の区別 - 正規表現一致では大文字と小文字は区別されません。
- 最長 128 文字 - 正規表現の長さが 128 文字を超えると、
フィルタの組み合わせ
フィルタはブール論理演算の OR
と AND
を使用して組み合わせることができます。これにより、
フィルタ式の 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
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 行が返されます。ga:country
の有効な値は 300 個に満たないため、国のみでセグメント化すると、max-results
に 300 より大きな値を設定しても、取得できる行数は 300 行以下です。output
output=dataTable
json
- JSON オブジェクトを含み、デフォルトのrows
プロパティをレスポンスで出力します。dataTable
- Data Table オブジェクトを含み、dataTable
プロパティをレスポンスで出力します。このData Table
オブジェクトは、Google グラフのビジュアル表示で直接使用できます。
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 の説明に示すように、結果の合計数が現在のレスポンスのページサイズを上回る場合は、結果とレスポンスが異なることがあります。
{
"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 |
クエリ結果に含まれる行の合計数。レスポンスで返される行数は関係ありません。クエリの結果に大量の行が含まれる場合、totalResults が itemsPerPage を上回る場合があります。改ページを参照して、大規模なクエリの totalResults と itemsPerPage の詳細を確認してください。
|
startDate |
string |
start-date パラメータで指定されたデータクエリの開始日。 |
endDate |
string |
end-date パラメータで指定されたデータクエリの終了日。 |
selfLink |
string |
このデータクエリの結果のこのページへのリンク。 |
previousLink |
string |
このデータクエリの結果の前のページへのリンク。 |
nextLink |
string |
このデータクエリの結果の次のページへのリンク。 |
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 のみです。指標の列ヘッダーには、INTEGER 、PERCENT 、TIME 、CURRENCY 、FLOAT といった指標の値に対応するデータタイプがあります。すべてのデータタイプについては、Metadata API レスポンスを確認してください。
|
totalsForAllResults |
object |
指標の名前と値の Key-Value ペアとしての、リクエストした指標の合計値。指標の合計が表示される順序は、リクエストで指定された指標の順序と同じです。 |
rows[] |
list |
アナリティクスのデータ行。各行にはディメンション値とそれに続いて指標値が記載されたリストが含まれます。ディメンションと指標の順序は、リクエストで指定された順序と同じです。それぞれの行には、N 個のフィールドのリストが含まれます。ここで、N はディメンションと指標を合計した数です。 |
{
"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 |
クエリ結果に含まれる行の合計数。レスポンスで返される行数は関係ありません。クエリの結果に大量の行が含まれる場合、totalResults が itemsPerPage を上回る場合があります。改ページを参照して、大規模なクエリの totalResults と itemsPerPage の詳細を確認してください。
|
startDate |
string |
start-date パラメータで指定されたデータクエリの開始日。 |
endDate |
string |
end-date パラメータで指定されたデータクエリの終了日。 |
selfLink |
string |
このデータクエリの結果のこのページへのリンク。 |
previousLink |
string |
このデータクエリの結果の前のページへのリンク。 |
nextLink |
string |
このデータクエリの結果の次のページへのリンク。 |
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 のみです。指標の列ヘッダーには、INTEGER 、PERCENT 、TIME 、CURRENCY 、FLOAT といった指標の値に対応するデータタイプがあります。すべてのデータタイプについては、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 Explorer
で analytics.data.ga.get メソッドをお試しください。
サンプリング
Google アナリティクスでは、ディメンションと指標の特定の組み合わせがリアルタイムで計算されます。妥当な時間内のデータを返すために、Google アナリティクスではデータのサンプルのみを処理することができます。
samplingLevel パラメータを設定すると、リクエストに使用するサンプリング レベルを指定できます。
Core Reporting API のレスポンスにサンプルデータが含まれる場合、containsSampledData
レスポンス フィールドは true
になります。さらに、sampleSize
と sampleSpace
という 2 つのプロパティにより、クエリのサンプリング レベルに関する情報が提供されます。これらの 2 つの値を使用すると、クエリに使用されたセッションの割合を計算できます。たとえば、sampleSize
が 201,000
、sampleSpace
が 220,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)