Google Analytics 4(GA4)とGoogle Search Console(GSC)は、SEO・マーケティング分析の中核データソースである。API経由でこれらのデータを取得し、独自ダッシュボード・AI分析エンジンに流し込む実装は、本格的なマーケティングシステムで必須となる。本記事では、renueが自社プロダクトとして実装している`GA4Client`と`SearchConsoleClient`をもとに、サービスアカウント認証・dataclass設計・遅延初期化まで含む本番品質の実装パターンを解説する。
GA4/GSC API統合の基礎
両APIとも以下の共通点を持つ。
- 認証方式: サービスアカウント(JSON鍵) または OAuth 2.0
- 権限モデル: プロパティ/サイトごとに閲覧権限付与が必要
- ライブラリ: Googleが公式Pythonクライアントライブラリを提供
- レート制限: 1日あたりのクォータ制限あり
両API比較
| 項目 | GA4 Data API | Search Console API |
|---|---|---|
| ライブラリ | google-analytics-data | google-api-python-client |
| クライアントクラス | BetaAnalyticsDataClient | googleapiclient.discovery.build |
| 必要スコープ | analytics.readonly | webmasters.readonly |
| 識別子 | Property ID(数字) | Site URL |
| 主要データ | セッション/ユーザー/PV/CV | 検索クエリ/表示回数/CTR/順位 |
| データ期間 | 理論上無制限 | 最大16ヶ月 |
本番品質の統合に必要な5レイヤー
レイヤー1: サービスアカウント認証
Webアプリやバッチジョブで本番運用する場合、OAuth 2.0(ユーザー認証)ではなくサービスアカウントが推奨される。以下の理由がある。
- 人間の介在が不要: 完全自動で実行可能
- 長期有効: OAuth トークンのリフレッシュ管理が不要
- 複数サイト対応: 1つのサービスアカウントで複数GA4/GSCを扱える
- 監査ログが明確: サービスアカウント別にアクセス履歴が残る
サービスアカウント作成の手順
- Google Cloud Console → 「IAMと管理」→「サービスアカウント」→「作成」
- GA4 Data API / Search Console API を有効化
- 鍵を作成(JSON形式)してダウンロード
- GA4の管理画面でサービスアカウントのメールアドレスを「閲覧者」権限で追加
- Search Consoleでも同様にサイトへの権限を付与
重要な落とし穴
GCP側で設定しただけでは不十分。**GA4/GSC側でも閲覧権限を付与する必要がある**。これを忘れると「認証は通るがデータが取れない」という状況になる。renueの実装ではこの問題に対応するエラーハンドリングを入れている。
レイヤー2: JSON文字列からの認証情報生成
本番運用では、サービスアカウントJSONをファイルではなく環境変数や暗号化DBに保存する。ファイルだとデプロイ時の管理が面倒になるため。
GA4Clientの実装パターン
class GA4Client:
SCOPES = ["https://www.googleapis.com/auth/analytics.readonly"]
def __init__(
self,
property_id: str,
service_account_json: Optional[str] = None,
credentials: Optional[Credentials] = None,
):
self.property_id = property_id
self._client = None
self._credentials = credentials
if service_account_json and not credentials:
self._credentials = self._create_credentials(service_account_json)
def _create_credentials(self, service_account_json):
try:
sa_info = json.loads(service_account_json)
# private_keyのフォーマットを修正
if "private_key" in sa_info:
sa_info["private_key"] = fix_private_key(sa_info["private_key"])
return Credentials.from_service_account_info(sa_info, scopes=self.SCOPES)
except json.JSONDecodeError as e:
raise GA4ClientError(f"Invalid service account JSON: {e}")
except Exception as e:
raise GA4ClientError(f"Failed to create credentials: {e}")
private_key修正の重要性
サービスアカウントJSONを環境変数経由で渡すとき、改行コード(` `)が文字列リテラルとして保存されるケースがある。これをそのままGoogleライブラリに渡すと認証エラーになるため、`fix_private_key`で実際の改行コードに変換する必要がある。
renueの実装では以下のような処理を`google_service_account.fix_private_key`で実行している。
- `\n`を実際の改行(` `)に変換
- BEGIN/ENDマーカーが正しく改行されているか確認
- 末尾の改行を保証
この1つのヘルパー関数があるかないかで、環境変数経由の認証が成功するかが決まる。本番実装で最もハマる罠の1つである。
レイヤー3: dataclass設計による型安全性
GA4/GSCのレスポンスは複雑な辞書形式で返ってくる。これをそのまま使うと型が曖昧になり、呼び出し側でバグが発生しやすい。renueの実装ではdataclassで型を明確化している。
GA4MetricsDataの設計
@dataclass
class GA4MetricsData:
date: date
sessions: int = 0
users: int = 0
new_users: int = 0
pageviews: int = 0
bounce_rate: float = 0.0
avg_session_duration: float = 0.0
events: int = 0
conversions: int = 0
raw_data: Optional[Dict[str, Any]] = None
設計のポイント
- デフォルト値で安全: 欠損データは0/0.0で埋める
- raw_dataを残す: 将来使う可能性のあるデータはraw_dataに保持
- 型ヒント: IDEの補完とmypyチェックが効く
- 日付型: `date`型にすることで日付演算が安全
SearchConsoleRowの設計
@dataclass
class SearchConsoleRow:
query: str = ""
page: str = ""
impressions: int = 0
clicks: int = 0
ctr: float = 0.0
position: float = 0.0
@dataclass
class SearchConsoleData:
site_url: str = ""
start_date: str = ""
end_date: str = ""
rows: List[SearchConsoleRow] = field(default_factory=list)
total_impressions: int = 0
total_clicks: int = 0
avg_ctr: float = 0.0
avg_position: float = 0.0
2層構造にする理由
`SearchConsoleData`が全体を表し、`rows`に個別データを格納する2層構造を採用している。これにより以下のメリットがある。
- 総合指標(total_*)と個別指標の両方をセットで扱える
- メタデータ(site_url, start_date, end_date)と本体データを分離
- `field(default_factory=list)`で空リストの共有問題を回避
レイヤー4: 遅延初期化パターン
GA4/GSCのクライアントインスタンスは初期化コストが高い。全てのリクエストで新規作成するのは非効率。renueの実装では**遅延初期化(lazy initialization)**を採用している。
@property
def client(self) -> BetaAnalyticsDataClient:
# クライアントインスタンスを取得(遅延初期化)
if self._client is None:
if self._credentials is None:
raise GA4ClientError("No credentials provided")
self._client = BetaAnalyticsDataClient(credentials=self._credentials)
return self._client
遅延初期化のメリット
- 認証情報なしでもインスタンス化可能: テスト時にモックを差し込みやすい
- 初回呼び出し時のみクライアント生成: 未使用時のコストゼロ
- 2回目以降はキャッシュ使用: 高速
- `@property`で透過的アクセス: 呼び出し側はメソッド/プロパティを意識しない
レイヤー5: エラー階層の設計
GA4とGSCで別々のカスタム例外を定義することで、呼び出し側でのエラーハンドリングが明確になる。
class GA4ClientError(Exception):
# GA4クライアントエラー
pass
class SearchConsoleClientError(Exception):
# Search Consoleクライアントエラー
pass
カスタム例外の設計方針
- API別: GA4とGSCでエラークラスを分離
- 呼び出し側で分岐可能: `except GA4ClientError`で絞り込み
- メッセージを具体的に: 原因がすぐわかるメッセージ
- `from e`で原因を保持: スタックトレースで原因究明できる
主要なGA4メトリクスとディメンション
よく使うメトリクス
- sessions: セッション数
- activeUsers: アクティブユーザー数
- newUsers: 新規ユーザー数
- screenPageViews: ページビュー数
- bounceRate: 直帰率
- averageSessionDuration: 平均セッション時間
- eventCount: イベント数
- conversions: コンバージョン数
よく使うディメンション
- date: 日付
- pagePath: ページパス
- sessionSource: 流入元
- sessionMedium: 流入手段
- deviceCategory: デバイス(desktop/mobile/tablet)
- country: 国
- eventName: イベント名
Search Consoleクエリの典型パターン
ページ別パフォーマンス
dimension=["page"]で、ページごとの表示回数・クリック数・CTR・平均順位を取得。SEO改善の起点となるクエリ。
クエリ別パフォーマンス
dimension=["query"]で、検索クエリごとの表示回数・クリック数を取得。どのキーワードで流入しているかを把握。
ページ×クエリ
dimension=["page", "query"]で、ページとクエリの組み合わせ分析。ページごとに「どのクエリで表示されているか」がわかる。
日次推移
dimension=["date"]で、日別の全体トレンドを取得。季節変動や特異日の検出に使う。
GA4のRunReportRequest構築
GA4のData APIではレポートリクエストを構造化して送信する。
from google.analytics.data_v1beta.types import (
DateRange, Dimension, Metric, RunReportRequest,
)
request = RunReportRequest(
property=f"properties/{self.property_id}",
dimensions=[
Dimension(name="date"),
Dimension(name="pagePath"),
],
metrics=[
Metric(name="sessions"),
Metric(name="screenPageViews"),
Metric(name="conversions"),
],
date_ranges=[DateRange(start_date="7daysAgo", end_date="today")],
limit=100000,
)
response = self.client.run_report(request)
date_rangesの柔軟な指定
- 相対指定: "7daysAgo", "30daysAgo", "today", "yesterday"
- 絶対指定: "2026-01-01", "2026-04-01"
- 複数レンジ: 期間比較も可能
Search Console のsearchanalytics実装
service = self._get_service()
request_body = {
"startDate": start_date,
"endDate": end_date,
"dimensions": ["query", "page"],
"rowLimit": 25000, # 最大25000
"startRow": 0,
}
response = service.searchanalytics().query(
siteUrl=self.site_url,
body=request_body,
).execute()
Search Console の制約
- 最大16ヶ月のデータ: それ以上古いデータは取得不可
- 1リクエスト最大25,000行: それ以上はページネーション必須
- データ欠損: プライバシー保護のため一部のクエリは取得できない
- 遅延: 2〜3日前のデータが最新
大量データのページネーション対応
GSCは25,000行ずつしか取得できないため、大規模サイトでは`startRow`をずらしながら複数回呼び出す必要がある。
all_rows = []
start_row = 0
row_limit = 25000
while True:
request_body["startRow"] = start_row
request_body["rowLimit"] = row_limit
response = service.searchanalytics().query(
siteUrl=site_url, body=request_body,
).execute()
rows = response.get("rows", [])
all_rows.extend(rows)
if len(rows) < row_limit:
break # これ以上データなし
start_row += row_limit
if start_row >= 100000: # 安全ガード
break
AI分析との統合
GA4/GSCデータを取得するだけでは価値がない。以下のAI分析と連携することで本格的な価値が生まれる。
AI連携の典型パターン
- 順位低下検知: GSCの順位データを前週比で比較し、急落ページを検出
- SEOレポート自動生成: GA4/GSCデータをLLMで要約
- リライト対象の自動選定: 表示回数高・CTR低のページを抽出
- コンテンツギャップ分析: GSCクエリから未対応トピックを発見
- コンバージョンパス分析: GA4のユーザー行動経路から改善点抽出
BigQuery経由の代替手段
API直接呼び出しには以下の制約がある。
- GA4: サンプリングが発生する場合がある
- GSC: 16ヶ月より古いデータが取れない
- 両方: レート制限あり
大規模データ分析ではBigQueryエクスポート経由の方が適している場合がある。
- GA4 BigQuery Export: 標準機能で無料(一定量まで)
- Search Console BigQuery Export: 2023年から正式対応
- 長期データ分析: 16ヶ月超のSEO推移分析
- 大量データ処理: 数百万行の分析がSQLで可能
renueの実装特徴
renueは「Self-DX First」の方針のもと、GA4/GSC API統合を自社プロダクトとして実装している。社内12業務を553のAIツールで自動化済み(2026年1月時点)であり、SEOエージェント等と連携している(全て公開情報)。
技術スタック
- 言語: Python 3.11
- GA4: google-analytics-data (BetaAnalyticsDataClient)
- GSC: google-api-python-client
- 認証: サービスアカウント
- dataclass設計: GA4MetricsData / SearchConsoleRow / SearchConsoleData
- 遅延初期化: @propertyによるクライアントキャッシュ
- エラー階層: GA4ClientError / SearchConsoleClientError
導入時のよくある失敗パターン
- GA4/GSC側での権限付与を忘れる: 認証は通るがデータが取れない
- private_keyの改行を修正しない: 環境変数経由の認証が失敗
- 遅延初期化を実装しない: テストでモック差し込みできない
- dataclassを使わない: 型が曖昧で呼び出し側にバグ
- GSCページネーションを考慮しない: 大規模サイトでデータが欠落
- date_rangesの柔軟性を活用しない: 期間比較が面倒になる
- サンプリングに気付かない: GA4の大量データで精度が下がる
- BigQueryエクスポートを検討しない: 古いデータが取れず後悔
業界別の活用パターン
| 業界 | 主な活用 |
|---|---|
| メディア | 記事別PV分析、リライト対象選定 |
| EC | 商品ページCVR分析、流入経路分析 |
| BtoB SaaS | LPCVR分析、キーワード流入分析 |
| 不動産 | 物件ページの人気度分析、エリア別流入 |
| 採用 | 求人ページPV、応募コンバージョン分析 |
| 観光 | 季節別流入、キーワードトレンド分析 |
よくある質問
サービスアカウントとOAuth 2.0どちらが良い?
本番のバッチ処理・Webアプリはサービスアカウント、ユーザー個別のダッシュボードはOAuth 2.0が適している。renueの実装はバッチ・分析基盤向けのためサービスアカウントを採用している。
GA4のサンプリングを避ける方法は?
BigQueryエクスポートを使う。Data API経由では大量データでサンプリングが発生することがあるが、BigQueryなら全データが使える。無料枠も大きい。
Search Consoleの16ヶ月制限を超えるには?
2023年から提供されているSearch Console BigQueryエクスポートを使う。毎日のデータが自動的にBigQueryに蓄積されるため、時間が経てば16ヶ月超のデータも保持できる。
private_key修正が必要な理由は?
環境変数はJSONをエスケープする際に改行が`\n`(文字列)になることが多い。Googleのライブラリは実際の改行を期待するため、変換が必要。この問題に気付かず「認証が通らない」とハマる本番実装が多い。
導入後に最も改善するKPIは?
「SEO分析レポート作成時間」が最も改善する(手動数時間 → AI自動生成数分)。次いで「順位低下検知までの時間」「リライト候補の抽出精度」が改善する。人間は戦略判断に集中できるようになる。