LinkedIn Ad Library Search API

LinkedIn Ad Library Search

主要特性

• 三种发现输入可使用公司名称、关键词、精确 LinkedIn 公司 ID，或在一个请求中组合这些字段；至少要提供其中一个。
• 国家与日期筛选通过两位国家代码和可选的 YYYY-MM-DD 投放日期区间缩小公开索引范围。
• 标准化公开广告记录在来源披露时返回稳定的广告身份、广告主、创意、详情 URL、日期、市场、格式、目标链接、展示次数和媒体字段。
• 有界令牌分页以 24 的倍数请求 24 到 1,992 条记录，SocQ 会继续使用新的上游分页令牌，直到达到上限或没有下一可用页。
• 从搜索进入详情当某条搜索结果需要可用的详情记录时，可把返回的 /ad-library/detail/ URL 交给 LinkedIn Ad Library Ad。

参数

如何使用

至少选择一个发现字段，只添加用于定义样本的筛选条件，然后读取异步任务的完整结果页。

1. 提供 company、keyword 或 company_id；只有确实需要更窄的来源匹配时才组合多个字段。
2. 可选添加两位 countries、有效日期区间，以及 24 的倍数 results_limit。
3. 向 /v1/linkedin-ad-library/search POST 请求并保存返回的 task_id。
4. 轮询 /v1/tasks/{task_id}，读取 data.results.items，并在 has_more 为 true 时继续使用 next_cursor。

curl -X POST "https://api.socq.ai/v1/linkedin-ad-library/search" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"company":"Microsoft","countries":["US"],"results_limit":24}'

# 轮询 GET /v1/tasks/{task_id}
# 读取 data.results.items，并在 has_more 为 true 时继续使用 next_cursor

最佳使用场景

• 发现广告主公开广告： 使用公司名称或精确公司 ID，整理采集时可观察到的该广告主公开广告。
• 文案与主题研究： 搜索产品、竞品或主题关键词，对比返回的创意文本、格式、媒体和目标链接。
• 市场与时间窗口比较： 使用一致查询和受控国家、日期筛选重复采集，对比定义明确的公开披露样本。
• 选择详情候选： 根据返回的广告 ID 和详情 URL，挑选需要交给独立详情接口进一步查看的记录。

使用建议

• 先从一个发现字段开始；只有需要更窄的来源匹配结果时，才组合 company、keyword 和 company_id。
• 虽然当前校验器接受大小写字母，但建议使用大写国家代码，以保持保存输入一致。
• 以每 24 条为一个增量设置 results_limit，并把它视为采集上限，而不是结果数量承诺。
• 比较多次采集时保留查询、筛选条件和 collected_at，因为公开可用性和保留记录会变化。
• 广告主、日期、国家、展示次数、目标链接、格式或媒体为空时，应视为披露数据不可用，而不是零。

相关 API