facebook-ad-library/
company-ads

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

Facebook Ad Library Company Ads API

ID страницы рекламодателя
Креатив и показ
Публичные записи объявлений
0,5 кредита за результат
Готово
Готово

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

README

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

Facebook Ad Library Company Ads

Объявления компаний в Facebook Ad Library — это публичные записи рекламодателей с текстом креатива, медиафайлами, данными страницы, датами показа, статусом активности, платформами размещения, странами и видимыми показателями. Такие записи помогают отслеживать рекламодателей, сравнивать креативы, анализировать отдельные рынки и готовить отчеты на момент сбора.

Возможности Facebook Ad Library Company Ads API

  • Сбор в рамках страницы рекламодателяИспользуйте один числовой ID страницы рекламодателя, чтобы каждое возвращенное объявление было связано с выбранной публичной страницей, а не с поиском по ключевому слову.
  • Фильтры по рынку и показуСужайте сбор по стране, статусу показа, типу медиафайлов, языку, диапазону дат и поддерживаемому порядку сортировки до сохранения записей.
  • Поля креатива, медиафайлов и целевых ссылокВозвращает доступные заголовки, основной текст, изображения или видео, значения CTA, публичные целевые URL и форматы показа для каждого объявления.
  • Рекламодатель и параметры показаСохраняет данные страницы, лайки страницы, даты показа, статус активности, платформы размещения, страны, охват, валюту и расходы, если они публично доступны.
  • Ограниченный набор уникальных объявленийПроходит по доступным страницам источника, удаляет дубликаты архивных ID или URL и останавливается на results_limit или на последней доступной странице.

Параметры Facebook Ad Library Company Ads API

ПараметрыОбязательныйОписание
page_idОбязательныйОбязательный числовой ID страницы рекламодателя в Facebook Ad Library. Если ID страницы неизвестен, сначала используйте Company Search; одна задача принимает один ID страницы.
results_limitНеобязательныйМаксимальное число уникальных объявлений для сохранения. По умолчанию 100, допустимы целые числа от 20 до 2 000.
countryНеобязательныйИспользуйте ALL или один двухбуквенный код страны. По умолчанию ALL.
statusНеобязательныйФильтр по статусу показа объявления. Используйте строго ALL, ACTIVE или INACTIVE; по умолчанию ACTIVE.
media_typeНеобязательныйФильтр по типу медиафайлов креатива. Используйте строго ALL, IMAGE, VIDEO, MEME, IMAGE_AND_MEME или NONE; по умолчанию ALL.
languageНеобязательныйНеобязательный двухбуквенный код языка объявления.
sort_byНеобязательныйСортировка возвращаемых объявлений по total_impressions или relevancy_monthly_grouped; по умолчанию total_impressions.
start_dateНеобязательныйНеобязательная дата начала в формате YYYY-MM-DD. Не может быть позже end_date.
end_dateНеобязательныйНеобязательная дата окончания в формате YYYY-MM-DD. Не может быть раньше start_date.

Как использовать Facebook Ad Library Company Ads API

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

  1. Получите числовой ID страницы рекламодателя и выберите нужные фильтры по стране, статусу, медиафайлам, языку, сортировке или датам.
  2. Отправьте page_id и выбранные фильтры на /v1/facebook-ad-library/company-ads и сохраните task_id.
  3. Опрашивайте /v1/tasks/{task_id}, пока обработка не завершится успешно или не вернет ошибку.
  4. Читайте data.results.items, затем запрашивайте следующую страницу с next_cursor, пока has_more равно true.
curl -X POST "https://api.socq.ai/v1/facebook-ad-library/company-ads" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"page_id":"51212153078","results_limit":100,"country":"US","status":"ACTIVE","media_type":"ALL"}'

# Poll GET /v1/tasks/{task_id}
# Read data.results.items and follow next_cursor while has_more is true

Сценарии использования Facebook Ad Library Company Ads API

  • Мониторинг рекламы рекламодателя: Отслеживайте архивные ID, текст креативов, медиафайлы, статус активности, даты показа, URL источника и collected_at для известной страницы рекламодателя.
  • Сравнение креативов и форматов: Сравнивайте текст, изображения или видео, формат показа, CTA, целевые ссылки и контекст группировки (collation) у возвращенных объявлений страницы.
  • Анализ рекламы с фильтром по рынку: Применяйте фильтры по стране, языку, статусу, медиафайлам и датам, чтобы формировать отдельные наборы объявлений под конкретные вопросы о рынке или показе.
  • Отчеты по снимкам публичных показателей: Объединяйте данные страницы, лайки страницы, охват, расходы, валюту, статус показа и collected_at, если эти публичные значения доступны.

Практические советы по Facebook Ad Library Company Ads API

  • Начинайте с country = ALL и широких фильтров по медиафайлам и датам, затем сужайте по одному условию за раз, чтобы правильно интерпретировать пустой результат.
  • Используйте минимальный results_limit, равный 20, пока проверяете ID страницы и набор фильтров, и увеличивайте его, только когда охват результатов соответствует задаче.
  • Для брендов с несколькими ID страниц рекламодателя отправляйте отдельные задачи: один запрос Company Ads принимает один ID страницы.
  • Удаляйте дубликаты повторных запусков по id объявления, считайте отсутствующие охват, расходы, медиафайлы и даты недоступными, а не нулевыми, и используйте поля группировки (collation) для группировки, а не для выводов об эффективности.

Помимо Facebook Ad Library Company Ads API, используйте эти API, когда нужен другой тип публичных данных Facebook Ad Library.

  • Facebook Ad Library Search API — Ищите публичную рекламу по ключевому слову с настройкой совпадения, типа рекламы, страны, статуса, медиа, сортировки, дат и лимита результатов.
  • Facebook Ad Library Company Search API — Находите рекламодателей по названию компании или страницы: Page ID, классификация, изображения, видимая аудитория и связанные сигналы Instagram.
  • Facebook Ad Library Ad API — Собирайте одно публичное объявление из Ad Library по его URL: креатив, рекламодатель, медиа, показ, CTA и видимые сигналы.

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

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

Facebook Ad Library Company Ads API — FAQ

Facebook Ad Library Company Ads API получает публичные объявления по одному числовому ID страницы рекламодателя. Он возвращает нормализованные поля креатива, медиафайлов, рекламодателя, показа, рынка, CTA, видимых показателей и времени сбора.

Используйте Facebook Ad Library Company Search с названием компании или бренда, затем выберите правильный числовой ID страницы среди возвращенных кандидатов и только потом отправляйте запрос Company Ads.

Можно фильтровать по стране, статусу показа, типу медиафайлов, двухбуквенному коду языка, датам начала и окончания, а также выбрать один из двух поддерживаемых порядков сортировки. results_limit задает максимальное число сохраняемых уникальных объявлений.

У выбранной страницы может не быть публично доступных объявлений, подходящих под фильтры по стране, статусу, медиафайлам, языку или датам, либо в источнике может не оказаться следующей страницы. Успешный пустой результат не создает объявления-заглушки.

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