TikTok Shop Categories
TikTok Shop 카테고리는 한 시장의 상품 분류 체계로, 카테고리마다 ID, 현지어 이름, 영문 slug, 깊이 레벨, 상위 카테고리, 그 위로 이어지는 이름 경로가 있습니다. 트리로 펼쳐 보면 시장이 상품을 어떻게 묶는지 알 수 있고, 카탈로그 매핑, 카테고리 리서치 기획, 특정 갈래 탐색에 필요한 ID를 얻을 수 있습니다.
TikTok Shop Categories API 주요 기능
- 호출 한 번에 모든 카테고리요청 한 번으로 선택한 시장의 트리 전체가 최상위 분류부터 가장 깊은 하위 카테고리까지 각각 별도 행으로 반환됩니다.
- 상위 카테고리, 레벨, 최하위 여부parent_id 값은 각 행을 바로 위 카테고리와 연결하고, level 값은 최상위를 1로 한 깊이를 세며, is_leaf 값은 하위 카테고리가 없는 분류를 표시합니다.
- path에 담긴 상위 이름path 배열에는 최상위부터 해당 행 바로 위까지의 카테고리 이름이 순서대로 담겨, 트리를 따라가지 않아도 깊은 카테고리를 맥락과 함께 보여 줄 수 있습니다.
- 카테고리 상품으로 이어지는 ID각 id 값은 TikTok Shop Category Products의 category_id로 넘겨 그 카테고리에 등록된 상품을 나열하는 데 쓸 수 있습니다.
TikTok Shop Categories API 매개변수
| 매개변수 | 필수 | 설명 |
|---|---|---|
region | 선택 | 카테고리 트리를 가져올 시장으로 US, SG, MY, PH, TH, VN, ID, JP, MX 중 하나이며 기본값은 US입니다. |
TikTok Shop Categories API 사용 방법
시장 하나의 트리를 요청하고, 반환된 행으로 트리를 구성합니다.
- {"region": "US"}을 /v1/tiktok-shop/categories로 POST합니다. region을 생략해도 US 트리가 반환됩니다.
- 작업이 성공할 때까지 GET /v1/tasks/{task_id}를 폴링합니다.
- has_more 값이 true인 동안 results.next_cursor를 따라가며 results.items의 모든 행을 모은 뒤, parent_id 값으로 행을 중첩합니다.
curl -X POST "https://api.socq.ai/v1/tiktok-shop/categories" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"region":"US"}'TikTok Shop Categories API 추천 활용 사례
- 카테고리 메뉴 재구성: parent_id 값으로 행을 중첩하고 level 값으로 정렬해 시장의 카테고리 내비게이션을 다시 만들며, 라벨에는 name, 아이콘에는 cover_url 값을 씁니다.
- 자사 카탈로그와 분류 매핑: name, slug, path 값을 자사 상품 카테고리와 대조해 자체 분류 체계와 해당 시장의 TikTok Shop 분류를 서로 변환합니다.
- 카테고리 전수 조사 계획: 선택한 대분류 아래에서 is_leaf 값이 true인 행만 걸러 TikTok Shop Category Products로 보낼 ID 목록을 만듭니다.
TikTok Shop Categories API 활용 팁
- has_more 값이 true이면 트리를 만들기 전에 results.next_cursor를 마지막 페이지까지 따라가세요. 페이지가 하나라도 빠지면 하위 행이 상위 카테고리를 잃습니다.
- parent_id 값이 비어 있고 level 값이 1인 행을 트리의 루트로 보세요. 이 행의 path는 빈 목록입니다.
- 트리는 시장마다 따로이므로, 카테고리 ID를 TikTok Shop Category Products에 보낼 때는 트리를 읽은 것과 같은 region 값을 쓰세요.
관련 API
TikTok Shop Categories API 외에 TikTok Shop의 다른 유형의 공개 데이터가 필요할 때 이 API를 사용하세요.
- TikTok Shop Search API — 키워드와 시장 지역으로 공개 TikTok Shop 상품을 검색하며, 판매자, 가격, 미디어, 평점, 리뷰, 판매량 필드를 포함합니다.
- TikTok Shop Products API — TikTok Shop 스토어 URL 하나에서 공개 상품을 수집하며, 판매자, 가격, 미디어, 카테고리, SKU, 평점, 리뷰, 판매량 필드를 포함합니다.
- TikTok Shop Product API — PDP URL로 공개 TikTok Shop 상품 하나를 가져오며, 판매자, 가격, 미디어, 카테고리, SKU, 평점, 리뷰, 판매량 필드를 포함합니다.
- TikTok Shop User Showcase API — TikTok 사용자 이름 하나의 공개 쇼케이스 상품을 수집하며, 가격, 판매자, 미디어, 평점, 리뷰, 판매량, 지역 맥락을 포함합니다.
- TikTok Shop Hot Products API — 지역 코드로 TikTok Shop 시장의 인기 판매 상품을 순위대로 수집하며 가격, 통화, 판매량, 평점, 판매자를 포함합니다.
- TikTok Shop Category Products API — 카테고리 ID와 시장으로 TikTok Shop 카테고리 하나의 상품을 나열하며 가격, 판매량, 평점, 리뷰, 판매자를 포함합니다.