TikTok Ad Library Search
TikTok Ad Library Search는 광고주 이름 또는 키워드 쿼리 하나를 공개 Ads Library에 보내고, 요청한 페이지 단위 한도나 원본의 중단 조건에 이를 때까지 불투명 커서를 따라갑니다. 투명성 조사와 광고 탐색을 지원하며, 비공개 캠페인 관리나 성과 측정은 지원하지 않습니다.
TikTok Ad Library Search API 주요 기능
- 하나의 집중된 쿼리비어 있지 않은 광고주 이름, 브랜드 용어 또는 키워드 하나를 필수로 입력해 검색합니다.
- 페이지 단위 수집결과를 12의 배수로 12~2,000개 요청할 수 있으며, 유효한 최대값은 1,992입니다.
- 불투명 커서 처리한도에 도달하거나, 빈 페이지, 종료 신호, 커서 누락, 커서 반복이 나타날 때까지 원본 커서를 따라갑니다.
- 정규화된 광고 요약안정적인 식별 정보, 광고주, 노출 날짜, 게재, 랜딩, 노출, 미디어, 게시, 수집 필드를 받습니다.
- 원본에 따른 null 허용공개 검색 결과가 요약만 노출하거나 해당 값을 제공하지 않으면 필드를 null 또는 빈 값으로 유지합니다.
TikTok Ad Library Search API 매개변수
| 매개변수 | 필수 | 설명 |
|---|---|---|
query | 필수 | 비어 있지 않은 광고주 이름 또는 키워드로, 필수 값입니다. 쿼리는 정확히 하나만 받습니다. |
results_limit | 선택 | 결과 수 상한으로, 선택 값입니다. 기본값은 12이며 12~2,000 범위의 12의 배수여야 합니다. 유효한 최대값은 1,992입니다. |
TikTok Ad Library Search API 사용 방법
쿼리 하나와 유효한 페이지 단위 한도를 제출하고, 비동기 작업을 폴링한 뒤, 정규화된 결과 페이지를 가져옵니다.
- 광고주 이름이나 키워드 하나를 고릅니다. 이 엔드포인트는 쿼리 목록을 받지 않습니다.
- query와 선택 사항인 results_limit을 /v1/tiktok-ad-library/search로 POST합니다.
- 작업이 최종 상태가 될 때까지 /v1/tasks/{task_id}를 폴링합니다.
- data.results.items를 읽고, 결과 응답에 더 많은 페이지가 있다고 표시되면 작업 결과 커서를 따라가며 가져옵니다.
curl -X POST "https://api.socq.ai/v1/tiktok-ad-library/search" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query":"Anysphere","results_limit":12}'
# Poll GET /v1/tasks/{task_id}
# Read normalized ads from data.results.itemsTikTok Ad Library Search API 추천 활용 사례
- 광고주 탐색: 제출한 광고주 또는 브랜드 이름과 연관된, 지원되는 공개 광고를 찾습니다.
- 키워드 조사: 색인된 라이브러리 콘텐츠가 주제어 하나와 일치하는 공개 광고의 검토용 세트를 구성합니다.
- 크리에이티브 동향 검토: 반환된 레코드들의 눈에 보이는 주제, 미디어 참조, 광고주 라벨, 노출 날짜를 비교합니다.
- 상세 조회 대기열: 상세 엔드포인트로 선택한 레코드를 확인할 수 있도록 공개 광고 ID와 원본 참조를 수집합니다.
TikTok Ad Library Search API 활용 팁
- 관련도는 원본의 매칭과 정렬이 좌우하므로, 구체적인 광고주 이름이나 특징적인 구문을 사용하세요.
- results_limit은 12개 단위로 정하세요. 2,000은 전체 상한 범위 안에 있지만 12의 배수 규칙에 맞지 않아 실패합니다.
- 원본이 끝나거나, 빈 페이지를 반환하거나, 커서를 반복하면 요청한 것보다 적은 레코드가 반환될 수 있습니다.
- 페이지 간 중복 제거는 보장되지 않으므로, 고유성이 중요하다면 자체 파이프라인에서 안정적인 광고 id를 사용하세요.
- 추정 오디언스나 노출 수는 전환이나 검증된 성과가 아니라 원본의 정의에 따라 해석하세요.
- 레코드 하나를 확인할 때는 Ad Details 엔드포인트를 사용하세요. Search는 선택적인 상세 정보 보강을 제공하지 않습니다.
관련 API
TikTok Ad Library Search API 외에 TikTok Ad Library의 다른 유형의 공개 데이터가 필요할 때 이 API를 사용하세요.
- TikTok Ad Library Ad API — 알고 있는 공개 TikTok 광고 URL 하나를 정규화된 크리에이티브, 광고주, 게재, 랜딩, 노출, 미디어, 게시, 수집 필드로 변환합니다.