Intent Finder APIは、入力したシード（seed）キーワードと実際に一緒に検索される関連キーワードリストを返します。消費者が同一の検索セッションで一緒に探索するキーワードを基盤としているため、単純な類似キーワードではなく、実際の検索意図を反映した拡張キーワードを確保できます。
核心特徴まとめ
| 項目 | 詳細 |
|---|---|
| エンドポイント | POST /intent_finder/keyword_list |
| リクエストキーワード数 | 最小1個 / 最大100個（配列） |
| 返却形式 | data: string[]（単純キーワード文字列配列） |
| デフォルト返却件数 | 100件 |
| 最大返却件数 | 10,000件（limitパラメーターで制御） |
| 対応国（gl） | kr（韓国）/ jp（日本）/ us（米国） |
| 課金方式 | 入力キーワード1個あたり30クレジット + 出力キーワード1個あたり2クレジット |
関連クエリ抽出API(/intent_finder/keyword_list) いつ使うか
| ユーザーの問い | 活用方向 |
|---|---|
| このキーワードと一緒によく検索されるキーワードは何ですか？ | シードキーワード基盤の関連キーワード拡張 |
| SEOのロングテールキーワードを探したい。 | volume_thresholdを下げてニッチキーワードを発掘 |
| 広告グループを細分化するキーワードが必要です。 | 複数シードキーワードで広告グループ別に拡張 |
| コンテンツのテーマを広げたい。 | 関連キーワードプールを確保後クラスタリング |
| トレンドが上昇中の関連キーワードを探したい。 | sort: volume_trend、order: desc を設定 |
リクエストパラメーター (Request)
パラメーター詳細
| パラメーター | タイプ | 必須 | デフォルト値 | 説明 |
|---|---|---|---|---|
| keywords | array[string] | Y | – | シードキーワードリスト（1〜100個）。英語は小文字推奨 |
| gl | string | Y | – | 国コード: "kr" / "jp" / "us" |
| volume_threshold | integer | N | 100 | 返却キーワードの最小検索量フィルター。この値未満のキーワードを除外 |
| limit | integer | N | 100 | 返却キーワード数の制限（1〜10,000） |
| sort | string | N | volume_avg | ソート基準: volume_avg / volume_total / volume_trend / cpc / competition_index |
| order | string | N | desc | ソート方向: desc（降順）/ asc（昇順） |
探索範囲の調整 – volume_threshold（検索量閾値）の設定
| 設定値 | 効果 | 推奨状況 |
|---|---|---|
| 100（デフォルト） | 一定需要以上のキーワードのみ返却 | 実務向け広告・SEOキーワードの確保 |
| 10以下 | 少量検索のロングテールも含む | ニッチ市場探索、新造語の発掘 |
| 1,000以上 | 高需要キーワードのみ返却 | 大型カテゴリーの核心キーワードのみ必要な場合 |
返却件数の調整 – limit
| 設定値 | 効果 | 出力課金 |
|---|---|---|
| 100（デフォルト） | 素早い探索、コスト削減 | 200クレジット |
| 500 | 実務向けSEO/広告キーワードを十分確保 | 1,000クレジット |
| 10,000（最大） | 全関連キーワードプールの収集 | 20,000クレジット |
✔ 実務ではlimit: 100〜500がコスト対効果が高いです。初期探索はデフォルト値（100）から始め、キーワードプールの拡張が必要な際に増やしてください。
目的別ソート基準の設定 – sort
| sort値 | ソート基準 | 推奨状況 |
|---|---|---|
| volume_avg（デフォルト） | 月平均検索量の高い順 | 主要大型キーワードを優先確認 |
| volume_total | 年間総検索量の高い順 | 季節性のあるキーワードを含む場合 |
| volume_trend | 検索量増減率の高い順 | 急上昇トレンドキーワードの発掘 |
| cpc | クリック単価の高い順 | 商業的価値の高いキーワードを優先 |
| competition_index | 広告競合度の高い順 | 競合キーワードの把握 |
リクエスト例
基本リクエスト
{
"keywords": ["OO 冷蔵庫"],
"gl": "jp"
}複数シードキーワード + 詳細オプション
{
"keywords": ["OO 冷蔵庫", "{競合他社} 冷蔵庫"],
"gl": "jp",
"volume_threshold": 500,
"limit": 300,
"sort": "volume_avg",
"order": "desc"
}レスポンスデータ構造 (Response)
レスポンスデータ構造概要
| フィールド | タイプ | 説明 |
|---|---|---|
| result | string | "OK" または "FAILED" |
| cost_detail | object | 入力クレジット（30 × シード数）+ 出力クレジット（2 × 返却キーワード数） |
| used_credits | integer | リクエスト後の残クレジット |
| data | array[string] | 関連キーワード文字列配列（核心結果） |
レスポンス例
{
"result": "OK",
"cost_detail": { "input_cost": 30, "output_cost": 20, "total_cost": 50 },
"remain_credits": 99950,
"data": [
"OO 冷蔵庫 オブジェ", "OO 冷蔵庫 価格",
"OO 冷蔵庫 おすすめ", "OOO 冷蔵庫",
"OO 冷蔵庫 口コミ"
]
}課金構造の詳細
| 区分 | 基準 | 単価 | 計算例 |
|---|---|---|---|
| 入力課金 | シードキーワード1個あたり | 30クレジット | シード3個 → 90クレジット |
| 出力課金 | 返却キーワード1個あたり | 2クレジット | 結果100件 → 200クレジット |
| 合計例 | シード3個、結果100件 | 290クレジット | 90 + 200 = 290クレジット |
✔ 4xx/5xxエラー時は入力・出力ともに課金されません。200正常レスポンスでも結果が空配列の場合は入力課金が発生します。
| シナリオ | シード数 | limit | 予想総クレジット（結果フル想定） |
|---|---|---|---|
| 素早い探索 | 1 | 100 | 230クレジット |
| 実務SEO作業 | 5 | 300 | 3,150クレジット |
| 大規模収集 | 10 | 1,000 | 20,300クレジット |
活用シナリオ
SEOロングテールキーワードの発掘
| 段階 | 作業 | パラメーター設定 |
|---|---|---|
| 1. シードの設定 | カテゴリー核心キーワード1〜5個 | keywords: ["キーワード1", …] |
| 2. フィルター調整 | 低いthresholdでロングテールを含む | volume_threshold: 50, limit: 500 |
| 3. トレンド優先 | 上昇中のキーワードを選別 | sort: "volume_trend", order: "desc" |
| 4. 深層分析 | 有望キーワードの詳細照会 | /keyword_infoに結果キーワードを入力 |
後続分析の連携ワークフロー
| 連携API | 活用方法 | 得られるインサイト |
|---|---|---|
| /keyword_info | Intent Finderの結果をkeywords[]に入力 | 検索ボリューム、CPC、SERP、意図、人口統計の確認 |
| /cluster_finder | 関連キーワードをクラスター分析シードとして活用 | キーワード関係網と消費者認識グループの把握 |
| /path_finder | 関連キーワードで検索ジャーニーを分析 | 該当キーワードの前後探索経路の確認 |
✔ 推奨ワークフロー: ① Intent Finderでキーワードプールを収集 → ② /keyword_infoで優先順位を選別 → ③ /cluster_finderで認識グループ化 → コンテンツ・広告セグメントの導出
エラーレスポンスの処理
| HTTP Status | 主な原因 | 対処方法 |
|---|---|---|
| 401 Unauthorized | APIキー未入力または無効 | LM-API-KEYヘッダーを確認 |
| 402 Payment Required | クレジット不足 | 残クレジットを確認後チャージ |
| 422 Unprocessable Entity | gl値エラー、パラメーター形式エラー | detailフィールドのエラー箇所を確認 |
| 429 Too Many Requests | レート制限超過 | リクエスト速度を調整後に再試行 |
| 500 Internal Server Error | サーバー内部エラー | テクニカルサポートに問い合わせ |
よくある質問 (FAQ)
Q1. シードを100個入力した場合、各シードの関連キーワードが個別に返却されますか？
いいえ。複数シードを入力した場合、統合された単一の配列で返却されます。シード別の個別結果が必要な場合は、APIを複数回呼び出してください。
Q2. 返却されたキーワードに無関係なキーワードが多く含まれています。
場合によって含まれることがあります。現在APIレベルでのフィルタリングは不可です。呼び出し後にフィルタリング作業を行うことを推奨します。
Q3. 結果のソート基準（sort）は実際の返却順序を保証しますか？
はい。sortパラメーターの基準でソートされた順序で返却されます。配列の前方に位置するキーワードが該当基準で高い値を持ちます。正確な数値の確認が必要な場合は /keyword_info を追加で呼び出してください。
