Cluster Finder APIは、中心キーワードを基盤に消費者の検索行動から形成されたキーワード関係ネットワーク(rels)と消費者認識グループ(communities)を返します。単純な関連キーワードリストを超え、キーワード間の接続構造と消費者認識における「意味のまとまり」を把握できる深層分析データです。
2つのデータタイプ: rels vs communities
| 区分 | rels（関係） | communities（コミュニティ） |
|---|---|---|
| 形式 | array of [source, target] | { cluster_id: string[] } オブジェクト |
| 内容 | 一緒に検索されたキーワードペア（無方向/方向指定可） | 消費者認識上、ひとつのテーマとしてまとめられたキーワードグループ |
| 活用 | グラフ・ネットワーク分析、関係の可視化 | CEP導出、メッセージセグメント、コンテンツポジショニング |
| デフォルトdata_type | – | communities（デフォルト値） |
核心特徴まとめ
| 項目 | 詳細 |
|---|---|
| エンドポイント | POST /cluster_finder |
| リクエストキーワード数 | 1個（単一キーワード） |
| 返却形式 | data: { rels: [][], communities: {} } |
| デフォルト返却件数 | 500件（関係数基準） |
| 最大返却件数 | 10,000件 |
| 対応国（gl） | kr / jp / us |
| 課金方式 | 入力150クレジット + 出力50クレジット/キーワード |
消費者認識・関係ネットワーク分析API (/cluster_finder) いつ使うか？
| ユーザーの問い | 活用方向 |
|---|---|
| 消費者はこのキーワードをどのような文脈で認識していますか？ | communitiesで認識グループを把握 |
| カテゴリー進入点（CEP）はどこですか？ | communitiesクラスター別テーマ分析 |
| キーワード間の接続関係をネットワークで見たい。 | relsデータでグラフ可視化 |
| ブランドポジショニング戦略を立てたい。 | コミュニティ別消費者認識グループ分析 |
| 競合ブランドと一緒に括られるキーワードを知りたい。 | NATURAL/REVERSE方向分析 |
| 6ヶ月前と現在で消費者認識は変わりましたか？ | time_point比較分析 |
リクエストパラメーター (Request)
パラメーター詳細
| パラメーター | タイプ | 必須 | デフォルト値 | 説明 |
|---|---|---|---|---|
| keyword | string | Y | – | 分析の中心キーワード（単一） |
| gl | string | Y | – | 国コード: "kr" / "jp" / "us" |
| time_point | string | N | curr | データ時点: curr / 3m / 6m / 9m / 12m |
| limit | integer | N | 500 | 返却関係数の制限（1〜10,000） |
| hop | integer | N | 2 | 関係拡張の深さ（1〜3） |
| orientation | string | N | UNDIRECTED | 関係方向: UNDIRECTED / NATURAL / REVERSE |
| data_type | string | N | communities | 返却データ: communities / rels / all |
関係拡張の深さ設定 – hop
| hop値 | 意味 | 結果規模 | 推奨状況 |
|---|---|---|---|
| 1 | 中心キーワードと直接接続されたキーワードのみ | 小規模 | 核心関連キーワードを素早く確認 |
| 2（デフォルト） | 直接接続 + 2段階拡張 | 中規模 | 実務標準。ほとんどの分析に適合 |
| 3 | 3段階まで拡張 | 大規模（コスト↑） | 全体ネットワーク探索、長期戦略策定 |
⚠ hop=3は結果数が爆発的に増加し、課金が大幅に増えます。hop=2 + limit=300〜500が実務上の安全な設定範囲です。
関係方向性の設定 – orientation
| 値 | 技術的な意味 | 解釈 | 活用 |
|---|---|---|---|
| UNDIRECTED（デフォルト） | 無方向関係 | 一緒に検索されたペア（順序不問） | 全体関連キーワードの把握 |
| NATURAL | 順方向（以降ネットワーク） | 中心キーワード検索後に探索したキーワード | 転換後の行動・離脱経路の把握 |
| REVERSE | 逆方向（以前ネットワーク） | 中心キーワード検索前に探索したキーワード | ファネル上位の進入経路把握 |
✔ NATURALは「このキーワードの後に何を探すか？」、REVERSEは「このキーワードの前に何を探すか？」を示します。両方向を比較すると、消費者探索フローの全体的な文脈を把握できます。
返却データタイプの選択 – data_type
| 値 | 返却データ | 活用 |
|---|---|---|
| communities（デフォルト） | 消費者認識グループ { cluster_id: keywords[] } | CEP導出、メッセージ細分化、ポジショニング |
| rels | キーワードペア関係エッジ [source, target][] | ネットワークグラフ可視化、関係分析 |
| all | communities + rels 両方 | 総合分析 |
リクエスト例
コミュニティ分析
{
"keyword": "OO 冷蔵庫",
"gl": "jp",
"hop": 2, "limit": 300, "data_type": "communities"
}順方向関係分析
{
"keyword": "OO 冷蔵庫",
"gl": "jp",
"orientation": "NATURAL", "data_type": "rels"
}時点比較（6ヶ月前）
{
"keyword": "OO 冷蔵庫",
"gl": "jp",
"time_point": "6m", "data_type": "communities"
}レスポンスデータ構造 (Response)
data.communities 構造
communitiesはcluster_idをキーとするオブジェクトです。各クラスターは消費者認識上ひとつのテーマを共有するキーワードグループです。
"communities": {
"0": ["OO 冷蔵庫 価格", "OO 冷蔵庫 割引", "OO 冷蔵庫 安く"],
"1": ["OO 冷蔵庫 オブジェ", "ディオス オブジェ", "OO オブジェ コレクション"],
"2": ["省エネ1等級 冷蔵庫", "電気代 冷蔵庫", "低電力 冷蔵庫"]
}| クラスターID | 主要キーワード | 認識テーマの解釈 | マーケティングへの示唆 |
|---|---|---|---|
| 0 | 価格、割引、安く | 価格重視の消費者グループ | プロモーション・割引コンテンツ戦略 |
| 1 | オブジェ、ディオス、コレクション | プレミアムライン関心グループ | プレミアムポジショニングの強化 |
| 2 | 省エネ1等級、電気代 | エネルギー効率関心グループ | 効率性メッセージコンテンツ |
data.rels 構造
relsは[source, target]ペアの配列です。2つのキーワード間に検索行動基盤の接続があることを示します。
"rels": [
["冷蔵庫", "OO 冷蔵庫"],
["OO 冷蔵庫", "OO 冷蔵庫 オブジェ"],
["OO 冷蔵庫", "OO 冷蔵庫 価格"]
]⚠ relsの[source, target]の順序は、UNDIRECTED（デフォルト）では順序に関係ありません。NATURALまたはREVERSEを設定した場合に方向の意味が生まれます。
課金構造の詳細
| 区分 | 基準 | 単価 | 例 |
|---|---|---|---|
| 入力課金 | リクエスト1回あたり | 150クレジット | 固定費用 |
| 出力課金 | 返却キーワード1個あたり | 50クレジット | 関係500件 → 25,000クレジット |
| 合計（デフォルトlimit: 500） | – | 25,150クレジット | 150 + 25,000 |
| limit | 総課金（推定） | 推奨状況 |
|---|---|---|
| 100 | 5,150クレジット | 初期探索、素早いアイデア確認 |
| 300 | 15,150クレジット | 実務分析標準 |
| 500（デフォルト） | 25,150クレジット | 十分なネットワークカバレッジ |
| 1,000 | 50,150クレジット | 深層分析 |
✔ コスト削減を希望する場合は、/cluster_finder/keyword_listでキーワードリストのみ先に収集し、その後必要なシードにのみ/cluster_finderを呼び出す2段階アプローチを推奨します。
活用シナリオ
CEP（Category Entry Point）の導出
消費者が購入を検討する際に思い浮かべる状況と文脈を、communitiesクラスターから把握します。
| 段階 | 作業 | 活用データ |
|---|---|---|
| 1. クラスター収集 | 中心キーワードでcommunitiesを照会 | data_type: "communities" |
| 2. テーマ解釈 | 各クラスターのキーワードグループから共通テーマを導出 | クラスター内キーワードパターン分析 |
| 3. CEP定義 | 消費者の購買進入状況・文脈の命名 | 例: 「価格比較型」「プレミアム追求型」 |
| 4. メッセージ設計 | CEP別のカスタム広告・コンテンツメッセージ開発 | セグメント別クリエイティブ戦略 |
orientation方向別の活用
| 分析目的 | orientation設定 | 得られるインサイト |
|---|---|---|
| 全体関連ネットワークの把握 | UNDIRECTED | 一緒に検索される全キーワードのエコシステム |
| 離脱・転換後の行動分析 | NATURAL | 中心キーワード後に消費者が探索するキーワード |
| ファネル上位進入経路の把握 | REVERSE | 中心キーワード前に探索したキーワード（上位ファネル） |
エラーレスポンスの処理
| HTTP Status | 主な原因 | 対処方法 |
|---|---|---|
| 401 Unauthorized | APIキーエラー | LM-API-KEYヘッダーを確認 |
| 402 Payment Required | クレジット不足 | チャージ後に再リクエスト |
| 422 Unprocessable Entity | hop範囲超過（3超過）、glエラー | パラメーター値を確認 |
| 429 Too Many Requests | レート制限超過 | リクエスト速度を調整 |
| 500 Internal Server Error | サーバーエラー | テクニカルサポートに問い合わせ |
よくある質問 (FAQ)
Q1. communitiesのcluster_id（0、1、2…）はどのような基準で生成されますか？
cluster_idはデータから自動検出されたグループ番号で、数字自体に意味はありません。各クラスター内のキーワードの共通テーマを直接分析して意味を付与する必要があります。
Q2. hop=3設定時に結果が多すぎて分析が難しいです。
hop=3は結果が爆発的に増加します。limitを低く設定するか（例：100〜300）、orientationをNATURALまたはREVERSEに限定することで、管理可能な規模に抑えることができます。
Q3. relsとcommunitiesを同時に受け取るにはどうすればよいですか？
data_type: "all"に設定すると、relsとcommunitiesを1回のリクエストですべて受け取ることができます。
Q4. 同じキーワードでNATURALとREVERSEをそれぞれ照会するとクレジットが2倍消費されますか？
はい。orientationが異なる2つのリクエストは別々のAPI呼び出しとして処理されるため、それぞれ課金されます。
