TikTok Shop Search
TikTok Shop 검색 결과는 선택한 시장에서 키워드와 일치하는 공개 상품으로, 상품 및 판매자 정보, 가격, 이미지, 평점, 리뷰 수, 판매 수를 담고 있습니다. 이러한 커머스 레코드는 지역별 상품 탐색, 가격 비교, 판매자 조사, 반복 가능한 시장 스냅샷에 활용할 수 있습니다.
TikTok Shop Search API 주요 기능
- 키워드와 시장 설정상품 쿼리를 지원되는 16개 region 값 중 하나와 짝지어, 원하는 공개 시장 카탈로그를 검색합니다.
- 범위가 제한된 고유 결과 수집결과를 20~2,000개 요청할 수 있으며, 수집한 페이지는 공개 상품 식별 정보를 기준으로 중복이 제거됩니다.
- 상품 및 판매자 정보상품 ID, 제목, 설명, 정식 링크와 노출된 판매자 또는 상점 정보를 반환합니다.
- 가격과 공개된 커머스 신호노출되는 경우 판매가, 정가, 통화, 할인, 평점, 리뷰 수, 판매 수를 보존합니다.
- 미디어와 상품 맥락공개 이미지, 카테고리, SKU 구조, 상태, 검색 쿼리, 지역, 수집 시각을 레코드마다 함께 보존합니다.
TikTok Shop Search API 매개변수
| 매개변수 | 필수 | 설명 |
|---|---|---|
query | 필수 | 비어 있지 않은 상품 키워드 또는 구문으로, 필수 값입니다. |
results_limit | 선택 | 요청할 고유 결과 수의 상한으로, 20~2,000 범위입니다. 기본값은 100입니다. |
region | 선택 | 시장 지역으로, US, GB, DE, FR, IT, ID, MY, MX, PH, SG, ES, TH, VN, BR, JP, IE 중 하나입니다. 기본값은 US입니다. |
TikTok Shop Search API 사용 방법
구체적인 상품 구문과 시장을 정한 뒤, 비동기 검색 요청을 한 번 제출합니다.
- 비어 있지 않은 query를 입력하고, 지원되는 region을 고르고, 20~2,000 범위의 results_limit을 설정합니다.
- 요청을 /v1/tiktok-shop/search로 POST하고, 반환된 task_id를 저장합니다.
- 작업이 succeeded 또는 failed가 될 때까지 /v1/tasks/{task_id}를 폴링합니다.
- data.results.items를 읽습니다. has_more가 true이면 next_cursor로 이어서 가져옵니다.
curl -X POST "https://api.socq.ai/v1/tiktok-shop/search" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query":"running shoes","results_limit":100,"region":"US"}'
# Poll GET /v1/tasks/{task_id}
# Read data.results.items and follow next_cursor while has_more is trueTikTok Shop Search API 추천 활용 사례
- 지역별 상품 탐색: 선택한 시장에서 카테고리, 니즈, 브랜드, 상품 구문과 일치하는 공개 상품을 파악합니다.
- 가격 및 할인 비교: 반환된 상품들의 판매가, 정가, 통화, 할인 필드를 비교합니다.
- 평판과 수요 비교: 노출된 평점, 리뷰 수, 판매 수를 비교하되, 누락된 지표를 0으로 바꾸지 않습니다.
- 상품·상점 후보 선별: 상품 링크, 판매자 정보, 이미지, 카테고리, SKU 맥락을 활용해 더 자세히 검토할 후보를 고릅니다.
TikTok Shop Search API 활용 팁
- 같은 구문이라도 공개 카탈로그가 다르게 해석될 수 있으므로, query와 region은 항상 함께 저장하세요.
- results_limit은 필요한 수량으로 설정하고, 작업 결과 전체를 읽으려면 has_more가 false가 될 때까지 next_cursor를 따라가세요.
- 누락된 가격, 평점, 리뷰 수, 판매 수는 0이 아니라 알 수 없는 값으로 취급하세요.
- 지역별 스냅샷을 재현할 수 있도록 모든 레코드에 search_query와 collected_at을 함께 보관하세요.
- 최신 상세 정보로 보강하려면 선택한 PDP URL을 TikTok Shop Product API에 전달하세요.
관련 API
TikTok Shop Search API 외에 TikTok Shop의 다른 유형의 공개 데이터가 필요할 때 이 API를 사용하세요.
- TikTok Shop Products API — TikTok Shop 스토어 URL 하나에서 공개 상품을 수집하며, 판매자, 가격, 미디어, 카테고리, SKU, 평점, 리뷰, 판매량 필드를 포함합니다.
- TikTok Shop Product API — PDP URL로 공개 TikTok Shop 상품 하나를 가져오며, 판매자, 가격, 미디어, 카테고리, SKU, 평점, 리뷰, 판매량 필드를 포함합니다.
- TikTok Shop Product Reviews API — TikTok Shop PDP URL 하나의 공개 리뷰를 수집하며, 본문, 평점, 리뷰어, 이미지, SKU, 국가, 구매 맥락 필드를 포함합니다.
- TikTok Shop User Showcase API — TikTok 사용자 이름 하나의 공개 쇼케이스 상품을 수집하며, 가격, 판매자, 미디어, 평점, 리뷰, 판매량, 지역 맥락을 포함합니다.
- TikTok Shop Hot Products API — 지역 코드로 TikTok Shop 시장의 인기 판매 상품을 순위대로 수집하며 가격, 통화, 판매량, 평점, 판매자를 포함합니다.
- TikTok Shop Search Suggestions API — 한 시장에서 쇼핑 검색어 앞부분에 대해 TikTok Shop이 제안하는 자동완성을 순위대로 최대 20개 가져옵니다.