TikTok Ad Library Ad
TikTok Ad Library Ad получает одну известную публичную рекламную запись, когда поиск или ручная проверка уже дали подходящий URL. Эндпоинт определяет один идентификатор источника и возвращает не более одного нормализованного объявления; он не ищет по рекламодателю, не перечисляет кампании и не раскрывает закрытые данные об эффективности из Ads Manager.
Возможности TikTok Ad Library Ad API
- URL известного объявления на входеОтправьте один официальный URL TikTok с http или https, путь которого содержит /ad.
- Определение идентификатораСначала берется первое значение id в строке запроса, затем ad_id, затем крайний правый числовой сегмент пути; иначе источник получает URL как резервный вариант.
- Детали одного объектаЗапрашивает у источника один объект с деталями и возвращает не более одной записи, только если в нем есть поддерживаемый идентификатор объявления.
- Канонические поля объявленияПолучайте стабильные поля рекламодателя, текста, дат, стран, платформ, формата, целевой ссылки, показов, медиа, публикации и сбора.
- Точность источника и значения nullНедоступные значения остаются null, потому что записи Commercial Content Library и Creative Center могут содержать разные поля.
Параметры TikTok Ad Library Ad API
| Параметры | Обязательный | Описание |
|---|---|---|
url | Обязательный | Обязательный единственный официальный URL TikTok с http или https, путь которого содержит /ad. Предпочтительны URL с пригодным значением id или ad_id в строке запроса либо с числовым сегментом пути. |
Как использовать TikTok Ad Library Ad API
Отправьте известный URL публичного объявления, опрашивайте асинхронную задачу и обработайте единственный результат, если он есть.
- По возможности выберите официальный URL объявления TikTok с id, ad_id или числовым идентификатором в пути.
- Отправьте url методом POST на /v1/tiktok-ad-library/ad и сохраните возвращенный task_id.
- Опрашивайте /v1/tasks/{task_id}, пока задача не перейдет в конечный статус.
- После успешного завершения читайте data.results.items; эта операция получения деталей возвращает ноль или один элемент.
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 itemСценарии использования TikTok Ad Library Ad API
- Изучение выбранного объявления: Получайте для одного объявления, выбранного из результатов поиска, нормализованные поля, доступные на текущий момент.
- Анализ креатива: Изучайте публичный текст креатива, данные о рекламодателе, формат, медиа и целевую ссылку известного объявления.
- Архив для прозрачности: Сохраняйте одну публичную запись с URL источника, датами показа, контекстом размещения и временем сбора.
- Сравнение между библиотеками: Сравнивайте поддерживаемые публичные метаданные выбранных объявлений, не считая их показателями эффективности кампании.
Практические советы по TikTok Ad Library Ad API
- Выбирайте URL с явным числовым значением id или ad_id в строке запроса, чтобы не зависеть от резервного поведения на стороне источника.
- Корректный URL не гарантирует, что источник все еще отдает идентифицируемый объект объявления.
- Считайте поля Ads Library и Creative Center специфичными для своего источника, а не взаимозаменяемыми.
- Архивируйте ссылки на медиа и целевые страницы только на допустимых условиях: URL могут устаревать или перенаправлять.
- Не делайте выводов о таргетинге, расходах, конверсиях или эффективности по публичным датам показа или показам.
- Для поиска используйте эндпоинт поиска; этот эндпоинт деталей никогда не перечисляет объявления рекламодателя.
Связанные API
Помимо TikTok Ad Library Ad API, используйте эти API, когда нужен другой тип публичных данных TikTok Ad Library.
- TikTok Ad Library Search API — Ищите поддерживаемые публичные рекламные записи TikTok по имени рекламодателя или ключевому слову с лимитом результатов, кратным размеру страницы.