facebook-ad-library/
search

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

Facebook Ad Library Search API

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

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

README

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

Facebook Ad Library Search

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

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

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

Параметры Facebook Ad Library Search API

ПараметрыОбязательныйОписание
queryОбязательныйОбязательное непустое ключевое слово или фраза для поиска публичных объявлений.
results_limitНеобязательныйМаксимальное число уникальных объявлений для сохранения. По умолчанию 100, принимает целые числа от 20 до 2 000.
search_typeНеобязательныйРежим совпадения по ключевым словам. По умолчанию keyword_unordered; используйте keyword_exact_phrase, если порядок слов должен совпадать.
ad_typeНеобязательныйФильтр по категории объявлений. По умолчанию all, можно ограничить значением political_and_issue_ads.
countryНеобязательныйФильтр по стране. Используйте ALL или двухбуквенный код страны; отправленные буквенные коды приводятся к верхнему регистру.
statusНеобязательныйФильтр по статусу показа. По умолчанию ACTIVE, поддерживаются ALL, ACTIVE и INACTIVE.
media_typeНеобязательныйФильтр по типу медиафайлов креатива. Поддерживает ALL, IMAGE, VIDEO, MEME, IMAGE_AND_MEME и NONE; по умолчанию ALL.
sort_byНеобязательныйПорядок результатов. По умолчанию total_impressions, также поддерживается relevancy_monthly_grouped.
start_dateНеобязательныйНеобязательная дата начала периода показов в формате YYYY-MM-DD.
end_dateНеобязательныйНеобязательная дата окончания периода показов в формате YYYY-MM-DD; не может быть раньше start_date.

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

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

  1. Подготовьте один непустой query и выберите необязательные параметры совпадения, типа объявления, страны, статуса, медиафайлов, сортировки, дат и лимита результатов.
  2. Отправьте запрос методом POST на /v1/facebook-ad-library/search и сохраните возвращенный 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/search" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"running shoes","results_limit":100,"country":"US","status":"ACTIVE","media_type":"VIDEO","search_type":"keyword_unordered"}'

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

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

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

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

  • Используйте keyword_exact_phrase, когда порядок слов важен для смысла, и keyword_unordered, когда в объявлениях порядок слов может меняться.
  • Применяйте фильтры по стране, статусу, медиафайлам, типу объявления и датам, прежде чем увеличивать results_limit, чтобы сохраненная выборка оставалась целевой.
  • Считайте results_limit верхней границей сбора, затем следуйте курсорам результатов задачи, пока has_more не станет false, чтобы прочитать все сохраненные записи.
  • Удаляйте дубликаты повторных запусков по архивному ID объявления или публичному URL объявления, сохраняя extra.search_query и collected_at как контекст наблюдения.
  • Считайте отсутствующие охват, расходы, лайки страницы, даты окончания, медиафайлы, CTA или страны недоступными публичными данными, а не нулем.

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

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

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

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

Facebook Ad Library Search API — FAQ

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

query обязателен. Запрос также принимает results_limit, sort_by, search_type, ad_type, country, status, media_type, start_date и end_date.

keyword_unordered находит слова запроса без требования к их исходному порядку, а keyword_exact_phrase сохраняет порядок слов во фразе. По умолчанию используется keyword_unordered.

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

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

results_limit по умолчанию равен 100 и принимает целые числа от 20 до 2 000 как максимальное число сохраняемых уникальных объявлений. После завершения задачи следуйте next_cursor, пока has_more равно true, чтобы прочитать все сохраненные страницы результатов.

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