Google Analytics 4(GA4) Data APIとは、GA4のレポートデータをプログラムから取得するためのインターフェースです。これを利用すると、ウェブブラウザ上のGA4管理画面で見る各種指標を、スクリプト(例えばGoogle Apps Script)やアプリケーションから自動的に取得できます。公式ドキュメントによれば、「Data APIを使用すると、Google Analytics(GA4)のレポート データにプログラムでアクセスできます」 developers.google.com 。つまり、GA4 Data APIはGA4のデータを外部から問い合わせるための公式な手段です。
一般的な使用方法としては、リクエストでプロパティIDや取得したいディメンション・指標・日付範囲などを指定し、APIが返すレポートデータ(JSON形式の集計結果)を読み取ります。例えば「特定の日付範囲のアクティブユーザー数を国別に取得する」ようなレポートも、Data API経由でプログラム的に取得できます。Google SheetsにてGoogle Apps Scriptから利用する場合、「サービスを追加」で「Google Analytics Data API」を有効化します。HTTP経由で直接エンドポイント(properties/runReport など)にリクエストを送る方法もあります。いずれにせよGA4 Data APIを使えば、人手を介さずレポートを自動生成できるため、定期レポートの自動化やスプレッドシート連携などによく活用されています。
Universal Analytics(UA)のReporting APIとの違いも押さえておきましょう。従来のUA(Google アナリティクス旧版)ではReporting APIでセグメント指定が可能でした。しかしGA4 Data APIはUAのAPIとは非互換の新しいAPIです developers.google.com。GA4のイベント駆動型データモデルに合わせて設計されており、エンドポイントやパラメータ構成がUA時代から大きく変わっています。その違いの一つとして、UAのAPIに存在した「セグメント」の指定項目がGA4 Data APIでは提供されていない点があります。次章で詳しく説明しますが、GA4 Data APIではUI上で設定できるセグメントを直接リクエストに適用することができません。この点を理解しておくことが、GA4 Data APIを正しく使いこなす前提となります。
GA4 Data APIを使い始めると、まず戸惑うのが「セグメントを指定できない」という点です。GA4のUIではユーザーやセッション単位でセグメントを作成し、特定の条件を満たすデータのサブセットを分析できます。しかしGA4 Data APIにはリクエストパラメータとしてセグメント項目が存在せず、API経由で直接セグメントを適用することはできません。
stackoverflow.com に示されたGA4 Data APIのrunReport
メソッドのパラメータ一覧を見ても、「dimensions(ディメンション)」「metrics(指標)」「dimensionFilter(ディメンションフィルタ)」等はありますが「segments(セグメント)」に相当する指定項目はありません。 stackoverflow.com
これはなぜでしょうか?理由の一つは、GA4 Data APIが提供する機能範囲がGA4の標準レポート(Reports)の機能に相当するためです。GoogleのIssue Trackerでの回答によれば、「Data APIはUIのレポートセクションと同様の機能を提供しており、レポートセクションではセグメントは利用できません。その代わりに比較機能(Comparisons)を使用できます」 issuetracker.google.com とのことです。GA4の標準レポート画面では、任意のセグメントをその場で作成して適用する代わりに、「比較」(Comparison) と呼ばれるフィルタ条件によるデータの絞り込み・比較機能が提供されています。Data APIもこの標準レポートと同様の設計となっているため、UIの探索(Explore)で可能な自由なセグメント指定機能はサポートされていないと考えられます。
もう一つの理由は、GA4のセグメント機能がリアルタイムにデータをフィルタリング・集計する高度な分析機能であり、これをAPIリクエスト単体で再現することが難しいためです。GA4では探索(Explore)の中でユーザーセグメント・セッションセグメント・イベントセグメントを柔軟に組み合わせて定義できますが、こうした「オンザフライ」(データをリアルタイムで解析)のセグメント処理はAPIには実装されていません。Google公式の回答でも、*「レポートクエリ内で動的にセグメントを作成することは現在サポートされていません」*とはっきり言及されています stackoverflow.com 。これはGoogleアナリティクスチームのエンジニアからの発言であり、GA4 Data APIでセグメントを直接指定する手段はないことの公式な裏付けと言えます。
以上をまとめると、GA4 Data APIではセグメント機能が提供されていないため、UAのように「セグメントIDを指定して絞り込んだレポートを取得する」といったことはできません。これは設計上の制約であり、GA4 UI上で可能なセグメント分析とAPIの機能範囲に違いがあるためです。では、APIでセグメントに近い分析を行うにはどうすればよいのでしょうか?次の章で代替手段としてフィルタを活用する方法を解説します。
GA4 Data APIにはセグメント指定こそありませんが、その代わりにディメンションや指標に対するフィルタ(filters)をリクエストに含めることができます。フィルタを上手く活用すれば、セグメントでデータを絞り込むのと近い効果を得ることが可能です。実際、GA4の標準レポートで「比較」機能を使ってデータを絞り込む場合も、内部的には特定のディメンション値によるフィルタリングが行われています measureschool.com 。Data APIではこのフィルタ機能を利用して、欲しいデータのサブセットを取得します。
フィルタの指定方法(概要): runReport
リクエストのJSONに、例えばdimensionFilter
オブジェクトを含めます。そこにフィルタ条件としてfieldName
(フィルタ対象のディメンション名)とその一致条件(完全一致、部分一致、大文字小文字区別など)を指定します。複数条件を組み合わせたい場合は、AND条件のandGroup
やOR条件のorGroup
を用いて複合フィルタを構成できます。以下はイメージ例です(国が「Japan」のユーザーに絞るフィルタ):
"dimensionFilter": {
"filter": {
"fieldName": "country",
"stringFilter": {
"matchType": "EXACT",
"value": "Japan"
}
}
}
上記のように、セグメントの条件が単一のディメンション(または指標)によって定義できる場合、Data APIのフィルタでも同様の絞り込みができます。GA4 UI上の「比較」も内部的にはこのような単一または複数ディメンション条件のフィルタリングで実現されています measureschool.com 。
しかし、フィルタでは代替できない複雑なセグメント条件も存在します。代表的なものはシーケンスセグメントやセッションスコープの複合条件です。例えば:
シーケンスセグメント: 「あるユーザーがまずイベントAを行い、その後にイベントBを行った」という順序を条件にしたセグメントは、単純なフィルタでは再現できません。フィルタは各イベント(行)ごとに適用されるため、「イベントの発生順序」という文脈を考慮できないためです。
セッション全体にまたがる条件: 「特定のイベントXを含むセッションの全ページビューを分析したい」といったケースもフィルタでは難しいです。例えば「イベントXが発生したセッションの売上合計」を求めようとしてeventName
にXをフィルタ指定すると、そのセッション内の他の購入イベントまでも除外されてしまうことがあります。実際、あるユーザーが指摘しているように「イベントでフィルタすると、該当セッションの別のイベント(購入など)が除外され、セグメントで欲しい指標と一致しない」という問題が報告されています reddit.com reddit.com 。これはフィルタ方式の限界で、セグメントのように「セッション単位で条件を満たすかどうか」を判断してデータを集計することができないために起こる現象です。
要するに、フィルタは基本的に各イベントや各ユーザーごとの属性に基づいてデータを絞り込む仕組みであり、イベント間の時系列関係やセッション全体に関わるロジックを直接指定することはできません。したがって「フィルタで代替可能なセグメント」は単一条件・静的条件によるセグメントに限られ、フィルタで代替不可能なセグメントとしてシーケンス・組み合わせロジックを含むセグメントが挙げられます。
ポイント: 多くの基本的なセグメント(ユーザー属性や1条件の絞り込み)はフィルタで再現できますが、高度なセグメント分析(例: 一連の行動パターンを捉える分析)はGA4 Data API単独では難しくなります。そのような場合は、後述するオーディエンス機能の活用や、BigQueryエクスポートを使ったオフライン分析など、API以外の手段も検討する必要があります reddit.com 。
セグメント相当のデータをGA4 Data APIで取得するもう一つのアプローチが、GA4のオーディエンス機能を利用する方法です。GA4における「オーディエンス」とは、特定の条件に基づいて定義されたユーザーのグループのことです 。GA4のセグメント設定画面の3点アイコンから、「オーディエンスの作成」に進むことができます。オーディエンスを作成しておくと、以降その条件を満たしたユーザーがオーディエンスメンバーとして蓄積されます。
GA4 Data APIでは、このオーディエンスに基づいたデータ取得が可能です。具体的には、リクエストにaudienceName
ディメンションを含めることで、各オーディエンスごとの指標値を取得できます。また、特定のオーディエンスだけにデータを絞りたい場合は、dimensionFilter
でaudienceName
を指定し、値を絞り込むことも可能です。Googleのエンジニアからも「GA4 UIで対象のセグメント条件を満たすオーディエンスを定義しておき、Data APIではaudienceName
ディメンションを使ってそのオーディエンスのデータを問い合わせる方法」が推奨されています stackoverflow.com 。つまり、セグメントを直接APIに指定できない代わりに、一度GA4上にセグメント相当のオーディエンスを作成し、その名前をAPIリクエストで指定するという回避策になります。
実際の使い方としては、例えば「直近30日間に商品購入イベントを行ったユーザー」というオーディエンス(仮に名前を「Purchasers」)をGA4管理画面で作成したとします。オーディエンス作成後、GA4 Data APIのリクエストでdimensions: ['audienceName']
を含め、metrics: ['activeUsers']
など任意の指標を指定してデータを取得すると、結果は「audienceName=All Users」の行と「audienceName=Purchasers」の行に分かれて返ってきます。All Users
は全ユーザーを指し、Purchasers
は該当オーディエンスに属するユーザーを指します 。このようにオーディエンスごとに指標値を集計して比較することが可能です。また、もしPurchasers
オーディエンスの指標値だけが欲しければ、リクエストにdimensionFilter
を加え、audienceName == "Purchasers"
という条件で絞り込むこともできます。
しかし、オーディエンス活用にも注意すべき制約があります。まず第一に、オーディエンスはユーザーレベルの集計単位であることです。オーディエンスに属するか否かは「ユーザー」が基準となるため、セッション単位やイベント単位の細かな条件を直接オーディエンスとして保存することはできません。たとえば「単一セッション内で特定の順序の行動をとったセッション」という概念はオーディエンス(ユーザーの集まり)には置き換えづらいです。オーディエンスを使ったAPI抽出は常に「ある条件を満たすユーザー全体が対象」となります。このため、ユーザー単位でしか定義できないセグメント(例: ある期間内に○回購入したユーザー etc.)はオーディエンスで実現できますが、セッション固有の一時的な条件はオーディエンス化できない場合があります。
第二に、オーディエンスは作成後にしかデータが蓄積されないことです。GA4のオーディエンスは作成した時点からユーザーのプールを構築し始めるため、過去のデータに遡って適用することはできません docs.magnolia-cms.com 。例えば、2024年1月1日に新しいオーディエンスを作成したとすると、そのオーディエンスには作成以降の期間に条件を満たしたユーザーしか含まれません。それ以前に条件を満たしていたユーザーであっても、作成前の履歴だけでは遡及的にメンバーにはならない点に注意が必要です(※作成直後に過去最大30日分のユーザーデータを初期評価して組み入れる仕組みはありますが、それ以上は遡れません measureschool.com )。公式の記述でも、「ユーザーはレポートの対象期間中に所属していたオーディエンスに基づいて報告され、現在のユーザー行動は過去のオーディエンス所属状況に影響しない」とあります docs.magnolia-cms.com 。これは裏を返せば、オーディエンス作成前の過去データにはそのオーディエンスによるセグメントを適用できないことを意味します。
以上のように、オーディエンスを使う方法は「事前に条件を定義してユーザー群を作っておき、将来のデータ収集に反映する」アプローチです。そのため、分析に用いたいセグメントがあらかじめ分かっていて、将来的に追跡したい場合には有効ですが、「今すぐ過去○ヶ月分についてこの条件でセグメント集計したい」といった要望には応えられません。この点はセグメントとの大きな違いです(セグメントは分析時に過去データへ適用できますが、オーディエンスは適用できない)。また前述の通りユーザー粒度のため、セグメントによっては完全に同等の定義ができないことにも留意してください stackoverflow.com 。
とはいえ、現状GA4 Data APIでセグメント相当の分析をする方法としては「フィルタを駆使する」か「オーディエンスを活用する」かの二択になります。GA4の画面上からオーディエンスを簡単に作成できることもあり、動的セグメントを使いたい場合はオーディエンス機能で代替し、Data APIではaudienceName
で取得するという運用が現実的な解決策となります stackoverflow.com 。実際、Googleの公式Q&Aでもこの方法が紹介されており、多くの開発者が採用しています。
GA4 Data APIでは、現在セグメントを直接適用することはできません。 これはGA4移行当初から指摘されている制限事項であり、API利用者はフィルタやオーディエンスによる代替策を講じる必要があります。幸い、単純な条件であればフィルタで絞り込みが可能ですし、ユーザー単位の条件であればオーディエンスを事前設定することでかなり柔軟に対応できます。しかし、複雑なシナリオでは依然として「セグメントが使えないことによる解析上の不便さ」が残ります stackoverflow.com 。
現時点(2025年)で、Googleは公式にGA4 Data APIへのセグメントサポート計画を発表していません。コミュニティでも「今後セグメントに対応するのか?」という質問が投げかけられていますが、非公式ながら「No(期待しにくい)」との見解も示されています reddit.com reddit.com 。したがって、少なくとも短期的には、Data API単体でUAのようなセグメント分析を完結させることは難しいでしょう。
そのため、GA4データの高度な分析ニーズに対しては他の手段との組み合わせも検討すべきです。例えば、GA4のBigQueryエクスポートを利用すれば生のイベントデータに対してSQLクエリで自由なセグメント抽出・分析が可能です reddit.com 。また、GA4 UIの探索(Explore)機能自体も、CSVエクスポートやLooker Studio連携によってレポートに活用できます。どうしても複雑なセグメント分析結果を自動化したい場合、探索で作成したセグメントの結果を定期エクスポートし(残念ながら現時点では手動で行うしかありません)、それをApps Scriptで処理する、といった工夫も一つの方法です。
まとめると、GA4 Data APIの現状の仕様ではセグメントは直接指定できないため、フィルタとオーディエンスで代替しつつ運用することが求められます。幸いGA4は柔軟な分析機能と連携手段を提供していますので、APIの制約を補うような形でこれらを活用してください。今後もしData APIにアップデートがありセグメント対応が追加された際には、改めて公式ドキュメント stackoverflow.com などで告知されるはずです。それまでは、本記事で述べた回避策を用いて、GA4 Data APIとGA4 UI機能を組み合わせた賢いデータ活用を行っていきましょう。
GA4のオーディエンスには「有効期間 (membership duration)」が設定でき、ユーザーがオーディエンスに追加されてから何日間そのリストに留まるかを指定できます。有効期間は最短1日から最長540日(約18か月)まで設定可能で、デフォルトでは30日です upport.google.com 。したがって540日がGA4オーディエンスの最大有効期限となります。
(例)「ユーザーAが本日条件を満たした場合、540日後までオーディエンスに残る」となります。公式ドキュメントにも、「有効期間: ユーザーがオーディエンスに最後に追加されてから最大540日間」と記載されています。つまりユーザーAが今日オーディエンス条件を満たしてリストに追加されたなら、そこから最大540日間はそのオーディエンスに含まれ続けることになります(期間内に再度条件を満たせば、その時点から期間がリセットされ延長されます)。
GA4データAPIで遡って取得できるデータの期間は、GA4プロパティのデータ保持期間(data retention)の設定に依存します。標準のGA4(無料版)ではイベントデータの保持期間はデフォルトで2か月、最大でも14か月まで延長可能です support.google.com 。したがって無料版GA4では最大で約14か月前までのデータしかAPI経由でも取得できません。
一方、GA4 360(有料版)ではデータ保持期間をさらに延長でき、最大で50か月まで過去データを保持できます support.google.com 。GA4 360プロパティでは保持期間を2、14、26、38、50か月から選択でき、最大50か月に設定すれば約4年前までのデータをGA4データAPIで取得することが可能です support.google.com support.google.com 。なお、これらの期間以上に遡ったデータは、GA4では保持されていないため無料版・有料版ともAPIから取得することはできません。公式ヘルプでも、標準の保持期間は最大14か月(※大規模プロパティでは2か月に制限)、360では最大50か月まで拡張可能であると明記されています support.google.com 。
参考資料:
Google アナリティクス データ API 概要
GA4 Data API のメソッド仕様(segmentsパラメータ無し)
GA4 標準レポートとData APIにおけるセグメント非対応の説明
GA4 Data APIでセグメントが未サポートであることの公式回答
フィルタとセグメントの違いに関する解説
audienceNameディメンション仕様とオーディエンス非遡及性に関する説明
Google アナリティクス4 オーディエンスの有効期間に関する公式ヘルプ
GA4のデータ保持期間(無料版と360の比較)に関する公式ドキュメント