このドキュメントでは、Multi-Channel Funnels Reporting API のすべてのクエリとレスポンスについて説明します。
はじめに
Multi-Channel Funnels Reporting API を使用すると、Google アナリティクスのマルチチャネル レポート データをリクエストできます。すべてのレポートは、トラッキング コードからアナリティクスに送信されるデータから派生する統計情報で構成され、ディメンションや指標として整理されます。ディメンションと指標を独自に組み合わせることで、Reporting API を使用して、お客様の仕様に合わせてカスタマイズされたレポートを作成できます。
この API には、レポートデータをリクエストするメソッド report.get のみが含まれています。このメソッドでは、データを取得するビュー(プロファイル)に対応するテーブル ID を指定します。さらに、次の項目を指定します。
- ディメンションと指標の組み合わせ。
- 期間。
- 取得するデータを制御する一連のオプション パラメータ。
この API により、report.get メソッドが REST エンドポイント( https://www.googleapis.com/analytics/v3/data/mcf)で使用できるようになります。次のセクションでは、サンプル リクエストを示し、各パラメータについて説明します。
リクエスト
この API には、データをリクエストするためのメソッドが 1 つ用意されています。
analytics.data.mcf.get()
この API は、REST エンドポイントとしてクエリすることもできます。
Authorization: Bearer {oauth2-token} GET https://www.googleapis.com/analytics/v3/data/mcf ?ids=ga:12345 &metrics=mcf:totalConversions,mcf:totalConversionValue &start-date=2011-10-01 &end-date=2011-10-31
各 URL クエリ パラメータは、API クエリ パラメータを指定します。API クエリ パラメータは、URL エンコードされている必要があります。
Multi-ChannelFunnel Reporting API へのリクエストはすべて、(できれば OAuth 2.0 を使って)承認する必要があります。
クエリ パラメータの概要
次の表は、Multi-ChannelFunnel 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 |
必須 | カンマ区切りの指標のリスト(mcf:totalConversions,mcf:totalConversionValue など)。有効なクエリには、指標を少なくとも 1 つ指定する必要があります。 |
dimensions |
string |
× | マルチチャネル レポートのカンマ区切りのディメンションのリスト(例: mcf:source,mcf:keyword )。 |
sort |
string |
× | 返されたデータの並べ替え順と並べ替え方向を示すカンマ区切りのディメンションと指標のリスト。 |
filters |
string |
× | リクエストに対して返されるデータを制限するディメンションまたは指標フィルタ。 |
samplingLevel |
string |
× | 希望するサンプリング レベル。使用できる値:
|
start-index |
integer |
× | 取得するデータの最初の行。1 から始まります。このパラメータは、max-results パラメータとともにページ設定メカニズムとして使用します。 |
max-results |
integer |
× | レスポンスに含める行の最大数。 |
クエリ パラメータの詳細
ids
ids=ga:12345
ga:
とレポートのビュー(プロファイル)ID を連結したものです。レポートのビュー(プロファイル)ID を取得するには、analytics.management.profiles.list
メソッドを使用します。このメソッドは、
Google アナリティクス Management API のビュー(プロファイル)リソースの id
を提供します。start-date
start-date=2011-10-01
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
は最も早いため 2011-01-01
です。start-date
に上限はありません。相対的な日付を使用して(昨日を基準に)過去 7 日間の期間を指定する例を 次に示します。
&start-date=7daysAgo &end-date=yesterday
end-date
end-date=2011-10-31
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=mcf:source,mcf:keyword
ディメンション パラメータは、マルチチャネル レポートのプライマリ データキー(mcf:source
、mcf:medium
など)を定義します。コンバージョン指標を分割するには、ディメンションを使用します。たとえば、サイトの合計コンバージョン数を求めることはできますが、メディア別に分割したコンバージョン数を尋ねる方が興味深いこともあります。この場合は、organic、referral、email などのコンバージョン数が表示されます。
データ リクエストで dimensions
を使用する場合は、次の制約に注意してください。
- クエリで指定できるディメンションは最大 7 個です。
- ディメンションのみで構成されたクエリを送信することはできません。リクエストするディメンションと少なくとも 1 つの指標を組み合わせる必要があります。
使用できない値
ディメンションの値を判別できない場合、特殊な文字列「(not set)」が使用されます。
metrics
metrics=mcf:totalConversions,mcf:totalConversionValue
合計コンバージョン数や合計コンバージョン値など、サイトでのユーザー アクションに関する集計データ。
クエリに dimensions
パラメータがない場合、返される指標は、全体の合計コンバージョン値など、リクエストされた期間の集計値を示します。ただし、ディメンションがリクエストされた場合、値はディメンション値によって分割されます。たとえば、mcf:source
でリクエストされた mcf:totalConversions
は、ソースごとの合計コンバージョン数を返します。
指標をリクエストする場合は、次の点に注意してください。
- どのリクエストでも少なくとも 1 つの指標を指定する必要があります。ディメンションのみでリクエストを構成することはできません。
- クエリには指標を 10 個まで指定できます。
sort
sort=mcf:source,mcf:medium
取得するデータの並べ替え順序と方向を示す指標とディメンションのリストです。
- 並べ替え順序は、指標とディメンションを指定した順(左から右)に指定されます。
- デフォルトの並べ替え方向directionは昇順ですが、リクエストしたフィールドで接頭辞としてマイナス記号(
-
)を使用すると、並べ替え方向を降順に変更できます。
クエリの結果を並べ替えることにより、データをさまざまな角度から見ることができます。たとえば、「上位のコンバージョンの発生元と、そのメディア経由」という質問には、次のように回答します。次のパラメータを使用してクエリを作成できます。mcf:source
で、次に mcf:medium
で、どちらも昇順で並べ替えます。
sort=mcf:source,mcf:medium
さらに、「最上位のコンバージョン メディアは何か、またそのソースは何か」という同様の質問への回答を得るには、次のパラメータを使用してクエリを作成できます。mcf:medium
で、次に mcf:source
で、どちらも昇順で並べ替えます。
sort=mcf:medium,mcf:source
sort
パラメータを使用する場合は、次の点に注意してください。
dimensions
パラメータまたはmetrics
パラメータに使用したディメンションまたは指標の値のみで並べ替えます。dimensions パラメータまたは metrics パラメータで指定されていないフィールドを基に並べ替えるようリクエストすると、エラーが返されます。- en-US の言語 / 地域では、デフォルトで、文字列がアルファベットの昇順で並べ替えられます。
- 数値は、デフォルトで昇順で並べ替えられます。
- 日付は、デフォルトで昇順で並べ替えられます。
filters
filters=mcf:medium%3D%3Dreferral
filters
クエリ文字列パラメータは、リクエストから返されるデータを制限します。filters
パラメータを使用するには、フィルタするディメンションまたは指標に続けてフィルタ式を指定します。たとえば、次のクエリは、ビュー(プロファイル)12134
の mcf:totalConversions
と mcf:source
をリクエストします。ここで、mcf:medium
ディメンションは文字列 referral
です。
https://www.googleapis.com/analytics/v3/data/mcf ?ids=mcf:12134 &dimensions=mcf:source &metrics=mcf:totalConversions &filters=mcf:medium%3D%3Dreferral &start-date=2011-10-01 &end-date=2011-10-31
詳細については、Core Reporting API リファレンスをご覧ください。
samplingLevel
samplingLevel=DEFAULT
DEFAULT
- 速度と精度のバランスがとれたサンプルサイズでレスポンスが返されます。FASTER
- サンプルサイズを小さくすることにより、高速なレスポンスが返されます。HIGHER_PRECISION
- サンプルサイズを大きくすることにより、より正確なレスポンスが返されますが、レスポンス速度が低下する可能性があります。
DEFAULT
のサンプリング レベルが使用されます。max-results
max-results=100
このレスポンスに含める行の最大数です。このパラメータを start-index
と組み合わせて使用すると、要素のサブセットを取得できます。また、このフィールドを単独で使用して、最初の要素から返される要素の数を制限することもできます。max-results
が指定されていない場合、クエリはデフォルトの最大 1, 000 行を返します。
指定した値に関係なく、Multi-Channel Funnels Reporting API から返される行数は、リクエストにつき最大 10,000 行です。ディメンション セグメントの数が予想より少ない場合、リクエストしたよりも少ない行数が返されます。たとえば、mcf:medium
に指定できる値は 300 個未満であるため、メディアのみでセグメント化した場合、max-results
により大きな値を設定しても、取得できる行数は 300 行までです。
レスポンス
成功すると、このリクエストは以下に定義する JSON 構造を持つレスポンスの本文を返します。
注: 「結果」という用語は、クエリに一致する行セット全体を表します。「レスポンス」という用語は、結果の現在のページで返される行のセットを表します。itemsPerPage で説明されているように、結果の合計数が現在のレスポンスのページサイズより大きい場合、これらの結果は異なる可能性があります。
レスポンスの形式
{
"kind": "analytics#mcfData",
"id": string,
"query": {
"start-date": string,
"end-date": string,
"ids": string,
"dimensions": [
string
],
"metrics": [
string
],
"sort": [
string
],
"filters": string,
"samplingLevel": string,
"start-index": integer,
"max-results": integer
},
"itemsPerPage": integer,
"totalResults": integer,
"selfLink": string,
"previousLink": string,
"nextLink": string,
"profileInfo": {
"profileId": string,
"accountId": string,
"webPropertyId": string,
"internalWebPropertyId": string,
"profileName": string,
"tableId": string
},
"containsSampledData": boolean,
"sampleSize": string,
"sampleSpace": string,
"columnHeaders": [
{
"name": string,
"columnType": string,
"dataType": string
}
],
"totalsForAllResults": [
{
metricName: string,
...
}
]
"rows": [
[
McfData.Rows
]
],
}
レスポンスのフィールド
レスポンス本文の構造のプロパティは次のように定義されています。
プロパティ名 | 値 | 説明 |
---|---|---|
kind |
string |
リソースのタイプ。値は "analytics#mcfData" です。 |
id |
string |
このデータ レスポンスの ID。 |
query |
object |
このオブジェクトは、パラメータとしてクエリに渡されるすべての値を格納します。各フィールドの意味については、対応するクエリ パラメータの説明をご覧ください。 |
query.start-date |
string |
開始日。 |
query.end-date |
string |
終了日。 |
query.ids |
string |
固有の表 ID。 |
query.dimensions[] |
list |
アナリティクス ディメンションのリスト。 |
query.metrics[] |
list |
アナリティクス指標のリスト。 |
query.sort[] |
list |
データの並べ替えに使用する指標またはディメンションのリスト。 |
query.filters |
string |
指標フィルタまたはディメンション フィルタのカンマ区切りリスト。 |
query.samplingLevel |
string |
Requested sampling level. |
query.start-index |
integer |
行の開始インデックス。デフォルト値は 1 です。 |
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 の詳細については、ページングをご覧ください。 |
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" または "MCF_SEQUENCE" のみです。指標の列ヘッダーには、"INTEGER" 、"DOUBLE" 、"CURRENCY" などの指標値に対応するデータ型があります。 |
totalsForAllResults |
object |
指標の名前と値の Key-Value ペアとしての、リクエストした指標の合計値。指標の合計が表示される順序は、リクエストで指定された指標の順序と同じです。 |
rows[] |
list |
レポートデータ行。各行には
{ "primitiveValue": "2183" }
{ "conversionPathValue": [ { "interactionType" : "CLICK", "nodeValue" : "google" }, { "interactionType" : "CLICK", "nodeValue" : "google" } ] } |
エラーコード
Multi-Channel Funnels Reporting API は、リクエストが正常に処理されると 200
HTTP ステータス コードを返します。クエリの処理中にエラーが発生すると、API からエラーコードと説明が返されます。Analytics API を使用するアプリケーションごとに、適切なエラー処理ロジックを実装する必要があります。エラーコードとその処理方法について詳しくは、
エラー レスポンス リファレンス ガイドをご覧ください。
試してみよう:
以下の API Explorer を使用して、ライブデータに対してこのメソッドを呼び出し、レスポンスを確認してください。
サンプリング
Google アナリティクスでは、ディメンションと指標の特定の組み合わせがその場で計算されます。妥当な時間内にデータを返すために、Google アナリティクスではデータのサンプルのみを処理する場合があります。
samplingLevel パラメータを設定すると、リクエストに使用するサンプリング レベルを指定できます。
MCF Reporting API レスポンスにサンプリング データが含まれている場合、containsSampledData
レスポンス フィールドは true
になります。また、sampleSize
と sampleSpace
の 2 つのプロパティによって、クエリのサンプリング レベルに関する情報が提供されます。この 2 つの値を使用して、クエリで使用されたセッションの割合を計算できます。たとえば、sampleSize
が 201,000
で、sampleSpace
が 220,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
は、結果で返される最大行数を示します。itemsPerPage
に対する totalResults
の比率が高い場合は、個々のクエリに必要以上に時間がかかっている可能性があります。表示目的などで、必要な行数が限られている場合は、max-results
パラメータを使用してレスポンス サイズに明示的な制限を設定すると便利です。ただし、アプリケーションで大きな結果セット全体を処理する必要がある場合は、許可された最大行数をリクエストする方が効率的です。
gzip の使用
gzip 圧縮を有効にすると、各リクエストが消費する帯域幅を手早く低減できます。これには、結果を圧縮解除するために追加の CPU 時間が必要ですが、ネットワークのコストを大きく削減できます。gzip でエンコードされたレスポンスを受け取るには、Accept-Encoding
ヘッダーを設定し、ユーザー エージェントを変更して文字列 gzip
を含める必要があります。gzip 圧縮を有効にするための正しい形式の HTTP ヘッダーの例を次に示します。
Accept-Encoding: gzip User-Agent: my program (gzip)