google-ad-library/
company-ads

Получайте отфильтрованный перечень публичных креативов из Google Ads Transparency Center по ID рекламодателя или домену: нормализованные идентификаторы креативов, исходный URL, показы, формат и доступные поля деталей.

Google Ad Library Company Ads API

Объявления рекламодателя
Пагинация по 40 записей
Индекс креативов с фильтрами
0,5 кредита за результат
Готово
Готово

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

README

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

Google Ad Library Company Ads

Перечень креативов Google Ads Transparency Center можно получить по выбранному ID рекламодателя или домену компании и сузить с помощью публичных фильтров запроса. Идентификаторы креативов и исходные URL — самые надежные значения на уровне списка, поскольку обогащение деталями каждого объявления в этой операции отключено.

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

  • Рекламодатель или домен как отправная точкаУкажите хотя бы один ID рекламодателя Google или домен компании; если переданы оба, их пересечение определяет источник.
  • Проверяемые фильтры перечняСужайте публичный индекс креативов по теме, региону, периоду дат, сервису Google или формату: текст, изображение, видео.
  • Сбор по курсоруПереходит по курсорам провайдера страницами по 40 записей и останавливается на запрошенном лимите от 40 до 2 000 результатов, на последней или пустой странице либо при повторе недействительного курсора.
  • Стабильные записи объявленийВозвращает общую нормализованную структуру объявления, сохраняя null и пустые поля деталей на уровне списка, а не придумывая обогащение креативов.

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

ПараметрыОбязательныйОписание
domainОбязательный (хотя бы один)Домен сайта компании, например lululemon.com. Обязателен хотя бы один из параметров domain или advertiser_id; совпадение по домену может охватывать несколько записей рекламодателей.
advertiser_idОбязательный (хотя бы один)Идентификатор рекламодателя в Google Transparency Center, обычно начинается с AR. Обязателен хотя бы один из параметров advertiser_id или domain.
topicНеобязательныйНеобязательный фильтр темы публичного источника: all или political. Поведение фильтра и охват определяет источник.
regionНеобязательныйНеобязательный код региона, например US, передаваемый как контекст публичного запроса, а не как полное определение таргетинга.
start_dateНеобязательныйНеобязательный фильтр даты источника (включительно) в формате YYYY-MM-DD. Если указаны обе даты, она не может быть позже end_date.
end_dateНеобязательныйНеобязательный фильтр даты источника в формате YYYY-MM-DD. Если указаны обе даты, она не может быть раньше start_date.
platformНеобязательныйНеобязательный сервис Google: google_maps, google_play, google_search, google_shopping или youtube.
formatНеобязательныйНеобязательный формат креатива: text, image или video. Похожие варианты креатива всё равно могут появляться как отдельные записи.
results_limitНеобязательныйМаксимальное число сохраняемых записей креативов. По умолчанию 40, допускаются целые числа от 40 до 2 000 с шагом 40.

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

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

  1. Выберите advertiser_id или domain; добавляйте только те фильтры, которые относятся к задаче сравнения или сбора.
  2. Задайте results_limit от 40 до 2 000 с шагом 40 и отправьте запрос методом POST на /v1/google-ad-library/company-ads.
  3. Опрашивайте /v1/tasks/{task_id}, пока задача не завершится успешно или с ошибкой, затем при необходимости листайте сохраненные результаты задачи.
  4. Считайте ID и URL креативов индексными записями; если нужны более подробные поля, отправляйте выбранные URL в отдельную операцию получения деталей объявления.
curl -X POST "https://api.socq.ai/v1/google-ad-library/company-ads" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"advertiser_id":"AR01614014350098432001","region":"US","format":"video","results_limit":80}'

# Poll GET /v1/tasks/{task_id}
# Read data.results.items and select creative URLs for detail retrieval

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

  • Очередь для выборочного получения деталей: Получите список ID креативов и публичных URL одного рекламодателя, затем выберите только нужные записи для запросов с подробными данными.
  • Сравнение наблюдаемого соотношения форматов: Подсчитывайте возвращенные индексные записи текстовых, графических и видеокреативов при одинаковых идентификаторах, фильтрах, лимитах и периодах сбора.
  • Анализ раскрытых периодов показа: Находите записи креативов, возвращенные при сопоставимых фильтрах даты, региона, темы или сервиса Google, не считая их приватными данными таргетинга.

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

  • Предпочитайте проверенный advertiser_id широкому домену, если нужная организация в Transparency Center уже известна.
  • Сохраняйте одинаковые идентификаторы, фильтры, results_limit и даты сбора, когда сравниваете перечни креативов во времени.
  • Учитывайте, что текст, даты, целевая ссылка, показы и медиафайлы на уровне списка будут null или пустыми, поскольку get_ad_details всегда равно false.
  • Считайте успешный пустой результат отсутствием пригодных креативов для переданных идентификаторов и фильтров на тот момент, а не доказательством того, что компания никогда не размещала рекламу.

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

  • Google Ad Library Ad API — Получайте один известный публичный креатив из Transparency Center по URL: рекламодатель, текст, медиа, показ, регион, формат, целевая страница и показы.
  • Google Ad Library Advertiser Search API — Находите публичных рекламодателей в Transparency Center по запросу и необязательному региону: данные рекламодателя, сайт, логотип, регион и доступное число объявлений.

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

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

Google Ad Library Company Ads API — FAQ

Google Ad Library Company Ads API — это программный интерфейс для получения перечня публичных индексных записей креативов из Google Ads Transparency Center по ID рекламодателя или домену с необязательными фильтрами. Он возвращает нормализованные записи объявлений, в которых ID креативов и публичные URL обычно надежнее полей деталей.

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

По умолчанию он равен 40 и должен быть целым числом от 40 до 2 000 с шагом 40. SocQ переходит по курсорам провайдера и обрезает сохраненные строки на этом лимите.

Запрос списка всегда отправляет get_ad_details=false. Поля стабильной схемы остаются объявленными, но отсутствующие значения текста, медиафайлов, целевой ссылки, показа или числа показов не домысливаются.

Каждая сохраненная запись креатива стоит 0,5 кредита SocQ. Оценка исходит из 40 результатов и допускает превышение; за успешный пустой результат взимается только настроенная базовая плата в ноль кредитов.