틱톡 영상 검색 API, 영상마다 국가 코드가 붙어요
틱톡 영상 검색 API는 키워드 하나로 영상 약 30개를 1크레딧에 돌려줘요. 국가 코드는 영상마다 붙어 오고 region=은 프록시만 바꾸니 국가는 응답에서 직접 걸러요.
틱톡 영상 검색 API는 키워드를 넣으면 맞는 영상을 JSON으로 돌려줘요. GET /v1/tiktok/search?query=요리를 호출하면 한 페이지에 영상이 약 30개 오는데 1크레딧이에요. 영상마다 틱톡에 등록된 국가가 post.ext.region에 담겨 있어요. 틱톡 개발자 앱은 필요 없어요.
틱톡 앱의 검색 화면에는 영상별 국가가 안 나와요. 공식 Research API Query Videos는 region_code로 거르지만 연구 승인을 받아야 쓸 수 있고 POST로만 불러요. 공식 API 없이 데이터를 가져오는 방법은 틱톡 크롤링: API 없이 데이터 가져오는 법에 있어요.
틱톡 영상 검색 API는 어떻게 쓰나요?
query=에 검색어를 넣고 x-api-key 헤더를 붙여 GET으로 부르면 돼요. 통합 스키마의 영상 목록이 오고 다음 페이지는 cursor로 이어서 받아요.
curl -s -H "x-api-key: $SOCIALCRAWL_API_KEY" \
"https://www.socialcrawl.dev/v1/tiktok/search?query=요리"응답 한 행을 줄이면 이래요.
{
"success": true,
"credits_used": 1,
"pagination": { "has_more": true, "next_cursor": "..." },
"data": {
"items": [
{
"post": {
"id": "7000000000000000000",
"url": "https://www.tiktok.com/@example_cook/video/7000000000000000000",
"author": { "username": "example_cook" },
"ext": {
"region": "KR",
"author_id": "6000000000000000000",
"author_followers": 11325
}
}
}
]
}
}자주 쓰는 필드는 네 가지예요.
| 필드 | 담긴 값 |
|---|---|
post.ext.region | 영상이 등록된 국가의 ISO 3166-1 alpha-2 코드. 보통 게시 당시 크리에이터의 계정 국가예요 |
post.author.username | 크리에이터 핸들 |
post.ext.author_id | 크리에이터의 숫자 ID |
post.ext.author_followers | 검색 응답에 실린 팔로워 수 |
선택 파라미터는 date_posted(yesterday, this-week, this-month, last-3-months, last-6-months, all-time), sort_by(relevance, most-liked, date-posted), region, cursor, limit, expand예요. 최신 목록은 틱톡 영상 검색 엔드포인트 페이지에 있어요.
파이썬으로는 이렇게 불러요.
import os
import requests
r = requests.get(
"https://www.socialcrawl.dev/v1/tiktok/search",
params={"query": "요리", "sort_by": "most-liked"},
headers={"x-api-key": os.environ["SOCIALCRAWL_API_KEY"]},
timeout=60,
)
payload = r.json()
for row in payload["data"]["items"]:
print(row["post"]["ext"]["region"], row["post"]["url"])
틱톡 영상을 국가별로 거르려면 어떻게 하나요?
각 행의 post.ext.region을 읽어서 원하는 코드만 남기면 돼요. region= 파라미터는 필터가 아니에요. 요청을 보내는 프록시 국가만 바꿀 뿐이라 region=ES로 검색해도 다른 나라에 등록된 영상이 섞여 와요.
korean = [
row for row in payload["data"]["items"]
if row["post"]["ext"]["region"] == "KR"
]코드는 ISO 표기를 써요. 영국은 UK가 아니라 GB예요. 키워드 검색은 전 세계가 대상이라 국가 구성은 검색어에 따라 달라져요. 한국 영상을 원하면 한국어 키워드로 검색하고 나머지는 필터로 걸러 내세요.
행마다 크리에이터의 유저네임, ID, 팔로워 수도 들어 있어서 한 나라로 거른 페이지는 그대로 그 나라의 크리에이터 목록이에요. 정확한 현재 팔로워 수, 바이오, 링크가 필요하면 유저네임을 GET /v1/tiktok/profile(1크레딧)에 넣어요. 최대 50명까지 한 번에 조회하려면 POST /v1/prism/profiles(확인된 프로필당 1크레딧)를 쓰면 돼요. 같은 크리에이터가 키워드마다 반복해서 나오니 유저네임은 먼저 중복을 없애세요.
post.ext.region은 영상이 등록된 국가일 뿐이에요. 시청자나 팔로워가 사는 나라도 캡션 언어도 이 필드로는 알 수 없어요.
틱톡 영상 검색은 몇 크레딧인가요?
약 30개짜리 한 페이지가 1크레딧이에요. limit을 30 이하로 주면 그 페이지의 앞쪽 limit개만 같은 1크레딧에 받아요. 다만 next_cursor는 페이지 전체를 건너뛰니 페이지를 넘길 때는 limit을 빼세요. 캐시에서 나온 응답은 무료예요.
한 페이지에는 아직 안 나온 영상을 25개 이상 담으려고 해요. 중복 제거나 날짜 조건으로 행이 빠지거나 첫 페이지가 거의 비어 오면 페이지를 내주기 전에 더 읽어 와요. 추가 크레딧은 없어요. 틱톡 결과가 끝나 갈 무렵에는 페이지가 짧아지는 게 정상이에요.
1크레딧 페이지를 cursor로 넘기다가 필요한 만큼 모이면 멈추세요. 틱톡 엔드포인트별로 1크레딧에 얼마나 받는지는 틱톡 팔로워 API 사용법과 엔드포인트별 크레딧에서 비교했어요.
틱톡은 검색어 하나의 결과를 200~400개쯤에서 끝내요. expand=true를 보내면 연관 검색어와 다른 정렬로 이어서 가져와요. 한 페이지는 여전히 1크레딧이에요. 원래 결과가 끝난 뒤 이어 붙는 행은 sort_by 순서를 따르지 않고 같은 영상이 다시 나오기도 해요. post.id로 중복을 없애세요.
영상 검색의 region=과 유저 검색의 country=는 같은 건가요?
아니에요. 엔드포인트가 다르고 거르는 대상도 달라요.
GET /v1/tiktok/search | GET /v1/tiktok/search/users | |
|---|---|---|
| 반환 | 영상 | 계정 |
| 국가 필드 | 영상마다 post.ext.region | 계정마다 author.location |
region= / country= | region=은 프록시만 바꿔요 | country=는 계정 지역으로 걸러요 |
| 크레딧 | 페이지당 1 | 반환된 국내 크리에이터당 5 |
주제에 맞는 영상을 국가 표시와 함께 받고 직접 거르려면 영상 검색을 쓰세요. 한 나라에 등록된 계정만 받고 싶다면 country=를 붙인 유저 검색이 맞아요. 그쪽은 틱톡 유저 검색, 국가로 한국 크리에이터만 찾기에서 다뤄요. 나라별로 지금 뜨는 게시물, 사운드, 해시태그를 한 번에 보고 싶다면 틱톡 트렌드 API 호출이 따로 있어요.
어떻게 시작하나요?
- 가입해요. 새 계정에는 무료 크레딧 100개가 들어오고 카드는 필요 없어요(요금). 인증은
x-api-key헤더예요. - 위의 요리 검색을 호출해서 행마다
post.ext.region이 있는지 확인해요. date_posted나sort_by를 붙이고post.ext.region으로 거른 뒤cursor로 다음 페이지를 불러요.- 코드 한 줄 쓰기 전에 응답부터 보려면 익스플로러를 열어 보세요. 나머지 틱톡 엔드포인트는 틱톡 문서에 있어요.
자주 묻는 질문
틱톡 영상을 국가별로 검색할 수 있나요?
네, 영상에 붙은 국가 코드를 보고 직접 거르는 방식이에요. GET /v1/tiktok/search가 영상마다 post.ext.region(ISO 3166-1 alpha-2)을 돌려주니 원하는 행만 남기면 돼요. API가 다른 나라 영상을 대신 빼 주지는 않아요. 한 나라 계정만 받고 싶다면 크리에이터당 5크레딧이 드는 GET /v1/tiktok/search/users?country=를 쓰세요.
region 파라미터로 틱톡 검색 결과가 걸러지나요?
아니요. region=은 요청을 보내는 프록시 국가만 정해요. 다른 나라에 등록된 영상도 나올 수 있어요. 호출한 뒤에 post.ext.region으로 거르세요.
틱톡 영상 검색은 한 번에 얼마인가요?
약 30개짜리 한 페이지가 1크레딧이에요. 30 이하의 limit도 마찬가지예요. 행이 빠지거나 첫 페이지가 거의 비어 오면 추가 크레딧 없이 더 읽어 와요. 캐시 기간 안에 같은 요청을 다시 보내면 무료예요.
틱톡 영상 검색을 날짜나 정렬로 좁힐 수 있나요?
네. date_posted로 기간(yesterday부터 all-time까지 여섯 단계)을 고르고 sort_by로 relevance, most-liked, date-posted 중 정렬을 골라요. 둘 다 검색과 함께 보내고 추가 크레딧은 없어요.
국가별 틱톡 크리에이터 찾기와는 뭐가 다른가요?
영상 검색은 영상마다 국가를 붙여 주고 거르는 건 사용자 몫이에요. 약 30개 한 페이지에 1크레딧이에요. country=를 붙인 유저 검색은 공개 지역이 맞는 계정만 돌려줘요. 크리에이터당 5크레딧이고 기본 8명에 최대 20명이며 cursor는 없어요. 틱톡 유저 검색 글에서 자세히 다뤄요.
함께 읽으면 좋은 글
페이스북 댓글 크롤링, 게시물 25개를 한 번에 읽어요
페이스북, 인스타그램, 틱톡, 유튜브 게시물 25개의 댓글을 API 호출 한 번으로 읽어요. since를 넣으면 새 댓글만 읽고 새 댓글이 없으면 크레딧도 들지 않아요.
인플루언서 검색 API: 팔로워가 아니라 조회수로 크리에이터 고르기
인플루언서 검색 API 한 번으로 주제와 국가, 규모에 맞는 크리에이터를 찾아요. 최근 게시물에서 잰 중간 조회수로 순위를 매기고 드라이런으로 비용도 미리 확인해요.
틱톡과 유튜브 이메일 찾기 API, include=contacts 한 줄로
프로필 호출에 include=contacts를 붙이면 크리에이터가 공개한 비즈니스 이메일과 출처가 와요. 결과 상태 다섯 가지와 재시도, 크레딧 규칙까지 담았어요.
