메인 콘텐츠로 건너뛰기
Meta 광고 라이브러리를 비동기 task API로 검색해 JSON으로 받습니다. taskType ADS에 platform meta_ad_library를 보내고, query에 키워드를 넣거나 pageId에 광고주의 Facebook 페이지 ID를 넣습니다. 검색은 받은 광고 30개마다 0.5크레딧입니다. 광고주 이름으로 페이지 ID를 찾으려면 action advertisers를 보냅니다.

요청

task를 제출한 뒤 GET /v1/async/task/{id}를 폴링하거나 웹훅으로 받습니다. 참고: 비동기 task. 광고 30개 검색은 보통 몇 초, 광고 500개 검색은 1분 안팎에 끝납니다.

입력

  • action: search(기본값), 또는 이름으로 광고주를 찾는 advertisers.
  • query: 키워드. 광고 문구에 든 단어를 순서와 관계없이 찾습니다. pageId가 없으면 필수입니다.
  • pageId: 광고주의 숫자 Facebook 페이지 ID(예: 266556540473351). 그 광고주의 광고를 모으고, query와 함께 주면 그 광고 안에서 검색합니다.
  • country: 광고가 게재된 국가의 2글자 코드, 또는 모든 국가를 뜻하는 ALL. 기본값은 US입니다.
  • activeStatus: active(기본값), inactive, all.
  • limit: 광고 1-500개. 기본값은 30입니다.
  • cursor: 이전 응답의 nextCursor. 그 뒤의 광고를 이어서 받습니다.
  • searchType: keyword_unordered(기본값) 또는 keyword_exact_phrase.
  • adType: all(기본값), political_and_issue_ads, housing_ads, employment_ads, financial_products_and_services_ads.
  • mediaType: all(기본값), image, meme, image_and_meme, video, none.
  • publisherPlatforms: facebook, instagram, audience_network, messenger, whatsapp, threads 중 하나 이상. 배열이나 쉼표로 구분한 텍스트로 보냅니다.
  • contentLanguages: 2글자 언어 코드 하나 이상.
  • startDate, endDate: YYYY-MM-DD. 두 날짜 사이에 노출된 광고를 남깁니다.
  • sortBy: impressions_high_to_low(기본값) 또는 most_recent. impressions_low_to_high는 adType political_and_issue_ads와 함께만 씁니다. 라이브러리가 이 순서로 정렬하는 광고는 그 유형뿐입니다.
라이브러리가 검색할 수 없는 값은 400 VALIDATION_ERROR로 거절하고, details가 그 필드를 알려 줍니다.

광고 더 받기

받을 광고가 더 있으면 응답에 nextCursor가 붙습니다. 같은 검색에 이 값을 cursor로 보내면 다음 광고를 다시 limit만큼 받습니다. position은 이전 응답에 이어지고, 라이브러리에 광고가 더 없으면 nextCursor는 null입니다.
커서는 그 커서를 돌려준 검색에서만 씁니다. query, pageId, country, activeStatus나 필터가 다르면 400 VALIDATION_ERROR로 거절하고, limit은 바꿔도 됩니다. 커서는 앞서 읽은 광고가 많을수록 길어져 광고 1,000개 뒤에는 약 14KB이므로, 길이 제한 없는 텍스트로 저장합니다. 라이브러리가 같은 광고를 두 번 보여 줄 때가 있어 다음 응답에 같은 광고가 다시 올 수 있습니다. 중복은 libraryId로 거릅니다.

광고주 찾기

action advertisers는 광고 라이브러리 검색창이 제안하는 것처럼 이름이 query와 맞는 광고주의 Facebook 페이지를 돌려줍니다. 고른 광고주의 pageId로 그 광고주의 광고를 검색합니다.
광고주마다 position, pageId, name, category, likeCount, verified(Meta 파란 인증 배지), country(Meta가 페이지 국가를 밝힌 경우, 예: 글로벌 브랜드의 영국 페이지), pageAlias, profileUrl, pictureUrl, instagramUsername, instagramFollowerCount, instagramVerified, 광고 라이브러리에서 그 광고주의 광고를 여는 libraryUrl이 있습니다. keywords는 라이브러리가 그 이름으로 제안하는 검색어입니다. 라이브러리는 페이지에 적힌 이름으로 찾으므로 Shokz는 Shokz 페이지를 찾고 샥즈는 찾지 못합니다. 맞는 페이지가 없으면 빈 advertisers로 완료됩니다. 광고주 검색은 query와 country만 받고 0.5크레딧입니다.

응답 예시

결과 필드

  • 응답은 platform, action, country, query 또는 pageId, activeStatus와 받은 필터를 그대로 돌려줍니다.
  • totalCount는 라이브러리가 센 조건에 맞는 광고 수이고, 큰 검색에서는 라이브러리가 반올림합니다. returnedCount는 ads의 광고 수, hasMore는 라이브러리에 광고가 더 있으면 true이며 nextCursor로 이어 받고, libraryUrl은 같은 검색을 광고 라이브러리에서 엽니다.
  • 광고마다 position, libraryId, libraryUrl, isActive, startDate와 endDate(UTC 날짜), platforms, versions(이 소재와 문구를 쓰는 광고 수), format(IMAGE, VIDEO, CAROUSEL, DCO, DPA, MULTI_IMAGES 등), body, title, caption, linkUrl, linkDescription, ctaText, ctaType, categories(POLITICAL, EMPLOYMENT처럼 라이브러리가 매긴 광고 분류)가 있습니다.
  • 광고주는 pageId, pageName, pageProfileUrl, pageProfilePictureUrl, pageLikeCount, pageCategories입니다. 사회 이슈, 선거, 정치 광고에는 광고비를 낸 주체인 byline과 disclaimerLabel이 붙고, 유료 파트너십 광고에는 파트너 페이지가 brandedContent로 붙습니다.
  • 미디어는 images(url, resizedUrl), videos(hdUrl, sdUrl, previewImageUrl), cards입니다. cards는 캐러셀이나 카탈로그 광고의 카드이고, 카드마다 title, body, linkUrl, caption, linkDescription, ctaText, ctaType, imageUrl, resizedImageUrl, video가 있습니다. 다이내믹 광고의 다른 문구, 링크, 이미지, 동영상은 extraTexts, extraLinks, extraImages, extraVideos에 담깁니다.
  • 미디어 URL은 며칠 뒤 만료되는 Meta CDN 링크이므로 필요한 파일은 따로 저장합니다.
  • 카탈로그 광고(DPA, DCO)의 문구에는 {{product.name}} 같은 라이브러리의 자리 표시자가 그대로 남습니다.
  • spend, currency, impressions, reach는 라이브러리가 공개하는 광고에만 있습니다. 사회 이슈, 선거, 정치 광고와 EU에 노출된 광고입니다.
  • 조건에 맞는 광고가 없는 검색은 빈 ads와 totalCount 0으로 완료됩니다.

가격

검색은 시작할 때 limit이 요청한 광고 30개마다 0.5크레딧을 보류하고, 받은 광고 30개마다 0.5크레딧을 과금하며 최소 0.5크레딧입니다. 기본 검색(광고 30개)은 0.5크레딧이고, limit 500 검색은 8.5크레딧을 보류합니다. 광고주 검색은 0.5크레딧입니다. 완료된 요청만 과금합니다.

관련 문서