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 사용 방법
광고 표본을 정의하는 필터와 함께 키워드를 제출하고, 완료된 비동기 작업에서 정규화된 레코드를 모두 읽습니다.
- 비어 있지 않은 query를 하나 준비하고, 필요에 따라 일치 방식, 광고 유형, 국가, 상태, 미디어, 정렬, 기간, 결과 수 제한을 선택합니다.
- 요청을 /v1/facebook-ad-library/search로 POST하고, 반환된 task_id를 저장합니다.
- 작업이 성공하거나 실패할 때까지 /v1/tasks/{task_id}를 폴링합니다.
- 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 trueFacebook 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이 아니라 공개되지 않은 데이터로 취급하세요.
관련 API
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, 공개된 신호 필드를 포함합니다.