Path Finder APIは、特定のキーワードを中心に消費者が検索の前後にどのようなキーワードを探索したかをシーケンス（sequence）形式で返します。単純な関連キーワードではなく、実際の検索フローの順序を示すため、消費者購買ジャーニー（Customer Journey）の各段階を把握するための核心データとして活用されます。
核心特徴まとめ
| 項目 | 詳細 |
|---|---|
| エンドポイント | POST /path_finder |
| リクエストキーワード数 | 1個（単一キーワードのみ対応） |
| 返却形式 | data: string[][] (検索経路シーケンス配列) |
| デフォルト返却件数 | 300経路 |
| 最大返却件数 | 1,000経路 |
| 対応国（gl） | kr（韓国）/ jp（日本）/ us（米国） |
| 課金方式 | 入力1回あたり50クレジット + 出力キーワード1個あたり40クレジット |
⚠ リクエストキーワードは必ず1個（単一string）である必要があります。配列形式（array）ではないことに注意してください。「keyword」パラメーター名を使用します。
返却データ構造
返却されるdataはstring[][]形式です。各内部配列（string[]）がひとつの検索経路シーケンスです。
| 例示経路 | 解釈 |
|---|---|
| ["冷蔵庫", "OO 冷蔵庫", "OO 冷蔵庫 価格"] | 一般カテゴリー → ブランド探索 → 価格比較の順序 |
| ["OO 冷蔵庫", "OO 冷蔵庫 OOO", "OO 冷蔵庫 口コミ"] | ブランド → 特定ライン → 購入口コミ探索 |
| ["OO 冷蔵庫", "OO 冷蔵庫 比較"] | ブランド探索後、競合比較へ移動 |
✔ 中心キーワードがシーケンスの最初・中間・最後のどの位置にあるかを分析すると、消費者がそのキーワードを探索の「起点」「経由点」「終着点」のどこで使用しているかを把握できます。
検索経路分析(/path_finder) APIはいつ使うか
| ユーザーの問い | 活用方向 |
|---|---|
| このキーワード検索後、人々は続けて何を探しますか？ | 転換前段階のキーワード発掘、コンテンツシーケンスの企画 |
| 購買決定直前にどのキーワードを経由しますか？ | 検索ファネルの最終段階キーワードの把握 |
| 消費者が競合ブランドへ離脱するフローはありますか？ | 競合離脱経路の検出 |
| コンテンツシリーズをどの順序で構成すべきですか？ | 検索ジャーニー基盤のコンテンツフロー設計 |
| このキーワードの前にどのような探索段階がありますか？ | ファネル上位キーワードの発掘（AS需要、購入前探索など） |
リクエストパラメーター (Request)
パラメーター詳細
| パラメーター | タイプ | 必須 | デフォルト値 | 説明 |
|---|---|---|---|---|
| keyword | string | Y | – | 分析の中心キーワード（単一）。英語は小文字推奨 |
| gl | string | Y | – | 国コード: "kr" / "jp" / "us" |
| time_point | string | N | curr | データ照会時点: curr / 3m / 6m / 9m / 12m |
| limit | integer | N | 300 | 返却経路数の制限（1〜1,000） |
時点別消費者行動の比較 – time_point
| 値 | 意味 | 活用 |
|---|---|---|
| curr（デフォルト） | 現在時点の検索構造 | 現在の消費者認識・行動の把握 |
| 3m | 3ヶ月前基準 | 直近3ヶ月の変化比較 |
| 6m | 6ヶ月前基準 | 半年前の探索パターン比較 |
| 9m | 9ヶ月前基準 | 季節性分析時に活用 |
| 12m | 12ヶ月前基準 | 1年前の同期間との比較 |
✔ time_pointをcurrと12mでそれぞれ照会すると、1年前と現在の検索経路の変化を比較できます。新製品発売前後やマーケティングキャンペーンの効果測定に有効です。
返却件数の調整 – limit
| limit値 | 経路数 | 課金（出力） | 推奨状況 |
|---|---|---|---|
| 20〜50 | 少数の核心経路 | 800〜2,000クレジット | 素早いジャーニー探索、アイデア確認 |
| 300（デフォルト） | 主要ジャーニーをカバー | 12,000クレジット | 実務標準。ほとんどの分析に十分 |
| 1,000（最大） | 全ジャーニーデータ | 40,000クレジット | 深層ファネル分析、大規模調査 |
⚠ limitを高くすると、レスポンスサイズ・処理時間・課金がすべて増加します。初期探索はlimit: 50〜100から始め、十分な経路を確認してから増やしてください。
リクエスト例
基本リクエスト
{
"keyword": "OO 冷蔵庫",
"gl": "jp"
}時点比較リクエスト
{
"keyword": "OO 冷蔵庫",
"gl": "jp",
"time_point": "12m",
"limit": 300
}レスポンスデータ構造 (Response)
レスポンスデータ構造概要
| フィールド | タイプ | 説明 |
|---|---|---|
| result | string | "OK" または "FAILED" |
| cost_detail | object | 入力50クレジット + 出力40 × 返却キーワード数 |
| used_credits | integer | リクエスト後の累計クレジット |
| data | array[array[string]] | 検索経路シーケンス配列（核心結果） |
レスポンス例
{
"result": "OK",
"cost_detail": { "input_cost": 50, "output_cost": 12000, "total_cost": 12050 },
"data": [
["冷蔵庫", "OO 冷蔵庫", "OO 冷蔵庫 価格"],
["OO 冷蔵庫", "OO 冷蔵庫 オブジェ", "OO 冷蔵庫 口コミ"],
["OO 冷蔵庫", "OO 冷蔵庫 比較"]
]
}課金構造の詳細
| 区分 | 基準 | 単価 | 例 |
|---|---|---|---|
| 入力課金 | リクエスト1回あたり | 50クレジット | 固定費用 |
| 出力課金 | 返却キーワード1個あたり | 40クレジット | キーワード300個 → 12,000クレジット |
| 合計（デフォルトlimit: 300） | – | 12,050クレジット | 50 + 12,000 |
✔ Path Finderは出力単価（40クレジット/キーワード）が高めです。分析目的に合った最小limitから始め、必要な場合は /path_finder/keyword_list でキーワードリストのみ先に確認してから詳細経路を照会する方法を推奨します。
経路データの解釈ガイド
経路タイプ別の解釈
| 経路パターン | 解釈 | 戦略的活用 |
|---|---|---|
| カテゴリー → ブランド → 詳細スペック | 探索型購買ジャーニー | 各段階別ランディングページの最適化 |
| キーワード → 競合キーワード | 競合離脱フロー | 離脱防止コンテンツ（比較・レビュー）の強化 |
| キーワード → AS/修理関連キーワード | 購入後のカスタマーサポート需要 | AS情報コンテンツ、顧客満足の強化 |
| キーワード → 価格/割引キーワード | 価格重視の消費者パターン | 価格競争力メッセージ、プロモーション企画 |
| キーワード → 口コミ/おすすめキーワード | 購入前のソーシャルプルーフ探索 | レビューコンテンツ、インフルエンサーマーケティング |
繰り返し登場するキーワードの分析
複数の経路に繰り返し登場するキーワードは、消費者探索の核心経由点（Hub）です。このキーワードに対するコンテンツ・広告の最適化が転換率に直接影響します。
✔ 経路データで中心キーワードがシーケンスのどの位置に主に登場するかを分析すると、そのキーワードが消費者探索において「入口」なのか「出口」なのかを把握できます（推定：経路分析は直接データ処理が必要）。
活用シナリオ
検索ファネルの設計
| 段階 | 作業 | パラメーター |
|---|---|---|
| 1. 転換キーワードの設定 | 購買意図の高い核心キーワード1個 | "keyword": "ブランド + 購入" |
| 2. 経路収集 | 現在時点の経路分析 | "time_point": "curr", "limit": 300 |
| 3. 転換前段階の把握 | 経路から核心キーワード直前のキーワードを抽出 | 経路配列の前インデックス分析 |
| 4. コンテンツ企画 | 各段階キーワードに合ったコンテンツ制作 | 段階別ランディングページ・コンテンツ構成 |
連携APIの活用
| 連携API | 活用方法 | 目的 |
|---|---|---|
| /path_finder/keyword_list | 経路キーワードリストのみ素早く収集 | 課金削減、キーワードプールの事前確保 |
| /keyword_info | 経路上のキーワードの検索ボリューム・意図を確認 | 核心経由キーワードの優先順位選別 |
| /cluster_finder | 経路キーワードをクラスター分析 | 消費者認識グループとジャーニーの連携 |
エラーレスポンスの処理
| HTTP Status | 主な原因 | 対処方法 |
|---|---|---|
| 401 Unauthorized | APIキーエラー | LM-API-KEYヘッダーを確認 |
| 402 Payment Required | クレジット不足 | 残クレジットを確認後チャージ |
| 422 Unprocessable Entity | 「keyword」の配列入力エラー、glエラー | 単一string値に修正 |
| 429 Too Many Requests | レート制限超過 | リクエスト速度を調整 |
| 500 Internal Server Error | サーバーエラー | テクニカルサポートに問い合わせ |
よくある質問 (FAQ)
Q1. 経路シーケンスの長さ（配列サイズ）は固定ですか？
いいえ。経路シーケンスの長さは実際の消費者検索パターンによって異なります。2要素の短い経路から5要素以上の長い経路まで混在する場合があります。
Q2. 中心キーワードが経路の途中に位置する場合もありますか？
はい。中心キーワードは経路の最初・中間・最後のどの位置にも登場することがあります。これは消費者がそのキーワードを探索のどの段階で使用しているかを示します。
Q3. time_point: "curr"と"12m"のデータの差が大きく出る場合がありますか？
はい。市場環境、製品発売、季節性、トレンドの変化によって、1年前と現在の検索経路が大きく異なる場合があります。時点比較はマーケティング戦略の変化検討に有効です。
Q4. 経路数（limit）を減らすと重要な経路が欠落する可能性がありますか？
返却される経路は頻度が高い順に並んでいます。そのためlimitを低く設定すると、頻度の低い経路は除外される場合があります。核心ジャーニーの把握には300件以上を推奨します。
