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
Отправьте ключевое слово с фильтрами, которые определяют вашу выборку объявлений, затем прочитайте все нормализованные записи из завершенной асинхронной задачи.
- Подготовьте один непустой query и выберите необязательные параметры совпадения, типа объявления, страны, статуса, медиафайлов, сортировки, дат и лимита результатов.
- Отправьте запрос методом POST на /v1/facebook-ad-library/search и сохраните возвращенный 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/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 или страны недоступными публичными данными, а не нулем.
Связанные API
Помимо 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 и видимые сигналы.