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只能与adTypepolitical_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和totalCount0完成。
价格
搜索开始时按limit 请求的每 30 条广告冻结 0.5 积分,并按返回的每 30 条广告扣除 0.5 积分,最少 0.5 积分。默认搜索(30 条广告)消耗 0.5 积分,limit 为 500 的搜索冻结 8.5 积分。广告主搜索消耗 0.5 积分。只对完成的请求计费。