facebook-ad-library/
ad

Получайте одно публичное объявление из Facebook Ad Library по его URL: текст креатива, данные о рекламодателе, медиафайлы, сроки показа и видимые показатели в виде нормализованной записи.

Facebook Ad Library Ad API

URL Ad Library
Креатив и рекламодатель
Публичные показатели показа
0,6 кредита за результат
Готово
Готово

Введите параметры и отправьте запрос. Здесь появятся статус задачи и нормализованные результаты.

README

Автор: SocQ · Обновлено

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, отслеживайте асинхронную задачу и читайте нормализованную запись объявления из стандартной обертки результатов.

  1. Подготовьте один публичный URL Facebook Ad Library с путем /ads/library и числовым id в строке запроса.
  2. Отправьте url на /v1/facebook-ad-library/ad и сохраните возвращенный task_id.
  3. Опрашивайте /v1/tasks/{task_id}, пока задача не завершится успешно или не вернет ошибку.
  4. Читайте 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 как репрезентативные поля и изучайте список медиафайлов без дубликатов, не считая его полной таблицей по каждому варианту.

Помимо 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 и видимые сигналы.

Другие платформы

Объединяйте данные Facebook Ad Library с публичными данными других поддерживаемых соцсетей.

Facebook Ad Library Ad API — FAQ

Facebook Ad Library Ad API получает одно публичное объявление по отправленному URL Ad Library. Он возвращает нормализованный текст креатива, данные о рекламодателе, медиафайлы, сроки показа, призывы к действию и доступные публичные показатели.

Отправьте один публичный URL в каноническом виде https://www.facebook.com/ads/library/?id={numeric_id}. Путь должен быть /ads/library, а параметр запроса id — числовым.

Запись может содержать архивный ID и URL объявления, заголовок и текст креатива, поля страницы рекламодателя, медиафайлы, даты и статус показа, платформы размещения, страны, параметры CTA, целевой URL, лайки страницы, охват, валюту, расходы и контекст сбора.

Синтаксически корректный URL может указывать на недоступное или ненайденное публичное объявление. В этом случае задача может завершиться успешно без создания результата-заглушки.

Нормализованные name и text берутся из доступных значений снимка или первой карточки, а media содержит уникальные медиафайлы из снимка и карточек. Запись не является полной таблицей всех вариантов креатива.

Каждая успешно возвращенная запись объявления стоит 0,6 кредита SocQ. Задача без результата не оплачивается.