跳转到主要内容
通过异步任务 API 搜索 Meta 广告资料库,并以 JSON 获取结果。发送 taskType ADS 并设置 platform meta_ad_library,在 query 中填入关键词,或在 pageId 中填入广告主的 Facebook 主页 ID。搜索按返回的每 30 条广告 0.5 积分计费。如需按名称查找广告主的主页 ID,请发送 action advertisers。

请求

提交任务后,轮询 GET /v1/async/task/{id} 或通过 webhook 接收。参见异步任务。30 条广告的搜索通常几秒内完成,500 条广告的搜索约需一分钟。

参数

  • action:search(默认),或按名称查找广告主的 advertisers。
  • query:关键词。按任意顺序匹配广告文案中的词语。未设置 pageId 时必填。
  • pageId:广告主的数字 Facebook 主页 ID,例如 266556540473351。列出该广告主的广告,与 query 一起使用时在其中搜索。
  • country:广告投放国家的两字母代码,或表示所有国家的 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:一个或多个两字母语言代码。
  • 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 条广告后约为 14 KB,请以不限长度的文本保存。资料库有时会把同一条广告列出两次,因此后续响应中可能再次出现同一条广告,可用 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 只出现在资料库公开这些数据的广告中:社会议题、选举或政治广告,以及在欧盟展示的广告。
  • 没有符合条件的广告时,搜索以空的 ads 和 totalCount 0 完成。

价格

搜索开始时按 limit 请求的每 30 条广告冻结 0.5 积分,并按返回的每 30 条广告扣除 0.5 积分,最少 0.5 积分。默认搜索(30 条广告)消耗 0.5 积分,limit 为 500 的搜索冻结 8.5 积分。广告主搜索消耗 0.5 积分。只对完成的请求计费。

相关