Search Console APIを使う前に、管理画面で取得したい条件を一度確認します。対象プロパティ、期間、検索タイプ、集計軸が決まっていないと、データを取得できても何を表す表か分かりません。
最初に管理画面のプロパティ識別子とAPIのsiteUrlを一致させることを確認します。URLプレフィックスとドメインプロパティでは指定の形式が異なります。
権限と取得条件をそろえる
searchanalytics.queryにはOAuthの認可が必要です。読み取りではwebmasters.readonlyスコープを使えるため、APIキーだけで自分の検索データを取得できる前提にしません。認証したユーザーが対象プロパティへアクセスできるかも確認します。
| 項目 | 確認する値 |
|---|---|
| siteUrl | https://example.com/ または sc-domain:example.comなど |
| 期間 | startDateとendDate、PT基準 |
| 検索タイプ | type=webなど目的に合う対象 |
| 集計軸 | page、query、date等と並び順 |
| データ状態 | 確定値だけか暫定値を含めるか |
| 取得範囲 | rowLimit、startRow、絞り込み条件 |
日付は日本時間の日界と同じではありません。公式仕様のPTを基準にし、他の計測データと日別比較するときも基準を記録します。
リクエストの形をローカルで確認する
次はリクエスト本文の例です。JSONの形式を確認するもので、実プロパティへの送信は行いません。プロパティ識別子はURL側で指定し、この本文には含めません。
{
"startDate": "2026-09-01",
"endDate": "2026-09-30",
"dimensions": ["page", "query"],
"type": "web",
"rowLimit": 1000,
"startRow": 0,
"dataState": "final"
}応答のkeysは指定したdimensionsの順に読みます。APIのctrは0〜1の値なので、パーセント表示にするときは100倍します。
全件取得と誤解しない
rowLimitは最大25,000で、startRowを使ってページを進められます。ただし、APIはすべてのデータ行の返却を保証していません。取得できた範囲の上位データと、全検索行が同じとは扱いません。
行がゼロなら、期間、フィルタ、プロパティ、データの有無を確認します。データが返らないことだけで検索需要がないと結論付けず、管理画面でも同じ条件を照合してください。
保存する際は取得日時、条件、取得行数、集計方法も残します。異なる条件の表を同じデータとして連結しないことが、後のCTR比較や記事選定を誤らないために必要です。
