pinterest/
search

テキストクエリと取得件数の上限を指定して公開Pinterestピンを検索し、正規化されたコンテンツ、投稿者情報、メディア、分類、表示中のエンゲージメントを返します。

Pinterest Search API

テキストクエリで指定
取得件数1〜2,000件
正規化された公開ピン
結果1件あたり0.6クレジット
準備完了
準備完了

パラメータを入力してリクエストを送信してください。タスクのステータスと正規化された結果がここに表示されます。

README

SocQ 編集 · 更新

Pinterest Search

Pinterest検索の結果は、テキストクエリに一致した公開ピンで、タイトル、説明文、投稿者情報、メディアの参照、カテゴリ、ハッシュタグ、タイムスタンプ、表示中のエンゲージメントを含みます。これらのレコードは、トピックの発見、ビジュアルテーマのリサーチ、投稿者の傾向分析、クエリ単位でのコンテンツ比較に活用できます。

Pinterest Search API の主な機能

  • クエリによるピンの検索空でないテキストクエリ1つと、1〜2,000の results_limit を受け付け、件数の上限を設けて公開ピンのレコードを取得します。
  • ピン・投稿者・メディアの正規化レコードピンID、URL、タイトル、本文、公開されている投稿者フィールド、画像または動画の参照を、一貫した形式の結果として返します。
  • 分類と表示中の指標取得可能なカテゴリ、ハッシュタグ、ピンの種類、ソースのメタデータ、表示中のいいね数・コメント数・投稿者のフォロワー数、公開日時、取得時刻、送信したクエリの情報を保持します。

Pinterest Search API のパラメータ

パラメータ必須説明
query必須必須。公開Pinterestピンの検索に使う空でないテキストクエリです。前後の空白は送信前に除去されます。
results_limit任意クエリに対して取得するピンの最大件数です。デフォルトは100で、1〜2,000の整数を指定できます。

Pinterest Search API の使い方

Pinterestのテキストクエリを取得件数の上限とともに送信し、非同期タスクを追跡して、正規化されたピンをカーソルページネーションで読み取ります。

  1. 空でないテキストクエリを用意し、results_limit を1〜2,000の範囲で決めます。
  2. query と results_limit を /v1/pinterest/search に POST し、返された task_id を保存します。
  3. タスクが成功するか失敗が返るまで /v1/tasks/{task_id} をポーリングします。
  4. data.results.items を読み取り、has_more が true の間は返された next_cursor で続きを取得します。
curl -X POST "https://api.socq.ai/v1/pinterest/search" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"home office ideas","results_limit":100}'

# Poll GET /v1/tasks/{task_id}
# Read data.results.items and follow next_cursor while has_more is true

Pinterest Search API の主なユースケース

  • トピック別のピンデータセット: 定めたクエリに対するピンID、元URL、タイトル、本文、メディアの参照、discovery_input を使い、追跡可能なトピック別コレクションを構築します。
  • ビジュアルと分類のリサーチ: 画像や動画、post_type、categories、hashtags、タイトル、説明文を比較し、検索結果に含まれる形式やテーマを分析します。
  • 投稿者と表示中の指標の比較: 公開されている投稿者フィールドといいね数・コメント数・フォロワー数を collected_at と組み合わせ、クエリごとのコレクション間で観測された結果を比較します。

Pinterest Search API 活用のヒント

  • 入力の検証を通過するよう、意図せず付いた前後の空白を取り除いた空でない query を送信し、results_limit は1〜2,000の範囲に収めてください。
  • 保存された結果が最初のレスポンスページの50件を超える場合は、has_more が false になるまで next_cursor をたどってください。
  • extra.discovery_input と collected_at を保持し、各ピンを送信したキーワードと観測時刻に紐付けたままにしてください。
  • title、text、投稿者情報、media、created_at、categories、hashtags、source、個々の指標は任意フィールドとして扱い、値がなくてもリクエストの失敗とみなさないでください。

Pinterest Search API 以外に別の種類の公開Pinterestデータが必要な場合は、これらのAPIをご利用ください。

  • Pinterest Pins API — 公開ピンのURLから、正規化されたコンテンツ、クリエイター、メディア、分類、タイムスタンプ、表示中の指標を取得します。
  • Pinterest User Pins API — プロフィールURLから公開ピンを探します。プロフィールごとの取得上限を指定でき、正規化されたコンテンツ、クリエイター、メディア、タイムスタンプ、表示中の指標を返します。
  • Pinterest Profiles API — プロフィールURLから、公開プロフィールのアカウント情報、プロフィール文、画像、Webサイト、表示中のアカウントのカウント、取得情報を取得します。
  • Pinterest User Boards API — プロフィールURLからPinterestのボードを一覧にし、名前、説明、カバー画像、作成日と、ピン・フォロワー・セクション・コラボレーターの数を返します。
  • Pinterest Board Pins API — ボードのURLから、Pinterestボードのピンを並び順どおりに、ピンのテキスト、保存したアカウント、フルサイズ画像、ピンのリンクとともに取得します。
  • Pinterest Topic API — アイデアページのURLから、各トピックの月間検索数、更新日時、配下に提案される細かいトピックを読み取ります。

他のプラットフォームを見る

Pinterestのデータを、対応する他のソーシャルプラットフォームの公開データと組み合わせられます。

Pinterest Search API — よくある質問

Pinterest Search APIは、空でないテキストクエリと任意の取得件数の上限から公開ピンのレコードを検索します。正規化されたピンの識別情報、コンテンツ、投稿者、メディア、分類、タイムスタンプ、表示中のエンゲージメントを返します。

このエンドポイントで使えるのは query と results_limit のみです。並び順、日付、言語、ボード、結果の種類によるフィルターパラメータはありません。

正規化された結果はすべて公開ピンで、resource は search、type は pin に設定されます。このレスポンスでは、プロフィール、ボード、商品、サジェストは個別の結果タイプとして返されません。

レコードには、ピンID、URL、タイトル、本文、公開されている投稿者情報、画像または動画の参照、表示中のいいね数・コメント数・フォロワー数、created_at、collected_at、extra 内の分類・ソース・検出情報のフィールドが含まれる場合があります。ソースの任意の値は null または空になることがあります。

results_limit はクエリに対する取得上限で、デフォルトは100、1〜2,000の整数を指定できます。タスクが成功すると、保存された結果はデフォルトで50件ずつのページで返されます。has_more が true の間は next_cursor をたどってください。タスクエンドポイントを直接呼び出す場合は、ページの limit に1〜500を指定できます。

返されたピンレコード1件につき0.6 SocQクレジットです。リクエスト前の見積もりには results_limit(省略時は100)が使われ、結果が空の場合は結果に対する課金は発生しません。