Google Ad Library Company Ads
El inventario de creatividades de Google Ads Transparency Center se puede enumerar a partir de un ID de anunciante o de un dominio de empresa seleccionados, y acotar con filtros de consulta públicos. Los identificadores de las creatividades y las URL de origen son los valores más confiables a nivel de lista, porque el enriquecimiento con detalles por anuncio está deshabilitado en esta operación.
Funcionalidades de la Google Ad Library Company Ads API
- Punto de partida por anunciante o dominioIndique al menos un ID de anunciante de Google o un dominio de empresa; cuando están presentes ambos, la fuente en origen define cómo se combinan.
- Filtros de inventario validadosAcote el índice público de creatividades por tema, región, ventana de fechas, superficie de Google o valores de formato de texto, imagen y video.
- Recopilación basada en cursoresSigue los cursores del proveedor en páginas de 40 registros y se detiene en el límite de resultados solicitado de 40–2,000, en la última página, en una página vacía o ante un cursor repetido no válido.
- Registros de anuncios establesDevuelve la estructura de anuncio normalizada compartida y conserva como nulos o vacíos los campos de detalle a nivel de lista, en lugar de inventar un enriquecimiento de la creatividad.
Parámetros de la Google Ad Library Company Ads API
| Parámetros | Obligatorio | Descripción |
|---|---|---|
domain | Obligatorio (al menos uno) | Dominio del sitio web de la empresa, como lululemon.com. Se requiere al menos uno de domain o advertiser_id; la coincidencia por dominio puede abarcar más de un registro de anunciante. |
advertiser_id | Obligatorio (al menos uno) | Identificador de anunciante de Google Transparency Center, que normalmente comienza con AR. Se requiere al menos uno de advertiser_id o domain. |
topic | Opcional | Filtro público opcional de tema de la fuente: all o political. El comportamiento y la cobertura del filtro los define la fuente. |
region | Opcional | Código de región opcional, como US, que se reenvía como contexto de consulta público y no como una definición completa de segmentación. |
start_date | Opcional | Filtro opcional de fecha de la fuente, inclusivo, en formato YYYY-MM-DD. No puede ser posterior a end_date cuando se indican ambas fechas. |
end_date | Opcional | Filtro opcional de fecha de la fuente en formato YYYY-MM-DD. No puede ser anterior a start_date cuando se indican ambas fechas. |
platform | Opcional | Superficie de Google opcional: google_maps, google_play, google_search, google_shopping o youtube. |
format | Opcional | Formato de creatividad opcional: text, image o video. Las variaciones similares de una creatividad aún pueden aparecer como registros separados. |
results_limit | Opcional | Máximo de registros de creatividades almacenados. Su valor predeterminado es 40 y acepta enteros de 40 a 2,000 en múltiplos de 40. |
Cómo usar la Google Ad Library Company Ads API
Envíe una solicitud estructurada de inventario de un anunciante, siga su tarea asíncrona y use las URL de creatividades devueltas para obtener detalles de forma selectiva.
- Elija un advertiser_id o un domain; agregue solo los filtros que correspondan a la pregunta de comparación o de recopilación.
- Defina results_limit entre 40 y 2,000 en múltiplos de 40 y luego envíe la solicitud por POST a /v1/google-ad-library/company-ads.
- Consulte /v1/tasks/{task_id} hasta que la tarea se complete con éxito o falle y, si hace falta, recorra por páginas los resultados almacenados de la tarea.
- Trate los ID y las URL de creatividades como registros de índice; envíe las URL seleccionadas a la operación aparte de detalle de anuncio cuando necesite campos más completos.
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 retrievalCasos de uso de la Google Ad Library Company Ads API
- Armar una cola selectiva de detalle: Enumere los ID de creatividades y las URL públicas de un anunciante y luego elija solo los registros relevantes para solicitudes de detalle más completas.
- Comparar mezclas de formatos observables: Cuente los registros de índice de texto, imagen y video devueltos con identificadores, filtros, límites y ventanas de recopilación consistentes.
- Revisar las ventanas de entrega divulgadas: Identifique los registros de creatividades devueltos con filtros comparables de fecha, región, tema o superficie de Google, sin tratarlos como datos privados de segmentación.
Consejos de expertos para la Google Ad Library Company Ads API
- Prefiera un advertiser_id verificado a un dominio amplio cuando ya se conozca la entidad de Transparency Center que se busca.
- Mantenga consistentes los identificadores, los filtros, results_limit y las fechas de recopilación al comparar inventarios de creatividades a lo largo del tiempo.
- Espere que el texto, las fechas, el destino, las impresiones y el contenido multimedia sean nulos o estén vacíos a nivel de lista, porque get_ad_details siempre es false.
- Trate un resultado vacío exitoso como ausencia de creatividades utilizables con los identificadores y filtros enviados en ese momento, no como prueba de que la empresa nunca haya anunciado.
APIs relacionadas
Además de la Google Ad Library Company Ads API, use estas APIs cuando necesite otro tipo de datos públicos de Google Ad Library.
- Google Ad Library Ad API — Obtiene un creativo público conocido del Transparency Center mediante su URL, con campos de anunciante, texto, contenido multimedia, entrega, región, formato, destino e impresiones.
- Google Ad Library Advertiser Search API — Descubre anunciantes candidatos del Transparency Center por consulta y región opcional, con campos de identidad, sitio web, logotipo, región y cantidad de anuncios disponible.