Google Ad Library Company Ads
Google Ads Transparency Center의 광고 소재 목록은 선택한 광고주 ID나 회사 도메인으로 나열할 수 있고, 공개된 검색 필터로 범위를 좁힐 수 있습니다. 이 작업에서는 광고별 상세 정보 보강이 꺼져 있으므로, 목록 단계에서 가장 믿을 수 있는 값은 소재 식별자와 원본 URL입니다.
Google Ad Library Company Ads API 주요 기능
- 광고주 또는 도메인 기준 시작Google 광고주 ID 또는 회사 도메인 중 하나 이상을 지정하세요. 둘 다 지정하면 두 값을 어떻게 교차시킬지는 상위 원본이 정합니다.
- 검증된 목록 필터주제, 지역, 기간, Google 게재 영역, 텍스트·이미지·동영상 형식 값으로 공개 소재 색인의 범위를 좁힙니다.
- 커서 기반 수집제공처 커서를 따라 40건 단위 페이지로 수집하고, 요청한 40~2,000건의 결과 제한, 마지막 페이지, 빈 페이지, 잘못 반복된 커서 중 먼저 나타나는 지점에서 멈춥니다.
- 안정적인 광고 레코드공통 정규화 광고 구조로 반환하며, 목록 단계에서 null이거나 비어 있는 상세 필드는 소재 정보를 지어내지 않고 그대로 보존합니다.
Google Ad Library Company Ads API 매개변수
| 매개변수 | 필수 | 설명 |
|---|---|---|
domain | 필수(하나 이상) | lululemon.com 같은 회사 웹사이트 도메인입니다. domain과 advertiser_id 중 하나 이상이 필요하며, 도메인 일치는 둘 이상의 광고주 레코드에 걸칠 수 있습니다. |
advertiser_id | 필수(하나 이상) | 보통 AR로 시작하는 Google Transparency Center 광고주 식별자입니다. 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의 배수인 40~2,000 사이로 설정한 뒤, 요청을 /v1/google-ad-library/company-ads로 POST합니다.
- 작업이 성공하거나 실패할 때까지 /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 retrievalGoogle Ad Library Company Ads API 추천 활용 사례
- 선별 상세 조회 대기열 구축: 광고주 한 곳의 소재 ID와 공개 URL을 나열한 뒤, 관련 있는 레코드만 골라 더 풍부한 상세 조회를 요청합니다.
- 관찰 가능한 형식 구성 비교: 식별자, 필터, 개수 제한, 수집 기간을 동일하게 맞춘 상태에서 반환된 텍스트, 이미지, 동영상 색인 레코드의 수를 셉니다.
- 공개된 게재 기간 검토: 비슷한 기간, 지역, 주제, Google 게재 영역 필터로 반환된 소재 레코드를 확인하되, 비공개 타기팅 데이터로 해석하지는 않습니다.
Google Ad Library Company Ads API 활용 팁
- 대상 Transparency Center 주체를 이미 알고 있다면 범위가 넓은 도메인보다 확인된 advertiser_id를 사용하세요.
- 시간에 따른 소재 목록을 비교할 때는 식별자, 필터, results_limit, 수집 날짜를 일관되게 유지하세요.
- get_ad_details가 항상 false이므로, 목록 단계에서는 텍스트, 날짜, 이동 대상, 노출 수, 미디어가 null이거나 비어 있을 수 있습니다.
- 성공했지만 비어 있는 결과는 제출한 식별자와 필터 기준으로 그 시점에 쓸 수 있는 소재가 없다는 뜻이며, 해당 회사가 광고를 한 적이 없다는 증거는 아닙니다.
관련 API
Google Ad Library Company Ads API 외에 Google Ad Library의 다른 유형의 공개 데이터가 필요할 때 이 API를 사용하세요.
- Google Ad Library Ad API — URL로 알고 있는 공개 Transparency Center 크리에이티브 하나를 가져오며, 광고주, 문구, 미디어, 게재, 지역, 형식, 랜딩, 노출 필드를 포함합니다.
- Google Ad Library Advertiser Search API — 검색어와 선택 지역으로 공개 Transparency Center 광고주 후보를 찾고, 계정 정보, 웹사이트, 로고, 지역, 확인 가능한 광고 수 필드를 반환합니다.