キーワード照会API (/keyword_info) 活用ガイド

Keyword Info APIは、特定のキーワードに関する検索ボリューム、広告競合度、SERP構造、検索意図、ユーザー人口統計などの情報を1回のリクエストで総合照会するエンドポイントです。最大1,000個のキーワードを同時に処理できます。

核心特徴まとめ

項目	詳細
エンドポイント	POST /keyword_info
リクエストキーワード数	最小1個 / 最大1,000個（配列）
返却件数	リクエストキーワード数と同一（1:1対応）
対応国（gl）	kr（韓国）/ jp（日本）/ us（米国）
data_type	ads_metrics, monthly volume, features(SERP), intents, demography
課金方式	入力キーワード1個あたり10クレジット（出力課金なし）

キーワード照会(/keyword_info) APIはいつ使うか

ユーザーの問い	使用指標
市場規模の判断 このキーワードをどれだけ検索していますか？	volume_avg, volume_total
成長/下落トレンドの把握（3ヶ月基準の増減率） 検索量は増えていますか、減っていますか？	volume_trend
Google/Naver チャネル比率の比較 GoogleとNaverのどちらで多く検索されていますか？	gg_volume_avg, nv_volume_avg
広告難易度・コストの推定 広告を出稿した場合、競合は激しいですか？	competition_index, cpc
コンテンツSEO どのコンテンツフォーマットが検索結果に表示されますか？	features (f_images, f_video_results など)
コンテンツ・広告戦略の方向性決定 このキーワードで検索する人の目的は何ですか？	intents (i, n, c, t)
ターゲットオーディエンスのプロファイリング 主な検索ユーザー層は誰ですか？	demography (m/f_gender_ratio, a30_ratio など)
季節性分析、広告出稿タイミングの決定 月別検索量の推移を見たい。	monthly_volume（data_type: ads_info または all）

リクエストパラメーター (Request)

パラメーター詳細

パラメーター	タイプ	必須	デフォルト値	説明
keywords	array[string]	Y	–	照会するキーワードリスト（1〜1,000個）。英語は小文字推奨
gl	string	Y	–	国コード。"kr" / "jp" / "us" のいずれか
data_type	string	N	ads_metrics	返却データ範囲の選択（下表参照）

data_typeの選択基準

data_type値	含まれるデータ	推奨状況
ads_metrics（デフォルト）	検索ボリューム、CPC、広告競合度	素早い検索ボリューム・競合度の確認のみ必要な場合
ads_info	ads_metrics + 月別検索ボリューム	季節性・トレンド分析が必要な場合
all	ads_metrics + 月別 + SERP + 意図 + 人口統計	ターゲティング・コンテンツ戦略の総合分析時

data_type別返却フィールドまとめ

フィールドグループ	ads_metrics	ads_info	all
ads_metrics（検索ボリューム・広告）	O	O	O
monthly_volume（月別検索ボリューム）	X	O	O
features（SERP表示）	X	X	O
intents（検索意図）	X	X	O
demography（人口統計）	X	X	O

リクエスト例

単一キーワード照会

{
"keywords": ["lg 冷蔵庫"],
"gl": "jp"
}

複数キーワード + 全データ照会

{
"keywords": ["lg 冷蔵庫", "サムスン 冷蔵庫", "冷蔵庫 おすすめ"],
"gl": "jp",
"data_type": "all"
}

✔ 英語キーワードは小文字で入力してください。

レスポンスデータ構造 (Response)

レスポンスデータ構造概要

最上位フィールド	タイプ	説明
result	string	"OK" または "FAILED"
reason	string	"SUCCESS" またはエラーメッセージ
request_detail	object	リクエストパラメーターのエコー
cost_detail	object	入出力クレジットの詳細（input_cost: 10 × キーワード数）
used_credits	integer	リクエスト後の累計クレジット
data	array	キーワード別分析結果の配列（核心データ）

data[ ] 内部構造

フィールド	含まれる条件	説明
keyword	常時	リクエストキーワード
ads_metrics	常時	検索ボリューム・CPC・広告競合度
features	data_type: all	Google SERP表示タイプ
intents	data_type: all	検索意図（I/N/C/T）
demography	data_type: all	性別・年齢分布
monthly_volume	data_type: ads_info または all	月別Google/Naver検索ボリューム（最大48ヶ月）

主要指標の解釈

検索需要・広告指標（ads_metrics）

指標名	説明	解釈のポイント
volume_avg	直近3ヶ月の月平均検索ボリューム（Google+Naver合算）	10万以上: 大型キーワード / 1万未満: ニッチキーワード
volume_total	直近12ヶ月の総検索ボリューム	市場規模の定量化に活用
volume_trend	3ヶ月前比の直近月増減率	正数: 上昇 / 負数: 下落（例: -0.22 = 22%減少）
gg_volume_avg	Google月平均検索ボリューム	Google/Naver比率でチャネル戦略を策定
nv_volume_avg	Naver月平均検索ボリューム	韓国ではNaver比率が高い場合が多い
competition	広告競合強度ラベル	LOW(0〜33) / MEDIUM(34〜66) / HIGH(67〜100)
competition_index	広告競合度の数値（0〜100）	高いほど広告入札競争が激しい
cpc	クリックあたりの広告費用（USD）	高いほど商業的価値の高いキーワード
low_bid_micros	低い入札価格（マイクロ単位）	広告最小予算の算定に参考
high_bid_micros	高い入札価格（マイクロ単位）	競争的入札時の必要予算の推定

✔ 韓国（gl: kr）基準のvolume_avg/total/trendはGoogle + Naver合算値です。Google単独の数値はgg_、Naver単独の数値はnv_フィールドをご使用ください。

SERP表示指標（features）

Google検索結果ページにどのようなタイプのコンテンツがどれだけ表示されるかを示します。

カテゴリー	主要フィールド	解釈
AI Overview	f_ai_overview	1の場合AI Overviewが表示。SEO戦略の見直しが必要
広告（Ads）	f_ads_top, f_ads_bottom	上部/下部広告ブロック数。値が大きいほど商業的なキーワード
オーガニック結果	f_organic_results	一般ウェブ文書の結果数。SEOの機会の測定に活用
Featured Snippet	f_featured_snippet	1の場合スニペットが占有中。ブログ/コンテンツ最適化の機会
People Also Ask	f_people_also_ask_for	関連質問の表示。FAQコンテンツ企画に活用
画像・動画	f_images, f_video_results	メディアコンテンツ需要あり。画像/動画制作を検討
Knowledge Panel	f_knowledge_panel	ブランド・人物関連キーワードの可能性
Local Results	f_local_results	地域基盤キーワードの特性。ローカルマーケティングと連携

検索意図（intents）指標

検索意図（情報型、移動型、商業型、取引型）を以下のように区分します。該当の意図が有意に現れているかどうかを1または0で返します。複数の意図が同時に存在する場合があります。

コード	意図タイプ	説明	活用戦略
i（I）	Informational（情報型）	製品・カテゴリー情報の取得を目的とした検索	ブログ、ガイド、FAQコンテンツ
n（N）	Navigational（移動型）	特定サイト・ブランド・場所への移動	ブランド検索の最適化
c（C）	Commercial（商業型）	購入前の比較・レビュー・おすすめ探索	比較ページ、レビューコンテンツ
t（T）	Transactional（取引型）	購入・申込みを目的とした検索	ランディングページ、転換最適化

ユーザー人口統計（demography）指標

標準偏差（1シグマ）以上で特定の性別・年齢層の検索比率が高い場合にフラグ（1/0）を返します。

フィールドタイプ	フィールド名の例	説明
フラグ（1/0）	m_gender, f_gender, a20, a30, a40…	1の場合、該当集団の検索比率が統計的に有意に高い
比率（%）	m_gender_ratio, f_gender_ratio, a30_ratio…	全検索量における該当集団の比率（単位：%）

年齢層別コード対応表

フィールド名	年齢範囲
a0	12歳以下
a13	13〜19歳
a20	20〜24歳
a25	25〜29歳
a30	30〜39歳
a40	40〜49歳
a50	50歳以上

月別検索ボリューム（monthly_volume）指標

最大48ヶ月（4年）間の月別Google・Naver検索ボリュームを提供します。季節性・成長性分析に活用します。

フィールド	説明
month	基準月（形式: YYYY-MM、例: 2025-08）
gg	該当月のGoogle検索ボリューム
nv	該当月のNaver検索ボリューム
total	Google + Naver合算検索ボリューム

✔ 月別検索ボリュームデータは、季節別の需要予測、広告予算の配分、コンテンツ公開タイミングの決定に有効です。例：夏季エアコンキーワードの5〜7月急増パターンの確認。

活用シナリオ別パラメーター組み合わせ

目的に応じてdata_typeを選択することで、不要なデータの受信と分析の複雑さを軽減できます。

目的	推奨data_type	核心確認指標	課金（キーワードあたり）
市場規模の素早い把握	ads_metrics	volume_avg, volume_total	10クレジット
広告効率の事前分析	ads_metrics	competition_index, cpc, high_bid_micros	10クレジット
プラットフォーム別チャネル戦略	ads_metrics	gg_volume_avg vs nv_volume_avg	10クレジット
季節性・トレンド分析	ads_info	monthly_volume, volume_trend	10クレジット
SEOコンテンツ企画	all	f_organic_results, f_ai_overview, f_featured_snippet	10クレジット
ターゲットオーディエンスの設定	all	demography（f_gender_ratio, a30_ratio など）	10クレジット
検索意図基盤のメッセージ設計	all	intents（i, c, t の組み合わせ）	10クレジット
総合キーワード戦略の策定	all	全指標の統合分析	10クレジット

⚠ 課金はdata_typeにかかわらず、入力キーワードあたり一律10クレジットです。ただし、1回のリクエストで全データを収集できるため、「all」で1回収集後、分析目的に応じてフィールドを選択的に使用すると効率的です。

全体レスポンス例

以下は「OO 冷蔵庫」キーワードに対する実際のレスポンス構造の例です。

Request

{
"keywords": ["OO 冷蔵庫"],
"gl": "jp",
"data_type": "all"
}

Response

{
"result": "OK",
"reason": "SUCCESS",
"cost_detail": { "input_cost": 10, "total_cost": 10 },
"remain_credits": 99990,
"data": [{
"keyword": "OO 冷蔵庫",
"ads_metrics": {
  "competition": "HIGH",  "competition_index": 93,
  "cpc": 0.87,
  "volume_avg": 304333,   "volume_total": 3271400,  "volume_trend": -0.22,
  "gg_volume_avg": 56833, "nv_volume_avg": 247500
},
"features": {
  "f_ai_overview": 1, "f_organic_results": 18,
  "f_ads_top": 2,     "f_featured_snippet": 1
},
"intents": { "i": 1, "n": 0, "c": 0, "t": 1 },
"demography": {
  "f_gender": 1,  "f_gender_ratio": 55.76,
  "a30": 1, "a40": 1, "a30_ratio": 26.12, "a40_ratio": 33.40
},
"monthly_volume": [
  { "month": "2025-08", "gg": 108000, "nv": 261000, "total": 369000 },
  { "month": "2025-09", "gg": 112000, "nv": 268000, "total": 380000 }
]
}]
}

レスポンスデータの解釈まとめ（上記例基準）

分析領域	解釈（推定含む）	備考
市場規模	月平均約30.4万件の検索（Google+Naver）	事実: API返却値基準
プラットフォーム比率	Naver約81%（247,500 / 304,333）	推定: Google+Naver合算基準で算出
検索トレンド	3ヶ月前比約22%減少（volume_trend: -0.22）	事実: API返却値基準
広告競合	非常に激しい（competition_index: 93/100）	事実: API返却値基準
広告費用	クリックあたり約$0.87 USD	事実: API返却値基準
SERPの特記事項	AI Overview表示中 → オーガニッククリック率への影響の可能性	推定: SERP構造変化に関連
検索意図	情報探索（i=1）と購買（t=1）の意図が共存	事実: API返却値基準
主要ユーザー	女性（55.76%）、30〜40代（合算約59.5%）	事実: API返却値基準

⚠ 「推定」表示の項目はAPI返却値を組み合わせ・計算した結果であり、実際の市場状況と異なる場合があります。「事実」表示の項目のみAPIの直接返却値です。

エラーレスポンスの処理

4xx/5xxエラー発生時はクレジットは課金されません。

HTTP Status	エラー種別	主な原因	対処方法
401 Unauthorized	認証失敗	APIキー未入力または無効なキー	LM-API-KEYヘッダーの値を確認
402 Payment Required	クレジット不足	remain_creditsが不足	クレジットをチャージ後に再リクエスト
403 Forbidden	権限なし	該当エンドポイントへのアクセス権限なし	契約プランを確認
422 Unprocessable Entity	パラメーターエラー	gl値エラー、keywordsの形式エラーなど	detailフィールドのエラーメッセージを確認
429 Too Many Requests	レート制限超過	短時間での過多リクエスト	リクエスト速度を調整後に再試行
500 Internal Server Error	サーバーエラー	ListeningMindサーバーの内部問題	ListeningMindテクニカルサポートに問い合わせ

よくある質問 (FAQ)

Q1. keywords配列に1,000個を入れると、レスポンスも1,000件ですか？

はい。Keyword Infoはリクエストキーワード数とレスポンス数が1:1で対応します。ただし、keywords配列のサイズが返却件数を決定し、別途limitパラメーターはサポートしていません。

Q2. volume_avgはどの期間を基準にしていますか？

直近3ヶ月の月別検索ボリュームの平均値です。volume_totalは直近12ヶ月の合算です。過去の特定時点のデータが必要な場合は、monthly_volumeフィールド（data_type: ads_info または all）をご活用ください。

Q3. GoogleとNaverの検索ボリューム合算基準は韓国（kr）のみですか？

はい。現在Google+Naver合算の検索ボリューム（volume_avg, volume_total, volume_trend）は、韓国（gl: kr）基準でのみ提供されます。日本（jp）、米国（us）はGoogleのみの提供となります。

Q4. features、intents、demographyがレスポンスに含まれていません。

data_typeを「ads_metrics」（デフォルト値）または「ads_info」に設定した場合、features/intents/demographyフィールドは返却されません。このデータが必要な場合は、data_type: "all"を明示する必要があります。

Q5. エラーが発生してもクレジットは課金されますか？

いいえ。4xxまたは5xxのHTTPレスポンスコードでエラーが発生した場合、入力・出力ともに課金されません。ただし、200正常レスポンスでも特定キーワードのデータがnullや空配列の場合は課金が発生します。

Q6. monthly_volumeは最大何ヶ月分を受け取れますか？

最大48ヶ月（4年）分のデータを提供します。ただし、データ収集開始時点によって実際に返却される月数が異なる場合があります。