LinkedIn Ad Library Search
LinkedIn Ad Library Searchは、会社名、正確な会社ID、キーワード、またはそれらの組み合わせから、保持されている公開広告の開示情報を探します。返されるレコードでは、取得可能な広告主情報、クリエイティブのテキスト、ソースURL、配信期間、国、インプレッション、形式、リンク先、メディアが正規化され、開示されていないフィールドを0として扱うことはありません。
LinkedIn Ad Library Search API の主な機能
- 3種類の検索入力会社名、キーワード、正確なLinkedIn会社ID、またはその複数を1回のリクエストで指定して検索します。少なくとも1つは必須です。
- 国と期間のフィルター2文字の国コードと、任意の YYYY-MM-DD 形式の配信日の範囲(両端を含む)で公開インデックスを絞り込みます。
- 正規化された公開広告レコード開示されている場合、安定した広告ID、広告主の参照、クリエイティブのテキスト、詳細ページURL、日付、市場、形式、リンク先、インプレッション、メディアを返します。
- 上限付きのトークンページネーション24の倍数で24〜1,992件のレコードを取得します。SocQは上限または最後の利用可能なページに達するまで、上流の新しいページネーショントークンをたどります。
- 検索から詳細取得へのワークフロー発見したレコードについて詳細を確認したい場合は、返された /ad-library/detail/ のURLをLinkedIn Ad Library Adに渡します。
LinkedIn Ad Library Search API のパラメータ
| パラメータ | 必須 | 説明 |
|---|---|---|
company | 必須(いずれか1つ以上) | 会社名または広告主名です。company、keyword、company_id のうち少なくとも1つが必須です。 |
keyword | 必須(いずれか1つ以上) | 公開広告検索で一致させるテキストです。一致の仕組みは公開ソースに従います。 |
company_id | 必須(いずれか1つ以上) | 検索の入力として使用する、正確なLinkedIn会社IDです。 |
countries | 任意 | 任意。2文字のアルファベットの国コードのリストです。US や CA のように大文字での指定を推奨します。 |
start_date | 任意 | 任意。YYYY-MM-DD 形式の、公開配信日フィルターの開始日です。 |
end_date | 任意 | 任意。YYYY-MM-DD 形式の、公開配信日フィルターの終了日です。start_date より前の日付は指定できません。 |
results_limit | 任意 | リクエストするレコードの最大件数です。デフォルトは24で、24〜1,992の範囲の24の倍数を指定できます。 |
LinkedIn Ad Library Search API の使い方
検索フィールドを少なくとも1つ選び、サンプルを定めるのに必要なフィルターだけを追加して、完了した非同期タスクのページを読み取ります。
- company、keyword、company_id のいずれかを指定します。ソースが定める、より絞り込んだ一致を意図する場合にのみ組み合わせてください。
- 必要に応じて、2文字の countries、有効な期間、24の倍数の results_limit を追加します。
- リクエストを /v1/linkedin-ad-library/search に POST し、返された task_id を保存します。
- /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}'
# Poll GET /v1/tasks/{task_id}
# Read data.results.items and follow next_cursor while has_more is trueLinkedIn Ad Library Search API の主なユースケース
- 広告主の広告の発見: 会社名または正確な会社IDを使って、取得時点で確認できる広告主に関連した公開広告をまとめます。
- メッセージとテーマの調査: 製品、競合、テーマに関するキーワードで検索し、返されたクリエイティブのテキスト、形式、メディア、リンク先を比較します。
- 市場別・期間別の比較: 国と期間のフィルターを統一したうえで同じクエリを繰り返し実行し、定めたサンプル間で公開されている開示情報を比較します。
- 詳細確認の候補選定: 返された広告IDと詳細ページURLを使って、別の詳細取得の操作で詳しく確認する個々のレコードを選びます。
LinkedIn Ad Library Search API 活用のヒント
- まずは検索フィールドを1つだけ使い、ソースが定める、より絞り込んだ結果セットが役立つ場合にのみ company、keyword、company_id を組み合わせてください。
- 現在の検証では大文字・小文字のどちらも受け付けますが、保存する入力の一貫性を保つため、国コードは大文字で指定してください。
- results_limit は24件単位で選び、すべての枠が一致する広告で埋まることを保証するものではなく、取得件数の上限として扱ってください。
- 公開状況や保持されるレコードは変化するため、実行結果を比較する際はクエリ、フィルター、collected_at の日時を保持してください。
- 広告主、日付、国、インプレッション、リンク先、形式、メディアの値がない場合は、0ではなく開示されていないデータとして扱ってください。
関連API
LinkedIn Ad Library Search API 以外に別の種類の公開LinkedIn Ad Libraryデータが必要な場合は、これらのAPIをご利用ください。
- LinkedIn Ad Library Ad API — 完全一致する詳細URLから、既知の公開LinkedIn広告ライブラリのレコード1件を取得し、正規化された広告主、クリエイティブ、配信、遷移先、インプレッション、メディアの各フィールドを返します。