Data API の chat メソッドは、アナリティクス アドバイザー（自然言語を使用して Google アナリティクス データのクエリ、分析、診断を行うのに役立つ AI を活用した分析アシスタント）へのプログラムによるアクセスを提供します。
アナリティクス アドバイザーは Google アナリティクスのユーザー インターフェースでインタラクティブに利用できますが、chat API を使用すると、デベロッパー、自律型 AI エージェント、内部ツールが HTTP 経由でアナリティクス アドバイザーとプログラムでやり取りできます。
重要: このサービスは AI を使用しており、不正確な情報が表示されることがあります。チャット アクティビティはサービスの改善に使用されることがあります。サービスのご利用には Google の利用規約、AI 利用ポリシー、プライバシー ポリシーが適用されます。
概要
chat メソッドを使用すると、単一ターンのアドホック データ質問とマルチターンの会話セッションの両方を行うことができます。
- 単一ターンのクエリ: 「先週のトラフィック チャネルの上位は？」などの分析に関する質問をすぐに投げかけ、構造化データテーブルとともに自然言語の回答を受け取ります。
- マルチターンの会話:
sessionIdを渡して会話の履歴を保持し、診断用のフォローアップの質問（「その期間にオーガニック トラフィックが減少したのはなぜですか？」など）をします。 - 構造化データ レスポンス: テキストによる説明に加えて、レスポンスには列見出しと行を含む構造化された
tableブロックが含まれます。 - Chat の割り当てのモニタリング:
returnPropertyQuotaをtrueに設定して、1 日あたりと 1 時間あたりの残りの Chat トークン割り当てを確認します。
認証
chat メソッドの呼び出しには、次のスコープによる OAuth 2.0 認証が必要です。
始める前に
gcloud CLI をインストールして初期化します。
アプリケーションのデフォルト認証情報を生成し、アカウントに必要なスコープを付与するには、次のコマンドを実行します。
gcloud auth application-default login --scopes="https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/analytics.chatbot.read"Google アナリティクスの UI で、ユーザー アカウントに Google アナリティクスのプロパティへのアクセス権を付与します。
次のように入力して、環境変数を構成します。
PROJECT_IDは プロジェクトの ID に、PROPERTY_IDは Google アナリティクスのプロパティの ID に置き換えます。export PROJECT_ID=
PROJECT_IDexport PROPERTY_ID=PROPERTY_ID
例 1: 割り当てトラッキングを含むシングルターン クエリ
新しい会話を開始するには、userQuery を含む ChatRequest を作成します。returnPropertyQuota を true に設定して、残りのトークン残高を検査します。
シナリオ: デバイス別の収益とコンバージョン率
過去 30 日間のデバイス別の収益とセッションのコンバージョン率を比較したい。
HTTP リクエスト
curl -X POST \
"https://analyticsdata.googleapis.com/v1alpha/properties/${PROPERTY_ID}:chat" \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "x-goog-user-project: ${PROJECT_ID}" \
-H "Content-Type: application/json" \
-d '{
"userQuery": "Compare our revenue and conversion rate across mobile vs desktop over the last 30 days.",
"returnPropertyQuota": true
}'
HTTP レスポンス
レスポンスには次のものが含まれます。
- フォローアップ ターンに使用できる、新たに割り当てられた
sessionId。 - 自然言語の要約（
text）と構造化された表（table）の両方を含むblocksのリスト。テキスト ブロックには、テキストを太字にする（機能）、見出し、リンクなどのマークダウン形式を含めることができます。 - 宿泊施設の
propertyQuotaの詳細。
{
"sessionId": "692e9ab9-b338-4426-b006-a05f21ac7cd6",
"blocks": [
{
"text": "Your report on revenue and conversion rates for mobile vs. desktop over the last 30 days (August 15 - September 13, 2026) is ready.\n\nHere is a summary of your revenue and conversion rate by device category:\n"
},
{
"table": {
"headers": [
{
"header": "Device Category",
"dataType": "string"
},
{
"header": "Total Revenue",
"dataType": "string"
},
{
"header": "User Conversion Rate",
"dataType": "string"
}
],
"rows": [
{
"columns": [
{
"value": "Desktop"
},
{
"value": "$17,412.62"
},
{
"value": "99.9%"
}
]
},
{
"columns": [
{
"value": "Mobile"
},
{
"value": "$15,309.41"
},
{
"value": "99.46%"
}
]
}
}
},
{
"text": "**Revenue and Conversion Rate Trends:**\n\nRevenue from desktop devices saw a peak on August 18th, while mobile revenue peaked on August 30th. Conversion rates remained high and relatively stable for both desktop and mobile throughout the period."
},
{
"text": "This product uses AI and may display inaccurate info. Your chat activity may be used to improve the product and your use is subject to Google's [Terms](https://policies.google.com/terms), [AI Use Policy](https://policies.google.com/terms/generative-ai/use-policy), and [Privacy Policy](https://policies.google.com/privacy). [Learn more about Chat AI Privacy](https://support.google.com/helpguide/answer/14185196)."
}
],
"propertyQuota": {
"tokensPerDay": {
"consumed": 26849,
"remaining": 3723151
},
"tokensPerHour": {
"consumed": 26849,
"remaining": 473151
}
}
}
例 2: マルチターンの会話型診断
コンテキストを維持しながらフォローアップの質問をするには、リクエストに前のレスポンスで返された sessionId を含めます。
シナリオ: 前の期間と比較する
前のデバイスの比較に続いて、アドバイザーに結果を前の期間と比較するよう依頼します。
HTTP リクエスト
curl -X POST \
"https://analyticsdata.googleapis.com/v1alpha/properties/${PROPERTY_ID}:chat" \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "x-goog-user-project: ${PROJECT_ID}" \
-H "Content-Type: application/json" \
-d '{
"sessionId": "692e9ab9-b338-4426-b006-a05f21ac7cd6",
"userQuery": "Compare results with the same period in the previous mounth."
}'
HTTP レスポンス
アナリティクス アドバイザーは、セッション メモリを使用して結果を前の期間と関連付けます。
{
"sessionId": "eb3284b2-49ce-4aed-b6d0-fdc15cb87b5f",
"blocks": [
{
"text": "The following table provides a detailed comparison of total revenue and user conversion rate by device category for the two periods.\n"
},
{
"table": {
"headers": [
{
"header": "Device Category",
"dataType": "string"
},
{
"header": "Metric",
"dataType": "string"
},
{
"header": "Jul 16 - Aug 15, 2026",
"dataType": "string"
},
{
"header": "Aug 16 - Sep 14, 2026",
"dataType": "string"
}
],
"rows": [
{
"columns": [
{
"value": "Desktop"
},
{
"value": "Total Revenue"
},
{
"value": "$17,412.62"
},
{
"value": "$19,565.46"
}
]
},
{
"columns": [
{
"value": "Desktop"
},
{
"value": "User Conversion Rate"
},
{
"value": "1.90%"
},
{
"value": "1.95%"
}
]
},
{
"columns": [
{
"value": "Mobile"
},
{
"value": "Total Revenue"
},
{
"value": "$13,997.19"
},
{
"value": "$15,309.41"
}
]
},
{
"columns": [
{
"value": "Mobile"
},
{
"value": "User Conversion Rate"
},
{
"value": "1.95%"
},
{
"value": "1.99%"
}
]
}
}
}
]
}
レスポンスの構造とデータブロック
ChatResponse オブジェクトは、blocks 配列で構造化されたコンポーネントを返します。
| ブロックタイプ | フィールド | 説明 |
|---|---|---|
| ナレーション テキスト | blocks[].text |
人が読める形式の説明と、分析結果の概要。 |
| 構造化テーブル | blocks[].table |
headers（名前とデータ型）と rows（セル値）を含む表形式のデータの内訳。 |
表のヘッダーのデータ型
blocks[].table.headers の列は、セマンティック データ型を表します。
string: カテゴリカル テキスト値（"desktop"、"/shop/apparel"など）。float: 数値の浮動小数点数。
チャットの割り当て管理
Analytics Advisor のリクエストは、クエリの複雑さに応じてチャット トークンを消費します。returnPropertyQuota が true の場合、現在の割り当て状態は propertyQuota で返されます。
tokensPerDay: 1 日あたりのトークンの上限と残高。tokensPerHour: 1 時間のスライディング ウィンドウのレート制限と残高。
統合アプリケーションの候補
properties.chat メソッドは、チームとツールにまたがる複数の統合アーキテクチャをアンロックします。
エンタープライズ チャットとコラボレーション ボット
チームチャット ワークスペースを Google アナリティクスに直接接続します。
- スレッド セッション:
sessionIdをチャット スレッド ID に保存して、チームメンバーがフォローアップの質問を共同で行えるようにします。 - リッチカードのレンダリング:
tableレスポンス ブロックをインタラクティブなカード ウィジェットにフォーマットします。
自律型 AI エージェントと Model Context Protocol（MCP）ツール
LLM オーケストレーター（Gemini、LangChain、Claude など）に GA 分析ツールを装備します。
- LLM に複雑な
runReportクエリを生成させるのではなく、LLM エージェントは自然言語のインテントでchatメソッドを呼び出すことができます。 - エージェントは、事実に基づいた要約と構造化されたテーブルを受け取り、それらを統合してマルチチャネル マーケティングの推奨事項を作成します。
自動化されたエグゼクティブ ブリーフィングとアラート
異常を事前に調査するスケジュールされたサービスを作成します。
- 毎日の cron ジョブは、「昨日の主要なパフォーマンス指標を要約し、コンバージョンの異常な減少を特定する」というクエリを実行します。
- 異常が検出されると、スクリプトは根本原因を診断するためのフォローアップ クエリを自動的にトリガーし、概要ダイジェストを内部ダッシュボードまたは CRM システムに投稿します。