---
title: 검색 경로 분석 API (/path_finder) 활용 가이드
description: "Path Finder API는 특정 키워드를 중심으로 소비자가 검색 전후에 어떤 키워드를 탐색했는지를 시퀀스(sequence) 형태로 반환합니다. 단순 연관 키워드가 아니라 실제 검색 흐름의 순서를 보여주므로, 소비자 구매 여정(Customer Journey)의 각 단계를 파악하는 데 핵심 데이터로 활용됩니다. ## 핵심 특징 요약 |…"
url: "https://kr.listeningmind.com/data-api/api-reference/path-finder-api/"
updated: "2026-10-16"
category: API 레퍼런스
tags:
  - 검색경로분석
  - 데이터 API
  - 리스닝마인드 DaaS
---

# 검색 경로 분석 API (/path_finder) 활용 가이드

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": "kr"
}
```

#### 시점 비교 요청

```
{
  "keyword": "OO 냉장고",
  "gl": "kr",
  "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 Key 오류 | LM-API-KEY 헤더 확인 |
| 402 Payment Required | 크레딧 부족 | 잔여 크레딧 확인 후 충전 |
| 422 Unprocessable Entity | "keyword" 배열 입력 오류, gl 오류 | 단일 string 값으로 수정 |
| 429 Too Many Requests | Rate Limit 초과 | 요청 속도 조절 |
| 500 Internal Server Error | 서버 오류 | 기술 지원 문의 |

## 자주 묻는 질문 (FAQ)

### Q1. 경로 시퀀스의 길이(배열 크기)는 고정인가요?

아니요. 경로 시퀀스의 길이는 실제 소비자 검색 패턴에 따라 다릅니다. 2개짜리 짧은 경로부터 5개 이상의 긴 경로까지 혼재할 수 있습니다.

### Q2. 중심 키워드가 경로 중간에 위치하는 경우도 있나요?

네. 중심 키워드는 경로의 첫 번째, 중간, 마지막 어느 위치에도 등장할 수 있습니다. 이는 소비자가 해당 키워드를 탐색의 어느 단계에서 사용하는지를 보여줍니다.

### Q3. time_point: "curr"과 "12m"의 데이터 차이가 크게 나타날 수 있나요?

네. 시장 환경, 제품 출시, 계절성, 트렌드 변화에 따라 1년 전과 현재의 검색 경로가 크게 달라질 수 있습니다. 시점 비교는 마케팅 전략의 변화 검토에 유용합니다.

### Q4. 경로 수(limit)를 줄이면 중요한 경로가 누락될 수 있나요?

반환 경로는 빈도가 높은 순서로 정렬됩니다. 따라서 limit을 낮게 설정하면 덜 빈번한 경로는 제외될 수 있습니다. 핵심 여정 파악에는 300개 이상을 권장합니다.