Google Analytics APIのfiltersはセミコロンでAND、カンマでORを組み立てる

Google Analytics Core Reporting APIで取得する行を絞るには、filtersを使います。複数の条件は、セミコロンでAND、カンマでORにします。ただし、ORはANDより先に評価されます。記号を左から読むだけでは、意図と違う条件になることがあります。

先に日本語で「何が必須で、何が選択肢か」を一行にし、それからfilterへ直してください。複雑な式を一度で作るより、単一条件の結果を確かめてから条件を足す方が、集計対象を見失いません。

filtersは名前、operator、式の三つで作る

Core Reporting APIのReference Guideでは、一つのfilterを次の形で指定します。

ga:name operator expression

たとえば、mediumがreferralの行だけを取得する条件は次のようになります。

filters=ga:medium==referral

ga:mediumが絞る項目、==が完全一致、referralが照合する式です。HTTP requestへ入れる際はoperatorなどをURL encodeします。Google API client libraryを使う場合は、filter operatorが自動でencodeされます。

filterは返される行を制限します。Google Analyticsに保存済みのデータを削除したり、viewの設定を変更したりするものではありません。同じ期間でもfilterが違えば結果が変わるため、数値と一緒にfilterも保存します。

ANDはセミコロン、ORはカンマでつなぐ

次の例は読みやすくするため、URL encode前の形で示しています。

ga:country==Japan;ga:browser==Firefox

セミコロンはANDです。この条件では、countryがJapanであり、browserがFirefoxである行を残します。

ga:browser==Firefox,ga:browser==Chrome

カンマはORです。browserがFirefoxまたはChromeである行を残します。

同じ項目の候補を増やすときはOR、別の必須条件を重ねるときはANDと考えると組み立てやすくなります。商品名やcampaign名のように、値自体へセミコロン、カンマ、backslashが入る場合は、その文字をbackslashでescapeし、条件をつなぐ記号と区別します。

ORがANDより先に評価される

Core Reporting APIのfilterでは、ORがANDより優先されます。次の条件を見てください。

ga:browser==Firefox;ga:operatingSystem==Windows,ga:operatingSystem==Macintosh

これは、browserがFirefoxであり、operating systemがWindowsまたはMacintoshである行を残す条件です。後半の二つが先にORの組になり、その組とFirefoxがANDで結ばれます。

条件が長くなると、記号の規則を知っていても確認しにくくなります。次のように、先に条件を分けて書きます。

必須: browserはFirefox
選択: operating systemはWindowsまたはMacintosh

この日本語とfilterが対応しているかを確認します。ANDとORが何組も続く場合は、一つのrequestへ詰め込まず、requestを分けて結果を比較する方法もあります。API callの回数だけで決めず、誰が見ても抽出条件を再現できるかを優先します。

dimensionとmetricではfilterを掛ける段階が違う

dimensionのfilterは、dimensionを集計する前に適用されます。browserをFirefoxへ絞れば、返るmetricはFirefoxに該当するデータの集計になります。

metricのfilterは、metricを集計した後に適用されます。たとえば、sessionが5より多い行へ絞る条件は次の形です。

ga:sessions>5

ANDではdimensionとmetricを同じ式へ含められます。

ga:country==Japan;ga:sessions>5

一方、ORではdimensionとmetricを同じ式へ混ぜられません。countryとsessionをORでつなぐ条件へ無理に直すのではなく、何を一つの表として比較したいのかを見直します。

filterに使うdimensionまたはmetricは、取得列に含めなくても構いません。ただし、request内のdimension、metric、filterが有効な組合せである必要があります。表示しない条件だから確認しなくてよい、という意味ではありません。

単一条件から増やしrequestと結果を残す

実装は、次の順で確認します。

1. 期間、metric、dimensionを固定してfilterなしで取得する。
2. 単一のdimension filterを追加し、対象行が変わることを確かめる。
3. ANDまたはORを一つだけ追加し、日本語で書いた条件と照合する。
4. URL encode前のfilterと、実際に送信したrequestを保存する。
5. 取得件数と先頭数行を記録し、変更前後を比べる。

API実装を外部へ任せても、どの行を報告対象にするかは事業側の判断です。コードだけを納品物にせず、filterの意味、対象期間、取得列、実行日時を一緒に残してください。条件を説明できなければ、同じ数字を翌月に再現できません。

最初の一手は、現在使っているrequestを一つ選び、filtersを名前、operator、式へ分解することです。複数条件なら、ANDの必須条件とORの選択肢を日本語で一行に戻してください。