tiktok-ad-library/
search

광고주 이름 또는 키워드 쿼리 하나로 지원되는 TikTok 공개 광고 레코드를 찾고, 제공되는 경우 정규화된 식별 정보, 노출 날짜, 오디언스 신호, 미디어 참조를 수집합니다.

TikTok Ad Library Search API

광고주 또는 키워드
12개 단위 페이지
공개 광고 탐색
결과당 0.5 크레딧
준비됨
준비됨

매개변수를 입력하고 요청을 전송하세요. 작업 상태와 정규화된 결과가 여기에 표시됩니다.

README

SocQ 작성 · 업데이트

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 사용 방법

쿼리 하나와 유효한 페이지 단위 한도를 제출하고, 비동기 작업을 폴링한 뒤, 정규화된 결과 페이지를 가져옵니다.

  1. 광고주 이름이나 키워드 하나를 고릅니다. 이 엔드포인트는 쿼리 목록을 받지 않습니다.
  2. query와 선택 사항인 results_limit을 /v1/tiktok-ad-library/search로 POST합니다.
  3. 작업이 최종 상태가 될 때까지 /v1/tasks/{task_id}를 폴링합니다.
  4. 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.items

TikTok Ad Library Search API 추천 활용 사례

  • 광고주 탐색: 제출한 광고주 또는 브랜드 이름과 연관된, 지원되는 공개 광고를 찾습니다.
  • 키워드 조사: 색인된 라이브러리 콘텐츠가 주제어 하나와 일치하는 공개 광고의 검토용 세트를 구성합니다.
  • 크리에이티브 동향 검토: 반환된 레코드들의 눈에 보이는 주제, 미디어 참조, 광고주 라벨, 노출 날짜를 비교합니다.
  • 상세 조회 대기열: 상세 엔드포인트로 선택한 레코드를 확인할 수 있도록 공개 광고 ID와 원본 참조를 수집합니다.

TikTok Ad Library Search API 활용 팁

  • 관련도는 원본의 매칭과 정렬이 좌우하므로, 구체적인 광고주 이름이나 특징적인 구문을 사용하세요.
  • results_limit은 12개 단위로 정하세요. 2,000은 전체 상한 범위 안에 있지만 12의 배수 규칙에 맞지 않아 실패합니다.
  • 원본이 끝나거나, 빈 페이지를 반환하거나, 커서를 반복하면 요청한 것보다 적은 레코드가 반환될 수 있습니다.
  • 페이지 간 중복 제거는 보장되지 않으므로, 고유성이 중요하다면 자체 파이프라인에서 안정적인 광고 id를 사용하세요.
  • 추정 오디언스나 노출 수는 전환이나 검증된 성과가 아니라 원본의 정의에 따라 해석하세요.
  • 레코드 하나를 확인할 때는 Ad Details 엔드포인트를 사용하세요. Search는 선택적인 상세 정보 보강을 제공하지 않습니다.

TikTok Ad Library Search API 외에 TikTok Ad Library의 다른 유형의 공개 데이터가 필요할 때 이 API를 사용하세요.

  • TikTok Ad Library Ad API — 알고 있는 공개 TikTok 광고 URL 하나를 정규화된 크리에이티브, 광고주, 게재, 랜딩, 노출, 미디어, 게시, 수집 필드로 변환합니다.

다른 플랫폼 둘러보기

TikTok Ad Library 데이터를 지원되는 다른 소셜 플랫폼의 공개 데이터와 함께 활용하세요.

TikTok Ad Library Search API — 자주 묻는 질문

TikTok Ad Library Search API는 광고주 이름 또는 키워드 쿼리 하나로 지원되는 TikTok 공개 광고 레코드를 찾고, 페이지 단위 한도까지 정규화된 광고 요약을 반환하는 프로그래밍 인터페이스입니다.

query는 비어 있지 않은 문자열 하나로, 필수 값입니다. 광고주 이름, 브랜드 용어, 키워드를 넣을 수 있지만 한 요청에 여러 query 값을 받지는 않습니다.

기본값은 12입니다. 12~2,000 범위의 정수이면서 12의 배수여야 하므로, 유효한 최대 한도는 1,992입니다.

아니요. 현재 SocQ 사양은 query와 results_limit만 받으며, 매칭, 정렬, 지역, 원본 적격 여부는 원본이 결정합니다.

요청한 한도에 도달하거나, 원본이 광고를 반환하지 않거나, 마지막 페이지를 알리거나, 커서를 생략하거나, 커서를 반복하면 수집이 멈춥니다. 공개 범위와 지역 규칙도 제공 여부에 영향을 줄 수 있습니다.

수집기는 커서 순환을 방지하지만 페이지 간 레코드 중복 제거는 보장하지 않습니다. 필요하면 null이 아닌 광고 id 기준으로 후속 단계에서 중복을 제거하세요.

반환된 광고 레코드 1개당 0.5 SocQ 크레딧이 차감되며 기본 요금은 없습니다. 기본 예상치는 결과 12건이고, 결과가 비어 있으면 결과 요금이 부과되지 않습니다.