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 страницы рекламодателя с необязательными фильтрами, отслеживайте асинхронную задачу и читайте нормализованные записи объявлений с курсорной пагинацией.
- Получите числовой ID страницы рекламодателя и выберите нужные фильтры по стране, статусу, медиафайлам, языку, сортировке или датам.
- Отправьте page_id и выбранные фильтры на /v1/facebook-ad-library/company-ads и сохраните task_id.
- Опрашивайте /v1/tasks/{task_id}, пока обработка не завершится успешно или не вернет ошибку.
- Читайте 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) для группировки, а не для выводов об эффективности.
Связанные API
Помимо 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 и видимые сигналы.