Search Console APIをサービスアカウントで使う

「Google Search Console のデータを Python で自動取得したい」――そう思って調べ始めると、サービスアカウント？ OAuth？ APIキー？ と、いきなり選択肢の多さに手が止まります。

さらに設定した通りに動かしたはずなのに 403（アクセス禁止）で弾かれる、という壁も待っています。この記事では、Search Console API をサービスアカウント方式でセットアップし、Python でデータが返ってくるところまでを、つまずきポイントを先回りしながら解説します。

この記事で分かること：

1. Search Console API と Indexing API の違い（混同しやすい）
2. なぜ「サービスアカウント」を選ぶのか
3. Google Cloud 側の設定手順（プロジェクト作成〜JSONキー発行）
4. なぜ Google Cloud だけでなく Search Console 側の設定も必要なのか
5. Python での疎通確認と、403 が出たときの切り分け

前提：この記事のゴール

ゴールは「Python を実行したら、自分のサイトの検索クエリと表示回数・クリック数・掲載順位が返ってくる」状態です。取得したデータを分析・活用する方法は範囲を広げすぎるため、別記事で扱います。

まずは「配線を通してデータが流れることを確認する」ところまでを、確実に到達させます。

Search Console API と Indexing API は別物です

最初に、多くの人が混同する2つの API を区別しておきます。名前が似ていて、Google Cloud での設定手順もほぼ同じなので、検索するとどちらの記事も入り混じって出てきます。しかし用途はまったく別です。

つまり Search Console API は「見る」ための API、Indexing API は「知らせる」ための API です。今回やりたいのは検索パフォーマンスのデータ取得なので、使うのは Search Console API です。

なぜ「サービスアカウント」を選ぶのか

Google Cloud で認証情報を作る画面には、3種類の選択肢が並びます。

OAuth を選ぶと、実行のたびにブラウザが立ち上がって同意を求められます。定期実行のように人がいない場面では、そこで処理が止まってしまいます。一方サービスアカウントは、プログラム自身が持つ専用のアカウントで、同意画面を経由せずに動くため自動実行に向いています。

Google Cloud 側の設定

ステップ1：プロジェクトを作成する

Google Cloud Console（https://console.cloud.google.com/）にアクセスし、新しいプロジェクトを作成します。この記事ではプロジェクト名を GSCAPI としています。

プロジェクトの作成

今回プロジェクト名：GSCAPI

ステップ2：Search Console API を有効化する

左メニューの「APIとサービス」→「有効なAPIとサービス」を開く

「+ APIとサービスを有効にする」をクリック

検索窓に「Google Search Console API」と入力して検索

「Google Search Console API」を選択

「有効にする」を押下

ステップ3：認証情報からサービスアカウントを作成する

「認証情報」→「認証情報を作成」→「サービスアカウント」を選択。

サービスアカウント名に gsc-reader と入力します。その他の項目は未入力で構いません。

ステップ4：JSONキーを発行する

作成されたサービスアカウントの「メール」をクリック

「鍵」タブ →「鍵を追加」→「新しい鍵を作成」→ キーのタイプで JSON を選択

ボタンを押した瞬間に鍵ファイルがダウンロードされます

ステップ5：JSONキーを作業ディレクトリに配置する

ダウンロードした鍵を、これから使うプロジェクトのフォルダへ移動します（パスは環境に合わせてください）。

mkdir -p ~/Desktop/claude/keyword-hunter/credentials
mv ~/Downloads/GSCAPI-xxxxxxxx.json ~/Desktop/claude/keyword-hunter/credentials/service-account.json
cat ~/Desktop/claude/keyword-hunter/credentials/service-account.json | grep client_email

最後のコマンドで gsc-reader@GSCAPI-xxxxxx.iam.gserviceaccount.com のようなメールアドレスが表示されます。これをコピーしておいてください。次のステップで使います。

なぜ Search Console 側の設定も必要なのか

ここが、この設定でもっとも直感に反する部分です。Google Cloud で作業したのに、なぜ別サービスの Search Console でも設定が要るのか？ 疑問に思う人が多い箇所です。理由は、今おこなった作業とこれからおこなう作業が、まったく別の「許可」だからです。

• Google Cloud 側（完了）：API という窓口を使う権利
• Search Console 側（これから）：このサイトのデータを見る権利

Google Cloud 側の設定は、銀行の「窓口システムを操作できる行員証」を発行するようなものです。しかし行員証を持っていても、口座の持ち主が「この行員に見せてよい」と許可しなければ、他人の口座は見られません。Search Console も同じで、サイトの持ち主が明示的に招待しない限り、誰にもデータを見せません。

さらに重要なのが、サービスアカウントは「あなた自身」とは別のアカウントだという点です。あなたが Search Console のオーナーであっても、gsc-reader@... というサービスアカウントは、Search Console から見れば初対面の他人です。この「他人」を招待して初めて、データを読めるようになります。

Google Search Console（https://search.google.com/search-console）を開き、対象プロパティを選択して以下の手順を進めます。

左メニュー最下部の「設定」をクリック

「ユーザーと権限」を選択

「ユーザーを追加」をクリック

コピーしたサービスアカウントのメールアドレスを貼り付け、権限を「制限付き」にして「追加」

ユーザーが追加されたことを確認

Python で疎通確認する

まずは必要なライブラリをインストールします。

cd ~/Desktop/claude/keyword-hunter
pip3 install google-auth google-api-python-client

続いて、確認用のスクリプト gsc_test.py を用意します。

"""
GSC API 疎通確認スクリプト
使い方: python gsc_test.py
"""
from google.oauth2 import service_account
from googleapiclient.discovery import build
from datetime import date, timedelta

# ── 設定 ──────────────────────────────
CREDENTIALS = "./credentials/service-account.json"

# プロパティの指定形式に注意（後述）
PROPERTY = "https://example.com/"
# ──────────────────────────────────────

SCOPES = ["https://www.googleapis.com/auth/webmasters.readonly"]

creds = service_account.Credentials.from_service_account_file(
    CREDENTIALS, scopes=SCOPES
)
service = build("searchconsole", "v1", credentials=creds)

# 直近28日・上位5クエリだけ取得してみる
end = date.today() - timedelta(days=2)
start = end - timedelta(days=28)

request = {
    "startDate": start.isoformat(),
    "endDate": end.isoformat(),
    "dimensions": ["query"],
    "rowLimit": 5,
}

resp = service.searchanalytics().query(siteUrl=PROPERTY, body=request).execute()

rows = resp.get("rows", [])
if not rows:
    print("接続は成功したが、データが0件。期間やプロパティを確認してください。")
else:
    print(f"接続成功！ 上位{len(rows)}クエリ:\n")
    for r in rows:
        q = r["keys"][0]
        print(f"  {q}  表示{int(r['impressions'])}  "
              f"クリック{int(r['clicks'])}  順位{r['position']:.1f}")

プロパティの指定形式に注意してください。PROPERTY の値は、プロパティの種類によって書き方が変わります。ここを間違えると 403 かデータ0件になります。

Search Console の左上に表示されているプロパティ名を見て、どちらの形式かを確認してください。スクリプトを実行します。

python gsc_test.py

次のように、クエリと数値が表示されれば設定は成功です。

接続成功！ 上位5クエリ:
  eclipse jar 作成  表示50  クリック32  順位1.1
  insightface  表示308  クリック18  順位5.9
  ...

403 が出たときの切り分け

設定した通りに進めても 403 が出ることがあります。原因は主に次の4つです。上から順に確認してください。

特に ① と ③ が二大原因です。「Google Cloud 側は完璧なのに 403」という場合、ほぼ Search Console 側の追加漏れか、プロパティ形式の不一致です。

まとめ

• Search Console API は「見る」ための API。「知らせる」Indexing API とは別物
• 自動実行にはサービスアカウントを選ぶ。OAuth ではない
• ロール付与は空でよい。閲覧権限は Search Console 側で付ける
• Google Cloud 側と Search Console 側、両方の許可が揃って初めて動く
• 403 の二大原因は「Search Console への追加漏れ」と「プロパティ形式の不一致」

これでデータを取得できるようになりました。この API を使えば「どの既存記事をリライトすれば検索順位が伸びるか」を数字で判断することができます。掲載順位11〜30位の記事を機械的に洗い出し、優先度をつけて改善していく――その具体的な方法は、次回の記事で解説します。

参考リソース

• Search Console API 公式ドキュメント（認証）
• Updates to Search Console’s API（Google 公式ブログ）
• 【Python】pyenvとvenvの違いと併用方法