TikTok Ad Library Ad
TikTok Ad Library Ad는 검색이나 직접 검토로 조건에 맞는 URL을 확보한 뒤, 알고 있는 공개 광고 레코드 하나를 조회합니다. 원본 식별자 하나를 도출해 정규화된 광고를 최대 하나만 반환하며, 광고주 검색, 캠페인 나열, 비공개 Ads Manager 성과 데이터 노출은 하지 않습니다.
TikTok Ad Library Ad API 주요 기능
- 알고 있는 광고 URL 입력경로에 /ad가 포함된 TikTok 공식 http 또는 https URL 하나를 제출합니다.
- 식별자 도출첫 번째 id 쿼리 값을 우선 사용하고, 없으면 ad_id, 그다음으로 경로의 맨 오른쪽 숫자 세그먼트를 사용합니다. 모두 없으면 제공처가 URL 자체를 대체값으로 받습니다.
- 단일 객체 상세원본 상세 객체 하나를 요청하며, 지원되는 광고 식별 정보가 있을 때만 레코드를 최대 하나 생성합니다.
- 표준 광고 필드광고주, 문구, 날짜, 국가, 플랫폼, 형식, 랜딩, 노출, 미디어, 게시, 수집 필드를 안정적인 구조로 받습니다.
- null 허용으로 원본 충실도 유지Commercial Content Library와 Creative Center 레코드가 노출하는 필드는 서로 다를 수 있으므로, 제공되지 않는 값은 null로 유지합니다.
TikTok Ad Library Ad API 매개변수
| 매개변수 | 필수 | 설명 |
|---|---|---|
url | 필수 | 경로에 /ad가 포함된 TikTok 공식 http 또는 https URL 하나로, 필수 값입니다. 사용 가능한 id 또는 ad_id 쿼리 값이나 숫자 경로 세그먼트가 있는 URL을 권장합니다. |
TikTok Ad Library Ad API 사용 방법
알고 있는 공개 광고 URL을 제출하고, 비동기 작업을 폴링한 뒤, 결과가 있으면 단일 결과를 처리합니다.
- 가능하면 id, ad_id 또는 숫자 경로 식별자가 있는 TikTok 공식 광고 URL을 고릅니다.
- url을 /v1/tiktok-ad-library/ad로 POST하고, 반환된 task_id를 저장합니다.
- 작업이 최종 상태가 될 때까지 /v1/tasks/{task_id}를 폴링합니다.
- 성공하면 data.results.items를 읽습니다. 이 상세 조회는 항목을 0개 또는 1개 반환합니다.
curl -X POST "https://api.socq.ai/v1/tiktok-ad-library/ad" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"https://library.tiktok.com/ads/detail/?id=1871655924410641"}'
# Poll GET /v1/tasks/{task_id}
# Read data.results.items; the detail operation returns at most one itemTikTok Ad Library Ad API 추천 활용 사례
- 선택한 광고 확인: 검색 결과에서 고른 광고 하나를 현재 제공되는 정규화된 상세 필드로 조회합니다.
- 크리에이티브 검토: 알고 있는 광고의 공개 크리에이티브 문구, 광고주 정보, 형식, 미디어, 랜딩 정보를 살펴봅니다.
- 투명성 아카이브: 원본 URL, 노출 날짜, 게재 맥락, 수집 시각과 함께 공개 레코드 하나를 보존합니다.
- 라이브러리 간 비교: 선택한 광고 레코드들의 지원되는 공개 메타데이터를 비교하되, 캠페인 성과로 해석하지 않습니다.
TikTok Ad Library Ad API 활용 팁
- 제공처에 따라 달라지는 대체 동작을 피하려면, 숫자 id 또는 ad_id 쿼리 값이 명시된 URL을 사용하세요.
- 유효한 URL이라도 원본 소스가 식별 가능한 광고 객체를 계속 노출한다는 보장은 없습니다.
- Ads Library와 Creative Center의 필드는 서로 바꿔 쓸 수 있는 값이 아니라 소스별로 다른 값으로 취급하세요.
- URL은 만료되거나 리디렉션될 수 있으므로, 미디어나 랜딩 페이지 참조는 적절한 약관 범위 안에서만 보관하세요.
- 공개된 노출 날짜나 노출 수만으로 타기팅, 지출, 전환, 성과를 추정하지 마세요.
- 광고를 찾아야 할 때는 검색 엔드포인트를 사용하세요. 이 상세 엔드포인트는 광고주의 광고를 나열하지 않습니다.
관련 API
TikTok Ad Library Ad API 외에 TikTok Ad Library의 다른 유형의 공개 데이터가 필요할 때 이 API를 사용하세요.
- TikTok Ad Library Search API — 광고주 이름 또는 키워드 하나로 지원되는 공개 TikTok 광고 기록을 검색하며, 페이지 단위에 맞춘 결과 수 제한을 지정할 수 있습니다.