google-ad-library/
company-ads

광고주 ID 또는 도메인으로 필터링한 공개 Google Ads Transparency Center 광고 소재 레코드를 나열하여, 정규화된 소재 식별 정보, 원본 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 주요 기능

  • 광고주 또는 도메인 기준 시작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 중 필요한 것만 골라 상세 조회에 사용합니다.

  1. advertiser_id 또는 domain을 정하고, 비교나 수집 목적에 맞는 필터만 추가합니다.
  2. results_limit을 40의 배수인 40~2,000 사이로 설정한 뒤, 요청을 /v1/google-ad-library/company-ads로 POST합니다.
  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 활용 팁

  • 대상 Transparency Center 주체를 이미 알고 있다면 범위가 넓은 도메인보다 확인된 advertiser_id를 사용하세요.
  • 시간에 따른 소재 목록을 비교할 때는 식별자, 필터, results_limit, 수집 날짜를 일관되게 유지하세요.
  • get_ad_details가 항상 false이므로, 목록 단계에서는 텍스트, 날짜, 이동 대상, 노출 수, 미디어가 null이거나 비어 있을 수 있습니다.
  • 성공했지만 비어 있는 결과는 제출한 식별자와 필터 기준으로 그 시점에 쓸 수 있는 소재가 없다는 뜻이며, 해당 회사가 광고를 한 적이 없다는 증거는 아닙니다.

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 광고주 후보를 찾고, 계정 정보, 웹사이트, 로고, 지역, 확인 가능한 광고 수 필드를 반환합니다.

다른 플랫폼 둘러보기

Google Ad Library 데이터를 지원되는 다른 소셜 플랫폼의 공개 데이터와 함께 활용하세요.

Google Ad Library Company Ads API — 자주 묻는 질문

Google Ad Library Company Ads API는 광고주 ID 또는 도메인과 선택 필터로 공개 Google Ads Transparency Center 광고 소재 색인 레코드를 나열하는 프로그래밍 인터페이스입니다. 정규화된 광고 레코드를 반환하며, 상세 필드보다 소재 ID와 공개 URL이 대체로 더 믿을 만합니다.

둘 중 하나 이상이 필요합니다. 광고주 ID는 보통 더 정확하고, 도메인은 여러 공개 광고주 주체의 레코드와 일치할 수 있습니다. 둘 다 지정하면 두 값이 함께 전달됩니다.

기본값은 40이며, 40 이상 2,000 이하이고 40의 배수인 정수여야 합니다. SocQ는 제공처 커서를 따라가며, 저장되는 행을 그 제한에서 잘라 냅니다.

목록 요청은 항상 get_ad_details=false로 전송됩니다. 안정적인 스키마 필드는 그대로 정의되어 있지만, 값이 없는 텍스트, 미디어, 이동 대상, 게재, 노출 수는 추정해서 채우지 않습니다.

저장된 소재 레코드 1건당 0.5 SocQ 크레딧이 차감됩니다. 예상 요금은 결과 40건을 기준으로 하며 초과분도 허용하고, 성공했지만 결과가 비어 있으면 설정된 기본 요금 0 크레딧만 청구됩니다.