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 креативов для выборочного получения деталей.
- Выберите advertiser_id или domain; добавляйте только те фильтры, которые относятся к задаче сравнения или сбора.
- Задайте results_limit от 40 до 2 000 с шагом 40 и отправьте запрос методом POST на /v1/google-ad-library/company-ads.
- Опрашивайте /v1/tasks/{task_id}, пока задача не завершится успешно или с ошибкой, затем при необходимости листайте сохраненные результаты задачи.
- Считайте 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.
- Считайте успешный пустой результат отсутствием пригодных креативов для переданных идентификаторов и фильтров на тот момент, а не доказательством того, что компания никогда не размещала рекламу.
Связанные API
Помимо 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 по запросу и необязательному региону: данные рекламодателя, сайт, логотип, регион и доступное число объявлений.