Facebook Ad Library Ad
Объявления в Facebook Ad Library — это публичные записи о рекламе с текстом креатива, данными о рекламодателе, медиафайлами, призывами к действию, сроками показа, статусом активности и доступными показателями охвата или расходов. Эти поля помогают обогащать данные о выбранных объявлениях, анализировать креативы, отслеживать публичные показы и сравнивать данные на определенный момент времени.
Возможности Facebook Ad Library Ad API
- Обработка прямого URL Ad LibraryПревращает один публичный URL /ads/library с числовым параметром запроса id не более чем в одну нормализованную запись объявления.
- Креатив и данные о рекламодателеВозвращает архивный ID объявления, заголовок и текст креатива, данные страницы рекламодателя, публичный URL страницы, призыв к действию и целевую ссылку, если они доступны.
- Показ и видимые показателиСохраняет время начала и окончания, статус активности, платформы размещения, страны, лайки страницы, охват, валюту и расходы, если публичная запись их содержит.
- Нормализованные медиафайлы из нескольких карточекБерет для стандартных полей доступный текст снимка или первой карточки и удаляет дубликаты изображений и видео из снимка и карточек, не претендуя на полную таблицу вариантов.
Параметры Facebook Ad Library Ad API
| Параметры | Обязательный | Описание |
|---|---|---|
url | Обязательный | Обязательный URL публичного объявления в Facebook Ad Library. Используйте канонический вид https://www.facebook.com/ads/library/?id={numeric_id}; один запрос принимает один URL. |
Как использовать Facebook Ad Library Ad API
Отправьте один публичный URL Ad Library, отслеживайте асинхронную задачу и читайте нормализованную запись объявления из стандартной обертки результатов.
- Подготовьте один публичный URL Facebook Ad Library с путем /ads/library и числовым id в строке запроса.
- Отправьте url на /v1/facebook-ad-library/ad и сохраните возвращенный task_id.
- Опрашивайте /v1/tasks/{task_id}, пока задача не завершится успешно или не вернет ошибку.
- Читайте data.results.items; этот эндпоинт возвращает не более одной записи, поэтому next_cursor обычно остается null, а has_more — false.
curl -X POST "https://api.socq.ai/v1/facebook-ad-library/ad" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"https://www.facebook.com/ads/library/?id=702369045530963"}'
# Poll GET /v1/tasks/{task_id}
# Read data.results.items; this operation returns at most one itemСценарии использования Facebook Ad Library Ad API
- Обогащение выбранного объявления: Используйте архивный ID, данные о рекламодателе, заголовок креатива, основной текст, медиафайлы, CTA, целевой URL и исходный URL, чтобы дополнить имеющуюся запись об объявлении.
- Проверка креативов и целевых ссылок: Изучайте ссылки на изображения или видео без дубликатов вместе с форматом показа, текстом и типом CTA и публичной целевой ссылкой известного объявления.
- Анализ публичного контекста показа: Используйте статус активности, время начала и окончания, платформы размещения, страны и доступные поля охвата или расходов, чтобы изучать публичный контекст показа.
- Сохранение снимков объявления во времени: Сохраняйте поля креатива, рекламодателя, показа, видимых показателей, исходного URL и collected_at, чтобы позже сравнивать одно и то же известное объявление.
Практические советы по Facebook Ad Library Ad API
- Отправляйте URL Ad Library с точным путем /ads/library и числовым параметром запроса id; URL и ID страниц, URL публикаций и голые ID объявлений не принимаются.
- Считайте успешную задачу без записи допустимым результатом «недоступно» или «не найдено», если отправленный URL синтаксически корректен.
- Обрабатывайте охват, расходы, лайки страницы, медиафайлы, end_at, URL профиля рекламодателя, CTA и страны как необязательные публичные поля и не превращайте отсутствующие значения в ноль.
- Для объявлений с несколькими карточками или креативами используйте нормализованные name и text как репрезентативные поля и изучайте список медиафайлов без дубликатов, не считая его полной таблицей по каждому варианту.
Связанные API
Помимо Facebook Ad Library Ad API, используйте эти API, когда нужен другой тип публичных данных Facebook Ad Library.
- Facebook Ad Library Search API — Ищите публичную рекламу по ключевому слову с настройкой совпадения, типа рекламы, страны, статуса, медиа, сортировки, дат и лимита результатов.
- Facebook Ad Library Company Search API — Находите рекламодателей по названию компании или страницы: Page ID, классификация, изображения, видимая аудитория и связанные сигналы Instagram.
- Facebook Ad Library Company Ads API — Собирайте публичную рекламу одного рекламодателя по Page ID: креатив, показ, рынок, медиа, CTA и видимые сигналы.