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개 이상을 권장합니다.
