Google Analytics APIで1万行を超えるデータはstart-indexとmax-resultsで分けて取得する

Google Analytics Core Reporting APIは、1回のrequestで最大1万行を返します。query全体が1万行で打ち切られるわけではありません。start-indexとmax-resultsを使い、nextLinkがなくなるまで同じqueryの続きを取得します。

ページ分割とsamplingは別の問題です。すべての行を取得しても、responseのcontainsSampledDataがtrueなら、集計値はsamplingされたデータから計算されています。

1万行は一回のresponseに含められる上限である

Core Reporting API v3のReferenceでは、max-resultsを指定しない場合の既定値を1000行、1回のrequestで返す上限を1万行としています。

ここで分けるべきものは、queryに該当する全行と、現在のresponseへ入る行です。

totalResultsがitemsPerPageより大きいときは、まだ続きがあります。itemsPerPageは実際に返った行数ではなく、responseが含められる最大行数です。取得した件数はrowsの要素数で確認します。

start-indexは0ではなく1から始める

start-indexは1を最初の行とする値です。0から始める配列の添字と混同しないでください。

説明用の仮例として、query全体に2万3650行があり、各responseが指定した上限まで行を返す場合を考えます。

一回目をstart-index=0にすると、APIの1始まりの規則とずれます。二回目をstart-index=10000にすると、10000行目を重ねて取得することになります。

数値を自分で組み立てるより、responseにnextLinkがあれば、そのURLを次のrequestへ使う方が関係を保ちやすくなります。nextLinkがないときは、最後のページです。

ページを変えてもqueryの条件は変えない

ページ分割では、start-index以外の条件を同じにします。途中で期間、view、dimension、metric、sort、filter、segmentを変えると、別のqueryの結果を一つの表へ連結することになります。

実装前に、次の値を一つのquery設定として保存します。

• ids
• start-dateとend-date
• dimensions
• metrics
• sort
• filters
• segment
• samplingLevel

一ページ目を取得したら、responseのquery、totalResults、itemsPerPage、containsSampledDataも記録します。制作を委託する場合は、出力したCSVだけでなく、これらのquery条件と取得日時、失敗したページを受け取ってください。取得処理を委託しても、どのviewと期間を分析対象にするかという責任は利用者側に残ります。

totalsForAllResultsをページごとに足さない

totalsForAllResultsは、requestしたmetricについて、query全体の合計値を返します。現在のページだけの小計ではありません。

三ページを取得したからといって、各responseのtotalsForAllResultsを三回足すと、同じ全体値を重ねて計算します。行データはページごとに連結し、全体のmetric合計は一つのresponseにあるtotalsForAllResultsを使います。

行を自分で集計した値とtotalsForAllResultsが一致しない場合は、metricの性質、dimensionの組み合わせ、samplingの有無を確認します。ページ数を増やすだけでは、集計条件の違いは解消しません。

ページ分割ではsamplingを解消できない

responseのcontainsSampledDataは、返されたデータがsamplingを含むかを示します。sampleSizeは計算に使ったsample数、sampleSpaceは選択元となる全体の大きさです。

start-indexは、query結果のどの行から返すかを指定します。samplingLevelは、集計に使うsampleの水準を指定します。役割が違うため、一万行ずつすべて取得しても、samplingされたqueryが非samplingの結果へ変わることはありません。

ページ分割の完了条件は、すべての結果行を取得したことです。集計精度の確認条件は、containsSampledData、sampleSize、sampleSpaceを記録したことです。二つの完了条件を分けてください。

最初の一手は、Query Explorerで同じ期間、dimension、metric、sort、filterを試し、totalResultsを確認することです。1万行を超えるなら、nextLinkをたどる小さな取得処理を作り、一ページ目と最後のページの行番号を保存します。