TikTok Ad Library Search
TikTok Ad Library Search отправляет один запрос по имени рекламодателя или ключевому слову в публичную Ads Library и переходит по ее непрозрачному курсору, пока не будет достигнут запрошенный лимит, кратный размеру страницы, или условие остановки на стороне источника. Сервис предназначен для исследований прозрачности и поиска рекламы, а не для управления закрытыми кампаниями или измерения эффективности.
Возможности TikTok Ad Library Search API
- Один целевой запросИщите по одному обязательному непустому имени рекламодателя, названию бренда или ключевому слову.
- Сбор, кратный размеру страницыЗапрашивайте от 12 до 2 000 результатов с шагом 12; наибольшее допустимое значение — 1 992.
- Работа с непрозрачным курсоромПереходит по курсорам источника до достижения лимита, пустой страницы, сигнала окончания, отсутствующего или повторяющегося курсора.
- Нормализованные сводки объявленийПолучайте стабильные поля идентификации, рекламодателя, дат показа, размещения, целевой ссылки, показов, медиа, публикации и сбора.
- Значения null с учетом источникаПоля остаются null или пустыми, если публичный результат поиска содержит только краткую сводку или не включает это значение.
Параметры TikTok Ad Library Search API
| Параметры | Обязательный | Описание |
|---|---|---|
query | Обязательный | Обязательное непустое имя рекламодателя или ключевое слово. Принимается ровно один запрос. |
results_limit | Необязательный | Необязательный лимит результатов. По умолчанию 12; значение должно быть кратно 12 и находиться в диапазоне от 12 до 2 000, поэтому наибольшее допустимое значение — 1 992. |
Как использовать TikTok Ad Library Search API
Отправьте один запрос и допустимый лимит, кратный размеру страницы, опрашивайте асинхронную задачу и обрабатывайте страницы нормализованных результатов.
- Выберите одно имя рекламодателя или ключевое слово; эндпоинт не принимает список запросов.
- Отправьте query и необязательный results_limit методом POST на /v1/tiktok-ad-library/search.
- Опрашивайте /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.itemsСценарии использования TikTok 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, используйте эти API, когда нужен другой тип публичных данных TikTok Ad Library.
- TikTok Ad Library Ad API — Преобразуйте один известный URL публичной рекламы TikTok в нормализованные поля креатива, рекламодателя, показа, целевой страницы, показов, медиа, публикации и сбора.