facebook-ad-library/
search

키워드와 필터로 Facebook Ad Library의 공개 광고를 검색하고, 광고주, 광고 소재 텍스트, 미디어, 게재 정보, 공개된 지표를 정규화된 레코드로 반환합니다.

Facebook Ad Library Search API

키워드 광고 검색
광고 소재·게재 정보
공개 광고 데이터
결과당 0.5 크레딧
준비됨
준비됨

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

README

SocQ 작성 · 업데이트

Facebook Ad Library Search

Facebook 광고 라이브러리 검색 결과는 키워드와 일치하는 공개 광고로, 광고주 페이지 정보, 광고 소재 텍스트와 미디어, 게재 기간, 게재 플랫폼, 국가, 공개된 지표를 담고 있습니다. 이러한 레코드는 광고 소재 탐색, 광고주 조사, 진행 중인 광고 모니터링, 반복 가능한 검색 간 비교에 활용할 수 있습니다.

Facebook Ad Library Search API 주요 기능

  • 키워드·구문 일치비어 있지 않은 query를 하나 입력하고, 순서에 상관없는 키워드 일치와 정확한 구문 일치 중에서 골라 공개 광고의 선별 방식을 조절합니다.
  • 검색 필터와 정렬광고 유형, 국가, 게재 상태, 미디어 유형, 기간을 지정해 결과를 좁히고, 지원되는 노출 수 기준 또는 관련도 기준으로 정렬합니다.
  • 정규화된 광고·광고주 레코드광고 아카이브 식별 정보, 공개 원본 URL, 광고주 페이지 정보, 광고 소재 제목과 본문 텍스트, 수집 시각을 일관된 레코드로 반환합니다.
  • 광고 소재·게재·공개 정보확인 가능한 이미지나 동영상, 시작·종료 시각, 진행 상태, 게재 플랫폼, 국가, CTA 정보, 연결 대상, 공개된 지표를 보존합니다.
  • 상한이 있는 중복 제거 수집결과를 20건에서 2,000건까지 요청할 수 있으며, 중복된 아카이브 ID나 공개 광고 URL은 모든 결과 페이지를 통틀어 한 번만 저장됩니다.

Facebook Ad Library Search API 매개변수

매개변수필수설명
query필수공개 광고를 검색하는 데 사용하는 키워드 또는 구문으로, 비어 있지 않아야 하는 필수 값입니다.
results_limit선택저장할 고유 광고의 최대 개수입니다. 기본값은 100이며 20에서 2,000 사이의 정수를 지정할 수 있습니다.
search_type선택키워드 일치 방식입니다. 기본값은 keyword_unordered이며, 단어 순서가 일치해야 할 때는 keyword_exact_phrase를 사용합니다.
ad_type선택광고 카테고리 필터입니다. 기본값은 all이며 political_and_issue_ads로 한정할 수 있습니다.
country선택국가 필터입니다. ALL 또는 두 글자 국가 코드를 사용하며, 알파벳 코드는 대문자로 정규화됩니다.
status선택게재 상태 필터입니다. 기본값은 ACTIVE이며 ALL, ACTIVE, INACTIVE를 지원합니다.
media_type선택광고 소재 미디어 필터입니다. ALL, IMAGE, VIDEO, MEME, IMAGE_AND_MEME, NONE을 지원하며 기본값은 ALL입니다.
sort_by선택결과 정렬 기준입니다. 기본값은 total_impressions이며 relevancy_monthly_grouped도 지원합니다.
start_date선택노출 기간의 시작일로, YYYY-MM-DD 형식의 선택 값입니다.
end_date선택노출 기간의 종료일로, YYYY-MM-DD 형식의 선택 값이며 start_date보다 앞설 수 없습니다.

Facebook Ad Library Search API 사용 방법

광고 표본을 정의하는 필터와 함께 키워드를 제출하고, 완료된 비동기 작업에서 정규화된 레코드를 모두 읽습니다.

  1. 비어 있지 않은 query를 하나 준비하고, 필요에 따라 일치 방식, 광고 유형, 국가, 상태, 미디어, 정렬, 기간, 결과 수 제한을 선택합니다.
  2. 요청을 /v1/facebook-ad-library/search로 POST하고, 반환된 task_id를 저장합니다.
  3. 작업이 성공하거나 실패할 때까지 /v1/tasks/{task_id}를 폴링합니다.
  4. data.results.items를 읽고, has_more가 true인 동안에는 next_cursor를 따라 다음 결과를 가져옵니다.
curl -X POST "https://api.socq.ai/v1/facebook-ad-library/search" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"running shoes","results_limit":100,"country":"US","status":"ACTIVE","media_type":"VIDEO","search_type":"keyword_unordered"}'

# Poll GET /v1/tasks/{task_id}
# Read data.results.items and follow next_cursor while has_more is true

Facebook Ad Library Search API 추천 활용 사례

  • 키워드 중심 광고 탐색: 제출한 검색어, 광고 ID, 광고 소재 텍스트, 광고주 이름, 공개 URL로 일치하는 공개 광고를 추적 가능한 형태로 모읍니다.
  • 광고 소재·포맷 비교: 일치한 레코드 전반에서 광고 소재 제목, 본문 텍스트, 이미지, 동영상, 노출 형식, CTA 값, 연결 대상, 게재 플랫폼을 비교합니다.
  • 진행 중인 광고 모니터링: 정해 둔 검색어를 반복 실행하고, 관측 시점별로 광고 ID, 진행 상태, 시작·종료 시각, 게재 플랫폼, 수집 시각을 비교합니다.
  • 광고주 후보 조사: 광고주 페이지 ID, 이름, 별칭, URL, 공개된 페이지 좋아요 수와 일치한 광고 소재로 후속 조사 대상 페이지를 가려냅니다.

Facebook Ad Library Search API 활용 팁

  • 단어 순서에 의미가 있다면 keyword_exact_phrase를, 광고마다 구문 순서가 달라질 수 있다면 keyword_unordered를 사용하세요.
  • 저장되는 표본이 한곳에 모이도록 results_limit 값을 늘리기 전에 국가, 상태, 미디어, 광고 유형, 기간 필터부터 적용하세요.
  • results_limit 값은 수집 상한으로 보고, 저장된 레코드를 모두 읽으려면 has_more가 false가 될 때까지 작업 결과 커서를 따라가세요.
  • 반복 실행한 결과는 광고 아카이브 ID나 공개 광고 URL로 중복을 제거하되, 관측 맥락을 위해 extra.search_query와 collected_at은 함께 보존하세요.
  • 도달, 지출, 페이지 좋아요, 종료일, 미디어, CTA, 국가 값이 없으면 0이 아니라 공개되지 않은 데이터로 취급하세요.

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

  • Facebook Ad Library Company Search API — 회사 또는 페이지 이름으로 광고주 페이지 후보를 찾고, 페이지 ID, 분류, 이미지, 공개된 오디언스, 연결된 Instagram 신호를 반환합니다.
  • Facebook Ad Library Company Ads API — 광고주 페이지 ID 하나에 대한 공개 광고를 수집하며, 크리에이티브, 게재, 시장, 미디어, CTA, 공개된 신호 필드를 포함합니다.
  • Facebook Ad Library Ad API — URL로 광고 라이브러리의 공개 광고 하나를 수집하며, 크리에이티브, 광고주, 미디어, 게재, CTA, 공개된 신호 필드를 포함합니다.

다른 플랫폼 둘러보기

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

Facebook Ad Library Search API — 자주 묻는 질문

Facebook Ad Library Search API는 비어 있지 않은 키워드 또는 구문과 선택적 검색 필터로 공개 광고를 가져오는 API입니다. 정규화된 광고 식별 정보, 광고주 페이지 정보, 광고 소재 텍스트와 미디어, 게재 필드, 공개된 지표를 반환합니다.

query는 필수입니다. 그 밖에 results_limit, sort_by, search_type, ad_type, country, status, media_type, start_date, end_date를 받을 수 있습니다.

keyword_unordered는 검색어의 단어를 원래 순서와 관계없이 일치시키고, keyword_exact_phrase는 구문의 순서를 그대로 유지합니다. 기본값은 keyword_unordered입니다.

정규화된 결과에는 광고·광고주 식별 정보, 광고 소재 텍스트, 이미지나 동영상, 게재 기간과 상태, 게재 플랫폼, 국가, CTA·연결 대상 필드, 페이지 좋아요 수, 도달, 지출 정보, 수집 시각이 포함될 수 있습니다. 공개되지 않은 필드는 비어 있습니다.

키워드와 일치하는 공개 광고가 없거나, 선택한 국가, 상태, 미디어, 광고 유형, 기간 필터가 가능한 레코드를 모두 제외했을 수 있습니다. 공개 출처의 제공 여부 때문에 완료된 작업의 결과가 비어 있을 수도 있습니다.

results_limit 값은 저장할 고유 광고의 최대 개수로, 기본값은 100이며 20에서 2,000 사이의 정수를 받습니다. 작업이 완료되면 has_more가 true인 동안 next_cursor를 따라가 저장된 작업 결과 페이지를 모두 읽습니다.

반환된 정규화 광고 1건마다 0.5 SocQ 크레딧이 차감됩니다. 결과가 비어 있으면 결과 요금이 발생하지 않습니다.