Facebook Ad Transcript
Facebook Ad Transcript — это записи устной речи, привязанные к объектам Ad Library, с исходным URL, текстом, языком, форматом, временем сбора и необязательным shortcode. Такие записи помогают анализировать рекламные сообщения, индексировать ключевые слова, обрабатывать текст с учетом языка и вести архивы со ссылками на источник.
Возможности Facebook Ad Transcript API
- Пакеты URL из Ad LibraryПринимает URL из Facebook Ad Library с поддерживаемых хостов Facebook и обрабатывает каждый уникальный URL как отдельный объект для расшифровки.
- Устный текст со ссылкой на источникВозвращает непустой текст расшифровки вместе с переданным исходным URL и идентификатором, который заменяется на URL, если ID источника отсутствует.
- Язык и форматДобавляет в нормализованную запись язык источника (может быть null), формат plaintext или WebVTT, время сбора и необязательный shortcode.
- Только доступные записиСохраняет результат, только если выбранное объявление дает непустую расшифровку, поэтому успешная задача может вернуть меньше записей, чем было передано URL.
Параметры Facebook Ad Transcript API
| Параметры | Обязательный | Описание |
|---|---|---|
urls | Обязательный | URL из Facebook Ad Library на поддерживаемых хостах Facebook, разделенные запятыми или переводами строки; каждый путь должен содержать /ads/library. |
Как использовать Facebook Ad Transcript API
Отправьте URL из Facebook Ad Library, затем сверьте возвращенные исходные URL: элементы результата создаются только для объектов с непустым текстом расшифровки.
- Подготовьте один или несколько URL из Facebook Ad Library с хостом facebook.com, www.facebook.com или m.facebook.com и путем, содержащим /ads/library.
- Отправьте urls методом POST на /v1/facebook/ad-transcript и сохраните возвращенный task_id.
- Опрашивайте /v1/tasks/{task_id}, пока задача не завершится успешно или с ошибкой.
- Читайте data.results.items, а если results.has_more равно true, запрашивайте следующую страницу с results.next_cursor.
curl -X POST "https://api.socq.ai/v1/facebook/ad-transcript" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"urls":["https://www.facebook.com/ads/library/?id=123456789012345"]}'
# Poll GET /v1/tasks/{task_id}
# Continue with GET /v1/tasks/{task_id}?limit=50&cursor={next_cursor}Сценарии использования Facebook Ad Transcript API
- Анализ рекламных сообщений: Читайте текст расшифровок со ссылками на источник, чтобы сравнивать формулировки, звучащие в выбранном наборе публичных объявлений.
- Индексация речи в рекламе для поиска: Индексируйте текст вместе с ID записей, исходными URL, временем сбора и shortcode, чтобы находить известные расшифровки рекламы по произнесенным словам.
- Маршрутизация обработки расшифровок: Используйте поля языка и формата, чтобы направлять записи plaintext и WebVTT в подходящий пайплайн обработки текста, субтитров или языка.
Практические советы по Facebook Ad Transcript API
- Используйте поддерживаемый хост Facebook и сохраняйте /ads/library в пути каждого URL: другие хосты или пути не проходят проверку запроса.
- Приводите URL из Ad Library к каноническому виду перед формированием пакета, если один и тот же объект встречается с разными строками запроса: сборщик удаляет только точные дубли строк.
- После успешного завершения сверяйте возвращенные значения url с отправленным списком, чтобы неподдерживаемые объявления и объекты без непустой расшифровки оставались видимыми в вашем рабочем процессе.
- Выбирайте способ разбора по format и обрабатывайте language и extra.shortcode как значения, которые могут быть null; поле created_at зарезервировано и сейчас возвращает null.
- Переходите по results.next_cursor, пока results.has_more равно true, если большой пакет URL не помещается в запрошенный лимит страницы результатов.
Связанные API
Помимо Facebook Ad Transcript API, используйте эти API, когда нужен другой тип публичных данных Facebook.
- Facebook Pages API — Получайте публичные профили страниц, контактные данные, изображения и видимые оценки аудитории.
- Facebook Posts API — Собирайте публичные публикации, медиа, реакции, комментарии и репосты по поддерживаемым URL Facebook.
- Facebook Video Transcript API — Извлекайте доступный текст расшифровки и формат по URL известных публичных видеопубликаций или Reels.
- Facebook Group Posts API — Собирайте публичные публикации по URL групп Facebook с выбором порядка, лимитом на группу, контекстом автора, видео и видимой вовлеченностью.
- Facebook Profile Photos API — Собирайте публичные фото по URL профилей или страниц: подписи, контекст автора, вовлеченность, метаданные изображений и ссылки на источник.
- Facebook Reels API — Собирайте публичные Reels по URL профилей или страниц: подписи, контекст автора, метаданные видео, видимая вовлеченность и ссылки на источник.