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のテキストクエリを取得件数の上限とともに送信し、非同期タスクを追跡して、正規化されたピンをカーソルページネーションで読み取ります。
- 空でないテキストクエリを用意し、results_limit を1〜2,000の範囲で決めます。
- query と results_limit を /v1/pinterest/search に POST し、返された task_id を保存します。
- タスクが成功するか失敗が返るまで /v1/tasks/{task_id} をポーリングします。
- 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 truePinterest 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、個々の指標は任意フィールドとして扱い、値がなくてもリクエストの失敗とみなさないでください。
関連API
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から、各トピックの月間検索数、更新日時、配下に提案される細かいトピックを読み取ります。