跳转到主要内容
通过异步 task API 读取 LinkedIn 广告资料库,以 JSON 获取竞品向职场人群投放了哪些广告。ADS 是独立的引擎。向 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 积分。

请求

提交 task 后,轮询 GET /v1/async/task/{id} 或通过 webhook 接收。参见 异步 task。资料库限制读取速度,所以 120 条广告的搜索约需半分钟。

分析竞品广告

三个请求即可完成一次竞品分析:
  1. 把竞品名称放入 advertiserName 发送 search,列出它的广告。advertiserName 匹配名称的一部分,因此请检查每条广告的 advertiserName。加上 query 可把广告缩小到某个主题,用 sortBy oldest 从最早的广告开始。
  2. 用广告的 libraryId 发送 ad,得到付费方和落地页;对于在欧盟展示的广告,还有投放日期、展示次数和定向。
  3. 用 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 积分。只对已完成的请求收费。

相关