1. API概要
本ドキュメントは、各エンドポイントの機能、リクエストおよびレスポンスのデータ構造を要約して説明します。
- API名: ListeningMind Data API
- OpenAPI Version: v0.0.36
- Base URL: https://listeningmind-data-api.ascentlab.io
- 認証方式: Header, LM-API-KEY
- Source: OpenAPI JSON
- 課金構造: クレジット基盤（input/output cost）
- Website: https://www.listeningmind.com
2. API項目まとめ
| Category | API Name | Method | Path | 核心機能 |
|---|---|---|---|---|
| Keyword | Keyword Info | POST | /keyword_info | キーワードメタ＋検索/広告データ |
| Intent | Intent Finder | POST | /intent_finder/keyword_list | 関連キーワードリスト |
| Journey | Path Finder | POST | /path_finder | 検索経路分析 |
| Journey | Path Finder List | POST | /path_finder/keyword_list | 経路キーワードリスト |
| Network | Cluster Finder | POST | /cluster_finder | キーワード関係/クラスター |
| Network | Cluster Finder List | POST | /cluster_finder/keyword_list | 関係キーワードリスト |
3. Requestパラメーター
3.1. 全エンドポイント共通パラメーター
| パラメーター | タイプ | 必須 | 説明 |
|---|---|---|---|
| keyword/keywords | string, string[] | ✓ | 分析対象キーワード（単一または配列）。英語キーワードは小文字推奨 |
| gl | string | ✓ | 国コード。必ず "kr"・"jp"・"us" のいずれか |
- gl（geolocation）基準の国設定： 検索ボリューム、SERP、意図、関係、コミュニティはすべてgl（kr/jp/us）基準で計算されます。
- keywords vs keyword
- 配列: /keyword_info、/intent_finder
- 単一: /path_finder、/cluster_finder
3.2. データ範囲・時点に関する共通パラメーター
| パラメーター | タイプ | デフォルト値 | 使用API | 説明 |
|---|---|---|---|---|
| time_point | string | "curr" | path_finder, cluster_finder | データ基準時点 curr / 3m / 6m / 9m / 12m |
- curr： 現在時点の消費者認識 / 検索構造
- 3m〜12m： 過去の認識・行動変化の比較用
3.3. 結果サイズ・範囲制御の共通パラメーター
| パラメーター | タイプ | デフォルト値 | 最大 | 使用API | 説明 |
|---|---|---|---|---|---|
| limit | integer | API別に異なる | API別に異なる | intent / path / cluster | 返却結果件数の制限 |
| hop | integer | 2 | 3 | cluster_finder | 関係拡張の深さ |
limit
- 小さく → 素早い探索 / コスト削減
- 大きく → 構造分析 / ネットワーク把握
hop
- 1：直接関連のみ
- 2：実務で最もよく使われるデフォルト値
- 3：探索用（複雑、コスト↑）
3.4. データ種別選択パラメーター
| パラメーター | 使用API | デフォルト値 | 説明 |
|---|---|---|---|
| data_type | keyword_info | "ads_metrics" | 返却データ範囲の選択 |
| data_type | cluster_finder | "communities" | 返却構造の選択 |
keyword_info 基準
| 値 | 含まれるデータ |
|---|---|
| ads_metrics | 検索ボリューム、CPC、競合度 |
| ads_info | ads_metrics ＋ 月別検索ボリューム |
| all | 全体（SERP、意図、人口統計を含む） |
cluster_finder 基準
| 値 | 意味 |
|---|---|
| communities | 消費者認識/文脈クラスター |
| rels | キーワード関係エッジ |
| all | 両方 |
3.5. ソート・フィルター共通パラメーター
| パラメーター | タイプ | デフォルト値 | 説明 |
|---|---|---|---|
| volume_threshold | integer | 100 | 最小検索ボリュームフィルター |
| sort | string | volume_avg | ソート基準 |
| order | string | desc | ソート方向 |
Sortオプション
- volume_avg：月平均検索ボリューム
- volume_total：年間総検索ボリューム
- volume_trend：増減率
- cpc：広告単価
- competition_index：広告競合度
3.6. 関係方向性パラメーター
| パラメーター | タイプ | デフォルト値 | 説明 |
|---|---|---|---|
| orientation | string | "UNDIRECTED" | 関係方向性 |
| 値 | 技術的な意味 | 解釈 |
|---|---|---|
| UNDIRECTED | Undirected Edge | 双方向関係 |
| NATURAL | Directed (forward) | 実際の検索フロー（中心キーワード以降） |
| REVERSE | Directed (reverse) | 逆方向フロー（中心キーワード以前） |
4. Request / Response schema
4.1. エンドポイント別必須パラメーター / 主要レスポンスデータ構造
| エンドポイント | Request | Response |
|---|---|---|
| /keyword_info | keywords: 照会するキーワードリスト［1〜1,000］ gl: 国コード（kr/jp/us）、必須 data_type: Enum: "ads_metrics" / "ads_info" / "all" ads_metrics → ads_metrics ads_info → ads_metrics, monthly_volume all → 全体 | data[]配列に各キーワードの詳細情報を含む ① ads_metrics: 広告競合度、CPC、検索ボリュームなど（competition / competition_index / cpc / 入札価格 / volume_avg・total・trend + gg_* / nv_*ごとの検索ボリューム） ※volume_avg・total・trendは韓国（gl:kr）のみGoogleとNaver検索量の合算値。日本・米国はGoogleのみ提供 ② features: SERP表示タイプのカウント ③ intents: 検索意図（i/n/c/t） ④ demography: 性別・年齢フラグ ＋ *_ratio ⑤ monthly_volume（data_type: ads_info / all 選択時のみ出力）: 月別検索量（gg/nv/total） |
| /intent_finder/keyword_list | keywords: キーワードリスト［1〜100］ gl: 国コード（kr/jp/us）、必須 volume_threshold: 検索量閾値 limit: キーワード数制限（1〜10,000） sort: ソート基準（volume_avg / volume_total / volume_trend / cpc / competition_index） order: 降順(desc) / 昇順(asc) | data: string[]（関連キーワードリスト） [デフォルト] 検索量閾値：100以上 / limit：100 / sort：volume_avg / order：desc ※キーワードの詳細指標（volume_avg・totalなど）は含まない |
| /path_finder | keyword: 経路分析の中心キーワード［1個］、必須 gl: 国コード（kr/jp/us）、必須 time_point: curr / 3m / 6m / 9m / 12m limit: 経路数制限（1〜10,000） | data: string[][]（検索経路シーケンス） 検索ジャーニーの流れ（以前→現在→以降）に基づく。繰り返し登場するキーワードは主要な探索段階・意図の候補 [デフォルト] time_point: curr / limit: 300 |
| /path_finder/keyword_list | keyword: 経路分析の中心キーワード［1個］、必須 gl: 国コード（kr/jp/us）、必須 time_point: curr / 3m / 6m / 9m / 12m limit: 経路数制限（1〜10,000） | data: string[]（経路に登場するキーワードリスト） 経路分析のキーワードプールを素早く確保（拡張・フィルタリング用） [デフォルト] time_point: curr / limit: 300 |
| /cluster_finder | keyword: 関係を分析する中心キーワード［1個］、必須 gl: 国コード（kr/jp/us）、必須 time_point: curr / 3m / 6m / 9m / 12m limit: 関係数制限（1〜10,000） hop: 拡張の深さ（1〜3） orientation: undirected / natural / reverse data_type: Enum: "communities" / "rels" / "all" | data: {rels, communities} ① rels: [source, target][] 関係エッジ。ユーザーの検索行動から生まれた接続線で、一緒に検索されたキーワードのペアを出力。※順序とは無関係 ② communities: {cluster_id: string[]} 複数のキーワードがひとつのグループ（string[]）にまとめられたデータ。消費者認識上のひとつの「テーマのかたまり」として解釈 ※hop（拡張深さ）・orientation（方向）・data_type（返却範囲）の設定に応じて出力が変わる [デフォルト] time_point: curr / limit: 500 / hop: 2 / orientation: undirected / data_type: communities |
| /cluster_finder/keyword_list | keyword: 関係を分析する中心キーワード［1個］、必須 gl: 国コード（kr/jp/us）、必須 time_point: curr / 3m / 6m / 9m / 12m limit: 関係数制限（1〜10,000） hop: 拡張の深さ（1〜3） orientation: undirected / natural / reverse | data: string[]（関係基盤キーワードリスト） rels/communities の詳細分析前に候補キーワードを素早く確保 [デフォルト] time_point: curr / limit: 500 / hop: 2 / orientation: undirected |
4.2. エンドポイント別リクエスト / 返却基準
| API | リクエストキーワード最大 | 返却デフォルト値 | 返却最大値 | 備考 |
|---|---|---|---|---|
| keyword_info | 1,000 | リクエスト数と同一 | リクエスト数と同一 | 大量分析の核心API |
| intent_finder | 100 | 100 | 10,000 | キーワード拡張 |
| path_finder | 1 | 300 | 1,000 | 検索ジャーニー |
| cluster_finder | 1 | 500 | 10,000 | 関係/認識分析 |
/keyword_info
| 区分 | 値 |
|---|---|
| リクエストキーワード数 | 最小1個 / 最大1,000個 |
| 返却単位 | キーワード単位の結果 |
| 返却件数 | リクエストキーワード数と同一 |
| デフォルト data_type | ads_metrics |
| data_type別返却範囲 | ads_metrics / ads_info / all |
- キーワードを1,000個入力 → 結果も1,000件
- 返却件数の制限は keywords 配列のサイズで制御
- 大量分析向けの核心API
/intent_finder/keyword_list
| 区分 | 値 |
|---|---|
| リクエストキーワード数 | 最小1個 / 最大100個 |
| 返却単位 | 関連キーワードリスト |
| 返却件数のデフォルト値 | 100件 |
| 返却件数の最大値 | 10,000件 |
| 返却制御パラメーター | limit |
| ソートのデフォルト | volume_avg desc |
- 1個のシードキーワード → 最大10,000件の関連キーワード
- 実務では100〜500件を推奨
- キーワード拡張 / SEO / コンテンツ企画向け
/path_finder
| 区分 | 値 |
|---|---|
| リクエストキーワード数 | 1個（単一） |
| 返却単位 | 検索経路（path） |
| 返却件数のデフォルト値 | 300件 |
| 返却件数の最大値 | 1,000件 |
| 返却制御パラメーター | limit |
- 結果1件 ＝ ひとつの検索ジャーニーシーケンス
- limit↑ → コスト・レスポンスサイズが増加
- 300件が実務の標準値
/cluster_finder
| 区分 | 値 |
|---|---|
| リクエストキーワード数 | 1個（単一） |
| 返却単位 | 関係エッジ（rels）またはコミュニティ |
| 返却件数のデフォルト値 | 500件 |
| 返却件数の最大値 | 10,000件 |
| 返却制御パラメーター | limit |
| 関係拡張の深さ | hop（デフォルト2 / 最大3） |
| デフォルト data_type | communities |
- limit ＝ 関係数（エッジ数またはキーワード数）基準
- hopが大きくなるほど結果が爆発的に増加
- hop=2 ＋ limit=300〜500が実務上の安全な設定範囲
5. Metrics
5.1. 検索需要・広告メトリクス（ads_metrics）
| Category | Metric | 説明 | Value（例） |
|---|---|---|---|
| ads_metrics | competition | 広告競合強度（LOW / MEDIUM / HIGH） | HIGH |
| competition_index | 広告競合度の数値（0〜100） | 100 | |
| cpc | クリックあたりの費用（CPC、USD基準） | 1.41 | |
| low_bid_micros | CPC_競合度低（低い入札価格） | 389992 | |
| high_bid_micros | CPC_競合度高（高い入札価格） | 3283108 | |
| volume_avg | 月平均検索ボリューム（直近3ヶ月の月別検索量平均） | 275133 | |
| volume_total | 年間総検索ボリューム（直近12ヶ月の月別検索量合算） | 3301900 | |
| volume_trend | トレンド（3ヶ月前比の直近月検索量増減率） | 0.19 | |
| gg_volume_avg | Google月平均検索量（直近3ヶ月の平均） | 36033 | |
| gg_volume_total | Google年間検索量（直近12ヶ月の合算） | 432396 | |
| gg_volume_trend | Googleトレンド（3ヶ月前比の増減率） | – | |
| nv_volume_avg | Naver月平均検索量（直近3ヶ月の平均） | 239100 | |
| nv_volume_total | Naver年間検索量（直近12ヶ月の合算） | 2869200 | |
| nv_volume_trend | Naverトレンド（3ヶ月前比の増減率） | – |
⚠️ volume_avg・volume_total・volume_trendは韓国（gl: kr）のみGoogleとNaverの合算値です。日本（jp）・米国（us）はGoogleのみの提供となります。Google単独の数値はgg_、Naver単独の数値はnv_フィールドをご参照ください。
5.2. SERP表示メトリクス（features）
該当キーワード検索時、Google検索結果ページにどのような形式のコンテンツがどれだけ表示されるかを確認します。
| Category | Metric | 説明 | Value（例） |
|---|---|---|---|
| 生成型AI要約 Features | f_ai_overview | Google SERP上部にAI Overview（生成型要約）ブロックが表示 | 1 |
| 広告（Ads）Features | f_ads_top | 検索結果上部の広告ブロック（複数）表示 | 1 |
| f_ads_bottom | 検索結果下部の広告ブロック（複数）表示 | 1 | |
| オーガニック結果 Features | f_organic_results | オーガニック検索結果の表示数（広告・特殊SERPを除く一般ウェブ文書数） | 17 |
| f_organic_results_rating | 星評価（rich rating）を含むオーガニック結果数 | 3 | |
| f_organic_results_video | 動画を含むオーガニック結果数 | 2 | |
| Featured Snippet | f_featured_snippet | Featured Snippetの表示有無 | 1 |
| f_featured_snippet_ordered_list | 順序型リストスニペット | 0 | |
| f_featured_snippet_unordered_list | 非順序リストスニペット | 1 | |
| f_featured_snippet_table | テーブル形式スニペット | 0 | |
| f_featured_snippet_video_exist | スニペット内動画の有無 | 0 | |
| 質問・関連探索 Feature | f_people_also_ask_for | People Also Ask（PAA）の表示 | 1 |
| f_people_also_search_for | People Also Search Forの表示 | 1 | |
| f_related_searches | SERP下部の関連検索語表示 | 1 | |
| f_spell_check | 誤字修正/代替クエリの提案 | 0 | |
| メディア・コンテンツタイプ Feature | f_images | 画像ブロックの表示 | 2 |
| f_video_results | 動画結果の表示 | 1 | |
| f_video_carousels | 動画カルーセルの表示 | 0 | |
| f_articles | ニュース/記事結果の表示 | 0 | |
| f_sns | SNS結果の表示 | 1 | |
| エンティティ・ブランド・ローカル Feature | f_knowledge_panel | Knowledge Panelの表示 | 1 |
| f_sitelinks | Sitelinks拡張結果 | 1 | |
| f_local_results | ローカル（Map Pack）結果 | 0 | |
| f_google_play | Google Play結果 | 0 | |
| f_app_results | アプリ結果の表示 | 0 |
5.4. 検索意図メトリクス（intents）
該当の意図が有意に現れているかどうか（1/0）を確認します。複数の意図が同時に存在する場合があります。
| Category | Metric | 説明 | Value（例） |
|---|---|---|---|
| Intents | I（Informational） | 情報型（Informational）意図 | 1 |
| N（Navigational） | 移動型（Navigational）意図 | 0 | |
| C（Commercial） | 商業型（Commercial）意図 | 0 | |
| T（Transactional） | 取引型（Transactional）意図 | 1 |
5.5. ユーザー人口統計メトリクス（demography）
標準偏差（1シグマ）以上で特定の性別・年齢層の検索比率が高い場合にフラグ（1/0）を返します。
| Category | Metric | 説明 | Value（例） |
|---|---|---|---|
| Demography | m_gender | 男性の検索比率が高い場合 | 0 |
| f_gender | 女性の検索比率が高い場合 | 1 | |
| a0 | 3歳以下の比率が高い場合 | 0 | |
| a13 | 13〜19歳の比率が高い場合 | 0 | |
| a20 | 20〜24歳の比率が高い場合 | 0 | |
| a25 | 25〜29歳の比率が高い場合 | 0 | |
| a30 | 30〜39歳の比率が高い場合 | 1 | |
| a40 | 40〜49歳の比率が高い場合 | 1 | |
| a50 | 50歳以上の比率が高い場合 | 0 | |
| m_gender_ratio | 全検索量における男性の検索比率（%） | 44.23 | |
| f_gender_ratio | 全検索量における女性の検索比率（%） | 55.76 | |
| a0_ratio | 全検索量における3歳以下の検索比率（%） | 0 | |
| a13_ratio | 全検索量における13〜19歳の検索比率（%） | 0.53 | |
| a20_ratio | 全検索量における20〜24歳の検索比率（%） | 3.08 | |
| a25_ratio | 全検索量における25〜29歳の検索比率（%） | 8.60 | |
| a30_ratio | 全検索量における30〜39歳の検索比率（%） | 26.12 | |
| a40_ratio | 全検索量における40〜49歳の検索比率（%） | 33.40 | |
| a50_ratio | 全検索量における50歳以上の検索比率（%） | 27.12 |
5.6. 月別検索ボリュームメトリクス（monthly_volume）
| Category | Metric | 説明 | Value（例） |
|---|---|---|---|
| Monthly_volume | month | 基準月 | 2025-07 |
| gg | Google検索量 | 110000 | |
| nv | Naver検索量 | 262100 | |
| total | 全体検索量（Google＋Naver合計） | 372100 |
5.7. 検索経路メトリクス（path_finder）
| Category | Metric | 説明 | Value（例） |
|---|---|---|---|
| Path_finder | path | 検索ジャーニーシーケンス | ["冷蔵庫", "lg 冷蔵庫", "lg 冷蔵庫 価格"] |
5.8. 関係ネットワークメトリクス（cluster_finder）
| Category | Metric | 説明 | Value（例） |
|---|---|---|---|
| Cluster_finder | rels | 検索行動基盤の接続 | ["lg 冷蔵庫", "lg 冷蔵庫 オブジェ"] |
| communities | 同一認識のキーワードグループ | "1": ["lg 冷蔵庫 オブジェ", "ディオス オブジェ", "オブジェ コレクション"] |
6. データフレーム例（csv）
| 順序 | カラム名 | 説明 | データ例 |
|---|---|---|---|
| 1 | キーワード | 分析対象となる核心検索語 | 身長を伸ばすサプリ |
| 2 | 月平均検索ボリューム | GoogleとNaverの月平均検索量を合算した数値 | 275133 |
| 3 | 年間総検索ボリューム | 直近12ヶ月間の総検索量 | 3301900 |
| 4 | 3ヶ月前比増減率（%） | 直近3ヶ月間の検索量変化推移をパーセントで表示 | 0.19 |
| 5 | CPC（USD） | クリックあたりコスト（Cost Per Click）。広告効率を把握する指標 | 1.41 |
| 6 | 広告競合度（%） | 該当キーワードのGoogle検索広告の競合レベル（0〜100） | 100 |
| 7 | 検索表示タイプ | Google検索結果ページ（SERP）に表示されるスニペットの種類 | 画像ブロック、動画ブロック |
| 8 | 検索インテント | ユーザーの検索意図（情報型、商業型、取引型など） | 情報型、取引型 |
| 9 | 性別特性 | 特定の性別で検索比率が際立つ場合に表示 | 女性 |
| 10 | 男性（%）/ 女性（%） | 全検索量における各性別の占める比率 | 44.84 / 55.15 |
| 11 | 年齢層別特性 | 特定の年齢層で検索比率が際立つ場合に表示 | 30代、40代 |
| 12 | 12歳以下（%）〜50歳以上（%） | 全検索量における各年齢層の占める比率 | 26.5（30代の例） |
| 13 | YYYY-MM（日付形式） | 月別詳細検索量を示すカラム（例: 2021-09） | 該当月の検索量（数値） |
