taskType ADS 发送 platform linkedin_ad_library,并用 action 选择要读取的内容。要在各广告资料库之间选择,参见 广告资料库对比。
search(默认)按query中的关键词、advertiserName中的广告主名称、payer中的付费方,或它们的组合来列出广告。每条广告带有广告主、形式、标题、文案和媒体,响应末尾附有汇总所返回广告的summary。ad打开单条广告:返回广告主、付费方、落地页,以及资料库公开时的投放日期、展示次数、触达的国家和定向。
action advertisers 会以 400 VALIDATION_ERROR 拒绝。请在搜索中用 advertiserName 查找竞品。
搜索按返回的每 30 条广告收取 0.5 积分。ad 收取 0.5 积分。
请求
GET /v1/async/task/{id} 或通过 webhook 接收。参见 异步 task。资料库限制读取速度,所以 120 条广告的搜索约需半分钟。
分析竞品广告
三个请求即可完成一次竞品分析:- 把竞品名称放入
advertiserName发送search,列出它的广告。advertiserName匹配名称的一部分,因此请检查每条广告的advertiserName。加上query可把广告缩小到某个主题,用sortByoldest从最早的广告开始。 - 用广告的
libraryId发送ad,得到付费方和落地页;对于在欧盟展示的广告,还有投放日期、展示次数和定向。 - 用
payer发送search,列出某家代理公司或企业付费的广告,无论由哪个主页投放。
参数
action:search(默认)或ad。query:广告文案中的关键词。search需要query、advertiserName或payer。advertiserName:名称,按广告主名称的一部分匹配,例如samsung。payer:付费方的名称,按名称的一部分匹配,例如Starcom。libraryId:广告的数字 ID,例如1638962914。ad必须提供。country:广告展示的国家,用两位国家代码表示,ALL表示所有国家(默认)。startDate、endDate:YYYY-MM-DD,需同时发送,且在最近一年内。保留在这两天之间展示的广告。sortBy:newest(默认)或oldest。limit:1 到 120 条广告。默认 30。cursor:上一次响应的nextCursor,用于读取其后的广告。
search 读取上面除 libraryId 之外的所有字段,ad 只读取 libraryId。Meta 广告资料库的筛选字段(pageId、pageIds、activeStatus、searchType、adType、mediaType、publisherPlatforms 或 contentLanguages)、资料库无法搜索的值,或该操作不读取的字段,会以 400 VALIDATION_ERROR 拒绝,details 会指明字段。
读取更多广告
还有更多广告可读时,响应带有nextCursor。把它作为 cursor 与同一搜索一起发送,即可收到后续广告,同样最多 limit 条。资料库没有更多广告时,nextCursor 为 null。游标只能用于返回它的那次搜索:query、advertiserName、payer、country、日期范围或 sortBy 不同,会以 400 VALIDATION_ERROR 拒绝,而 limit 可以改变。
搜索响应示例
- 响应会原样返回
platform、action、country、query、advertiserName、payer、sortBy以及你传入的日期。returnedCount统计ads中的广告数,资料库还有更多广告时hasMore为true,可用nextCursor继续读取,libraryUrl在广告资料库中打开同一搜索。资料库不给出总数,所以totalCount为null。 - 每条广告是一张卡片:
position、libraryId、libraryUrl、advertiserName、advertiserLogoUrl、creativeType(如SPONSORED_STATUS_UPDATE或SPONSORED_VIDEO)、format、title、body、images、videos(视频封面在previewUrl)和platforms(LINKEDIN)。format为IMAGE、VIDEO、CAROUSEL、DOCUMENT、ARTICLE、MESSAGE、JOB、SPOTLIGHT或FOLLOW_COMPANY。 - 消息广告和 Thought Leader 广告带有
member,即消息的发送者或广告所推广帖子的作者,包含name和url;ad以相同的结构返回。其他广告的member为null。 - 卡片包含文案的前 120 个字符,文案更长时
bodyTruncated为true。ad返回完整文案。 advertiserId、payer、startDate、endDate、activeDays、linkUrl、landingDomain、impressions、targeting、ctaText和utm在卡片上为null,由ad填充资料库中有的值。资料库不说明广告是否仍在投放,所以isActive为null。summary统计本次响应中的广告:ads、advertisers(广告最多的 10 个:advertiserName、ads)、formats和platforms。卡片不含日期,所以它的日期字段(oldestStartDate、newestStartDate、medianActiveDays、launchesByWeek和longestRunning)保持为空或null。- 没有匹配广告的搜索会以空的
ads和广告数为0的summary完成。
资料库保留的范围
- 每条广告的素材、广告主和付费方在所有国家都可获取。
- 投放日期、展示次数范围、各国展示次数占比和定向,仅对在欧盟展示的广告可获取。
- 资料库保留广告约 12 个月,日期筛选只接受最近一年。
打开单条广告
action ad 打开你发送的 libraryId 对应的广告,可从搜索结果或广告资料库地址 /ad-library/detail/<libraryId> 获得。
ad包含带完整文案的搜索卡片的字段,外加advertiserId、advertiserUrl、advertiserType(company或person)、payer(为广告付费的一方)、linkUrl、landingDomain、ctaText、startDate、endDate、activeDays、impressions、targeting和reachedCountries。impressions是资料库公开的范围(min、max)。targeting列出广告主包含或排除的语言和地区(language、location)以及定向参数(parameters:parameter、targeted、excluded)。对于未在欧盟展示的广告,例如 Adobe 的广告1698237666,日期、impressions、targeting和reachedCountries为null。付费方和广告主则每条广告都有。videos列出每个视频的url(码率最高的文件)、files(所有 mp4:url、type、bitrate)和previewUrl。轮播广告增加cards(title、imageUrl),文档广告增加document(标题、页数和各页封面)。advertiser是广告背后的主页:advertiserId、advertiserName、url、type和logoUrl。- 未在欧盟展示的广告,
transparency为null。在欧盟展示的广告则包含impressions、impressionsText(资料库给出的文字,如50k-100k)和reachByCountry,即各国展示次数的占比(country、countryCode、share、shareText),欧盟以外的国家也包含在内。 variants在资料库显示多个版本时列出广告的其他版本,否则为null。- 素材的媒体 URL 多年保持可访问。轮播卡片的 URL 约一周后过期,广告主标志约两周半后过期。请自行保存需要的文件。
- 资料库没有对应广告的
libraryId会以PAGE_UNAVAILABLE失败。
价格
搜索开始时,按limit 所要求的每 30 条广告预留 0.5 积分,按实际返回的每 30 条广告收取 0.5 积分,最少 0.5 积分。默认搜索(30 条广告)收取 0.5 积分,limit 为 120 的搜索预留 2 积分。ad 收取 0.5 积分。只对已完成的请求收费。