google-ad-library/
ad

정확한 URL로 공개 Google Ads Transparency Center 광고 소재 1건을 조회하여, 광고주 정보, 문구, 미디어, 게재 기간, 지역, 형식, 이동 대상, 확인 가능한 노출 수를 정규화된 레코드로 반환합니다.

Google Ad Library Ad API

정확한 소재 URL
광고주와 미디어
공개된 게재 정보
결과당 0.5 크레딧
준비됨
준비됨

매개변수를 입력하고 요청을 전송하세요. 작업 상태와 정규화된 결과가 여기에 표시됩니다.

README

SocQ 작성 · 업데이트

Google Ad Library Ad

Google Ads Transparency Center의 광고 소재는 광고주 정보, 화면에 표시되는 문구와 미디어, 이동 링크, 형식, 게재 기간, 지역, 확인 가능한 노출 데이터를 담은 공개 광고 기록입니다. 이러한 세부 정보는 광고 소재 검증, 선별한 광고의 정보 보강, 게재 환경 조사, 특정 시점의 아카이브 비교에 활용할 수 있습니다.

Google Ad Library Ad API 주요 기능

  • 정확한 소재 단위 조회/creative/ 경로가 포함된 adstransparency.google.com URL 하나를 검색으로 확장하지 않고, 정규화된 공개 광고 레코드 최대 1건으로 조회합니다.
  • 광고주 및 소재 필드소재 식별자, 공개 원본 URL, 확인 가능한 텍스트, 광고주 참조 정보, 이동 대상, 형식을 안정적인 광고 스키마로 반환합니다.
  • 게재 정보확인 가능한 시작일과 종료일, 국가, 게재 위치를 보존하며, 노출 수는 원본 데이터를 안전하게 정규화할 수 있을 때만 단일 값으로 제공합니다.
  • 정규화된 미디어 자산확인 가능한 이미지 또는 동영상 참조를 썸네일, 크기, 재생 시간과 함께 제공하며, 값이 없는 선택 항목은 생략합니다.

Google Ad Library Ad API 매개변수

매개변수필수설명
url필수공개 Google Ads Transparency Center 소재 URL로, 필수 값입니다. 스킴은 http 또는 https여야 하고, 호스트는 adstransparency.google.com으로 끝나야 하며, 경로에는 /creative/가 포함되어야 합니다.

Google Ad Library Ad API 사용 방법

정확한 공개 소재 URL 하나를 제출하고, 비동기 작업을 추적한 뒤, 표준 결과 구조에서 정규화된 광고 레코드를 읽습니다.

  1. 경로에 /creative/가 포함된 adstransparency.google.com의 http 또는 https URL 하나를 준비합니다.
  2. url을 /v1/google-ad-library/ad로 POST하고, 반환된 task_id를 저장합니다.
  3. 작업이 성공하거나 실패할 때까지 /v1/tasks/{task_id}를 폴링합니다.
  4. data.results.items를 읽습니다. 이 상세 조회는 항목을 최대 1건만 반환하므로, 보통 has_more는 false이고 next_cursor는 null입니다.
curl -X POST "https://api.socq.ai/v1/google-ad-library/ad" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://adstransparency.google.com/advertiser/AR01614014350098432001/creative/CR10449491775734153217"}'

# Poll GET /v1/tasks/{task_id}
# Read data.results.items; this detail operation returns at most one item

Google Ad Library Ad API 추천 활용 사례

  • 선택한 소재 정보 보강: 소재 ID, 광고주 참조 정보, 문구, 이동 대상, 형식, 미디어, 원본 URL을 이용해 앞서 발견한 광고 레코드를 완성합니다.
  • 공개된 게재 근거 검토: 확인 가능한 기간, 국가, 게재 위치, 노출 수를 비교하여 알려진 소재가 언제 어디서 공개적으로 확인되었는지 기록합니다.
  • 소재 스냅샷 아카이브: 정규화된 텍스트, 미디어, 광고주, 게재, 이동 대상 정보와 collected_at 필드를 저장해 나중에 특정 시점끼리 비교합니다.

Google Ad Library Ad API 활용 팁

  • CR 식별자만 보내거나 광고주 URL을 보내지 말고 소재 URL 전체를 제출해야 호스트와 /creative/ 경로 검증을 통과합니다.
  • 항목 없이 성공한 작업과 제공처 오류는 구분해서 처리하세요. 삭제되었거나 제한되었거나 확인할 수 없는 소재는 사용할 수 있는 레코드가 없을 수 있습니다.
  • 게재, 텍스트, 이동 대상, 광고주, 노출 수, 미디어 필드의 null 값은 0이나 빈 값으로 바꾸지 말고 그대로 보존하세요.
  • 탐색이나 광고 목록 수집에는 광고주 검색과 회사 광고 엔드포인트를 사용하세요. 이 상세 조회는 제출한 소재만 의도적으로 조회합니다.

Google Ad Library Ad API 외에 Google Ad Library의 다른 유형의 공개 데이터가 필요할 때 이 API를 사용하세요.

  • Google Ad Library Advertiser Search API — 검색어와 선택 지역으로 공개 Transparency Center 광고주 후보를 찾고, 계정 정보, 웹사이트, 로고, 지역, 확인 가능한 광고 수 필드를 반환합니다.
  • Google Ad Library Company Ads API — 회사 도메인 또는 광고주 ID로 공개 Transparency Center 크리에이티브를 수집하며, 주제, 지역, 날짜, 게재면, 형식, 결과 수 제한을 지정할 수 있습니다.

다른 플랫폼 둘러보기

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

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

Google Ad Library Ad API는 정확한 URL로 공개 Google Ads Transparency Center 광고 소재 1건을 조회하는 프로그래밍 인터페이스입니다. 정규화된 광고주, 문구, 미디어, 게재, 지역, 형식, 이동 대상, 확인 가능한 노출 수 필드를 반환합니다.

호스트가 adstransparency.google.com으로 끝나고 경로에 /creative/가 포함된 http 또는 https URL 하나를 제출합니다. 소재 ID만 있는 값, 광고주 URL, 도메인, 검색어, URL 목록은 허용되지 않습니다.

정규화된 레코드에는 식별 정보, 원본 URL, 텍스트, 광고주, 게재 기간, 국가, 플랫폼, 형식, 이동 대상, 노출 수, 미디어, 게시 시각, 수집 시각이 정의되어 있습니다. 원본에 따라 제공되지 않는 필드는 null일 수 있고, 미디어는 비어 있을 수 있습니다.

유효한 소재 URL이라도 삭제되었거나, 제한되었거나, 형식이 올바르지 않거나, 현재 확인할 수 없는 공개 레코드를 가리킬 수 있습니다. 이 엔드포인트는 다른 소재로 대체하거나 요청을 검색으로 바꾸지 않습니다.

반환된 레코드 1건당 0.5 SocQ 크레딧이 차감됩니다. 반환된 레코드가 없으면 설정된 빈 결과 정책에 따라 기본 요금 0 크레딧만 청구됩니다.