Pinterest Board Pins
Pinterestボード上のピンは、誰かが1つのアイデアを軸に集めた画像で、それぞれに短いタイトルや説明、保存したアカウント、元の幅と高さのままのオリジナル画像が付いています。ボードが表示する順にまとめて扱えば、ムードボード、デザインリサーチ、画像データセット、キュレーションされたコレクションの変化の把握にそのまま使えるビジュアル資料になります。
Pinterest Board Pins API の主な機能
- ボードの並び順を保ったピン行はボード自体が表示する順序に従うため、キュレーターが並べたとおりにコレクションを読めます。
- オリジナル画像とサムネイルmedia.url はフルサイズの画像、media.thumbnail_url は小さなプレビューを指し、すべてのファイルに幅と高さ(ピクセル)が付きます。
- 保存したアカウントとピンの内容author は各ピンを保存したアカウントをユーザー名、表示名、プロフィールリンク、アバターとともに示し、text にはピンのタイトルや説明が入ります。
- すべてのピンへの戻りリンクurl はピンの id から組み立てたピン自身のページで、セット内のどの画像もPinterest上の掲載場所までたどれます。
- 各ボードから最大1,000ピンresults_limit はボードごとに数えられ、デフォルトは50、最大1,000まで指定でき、urls には複数のボードをまとめて送れます。
Pinterest Board Pins API のパラメータ
| パラメータ | 必須 | 説明 |
|---|---|---|
urls | 必須 | /{username}/{board}/ 形式のPinterestボードのリンクです(例:https://www.pinterest.com/lizmrodgers/moms-night/)。 |
results_limit | 任意 | ボードごとに返すピンの最大数で、1〜1000の整数です。デフォルトは50です。 |
Pinterest Board Pins API の使い方
ボードのリンクを送信し、タスクの完了を待ってから、ピンをページごとに読み取ります。
- ボードのリンクを urls に入れ、1ボードあたり50件を超えるピンが必要なら results_limit も付けて /v1/pinterest/board に POST します。
- 受け取った task_id で、タスクが成功するまで GET /v1/tasks/{task_id} をポーリングします。
- results.items からピンを取り出し、has_more が true の間は results.next_cursor で取得を続けます。
curl -X POST "https://api.socq.ai/v1/pinterest/board" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"urls":["https://www.pinterest.com/lizmrodgers/moms-night/"],"results_limit":50}'
# 0.5 credits per pin; boards that do not exist return no pins.Pinterest Board Pins API の主なユースケース
- ボードの画像のダウンロード: ボードのすべての media.url を保存してオリジナルファイルの参考ライブラリを手元に作り、width と height で縦長と横長の画像を分けます。
- キャプション付き画像データセットの構築: 各画像をピンの text と取得元のボードと組み合わせ、デザインリサーチやモデル学習用のラベル付きサンプルを用意します。
- 競合の季節ボードの監視: 同じボードを毎週取得して前回のピンの id と比べ、何が追加されたかを正確に把握します。
- ムードボードでの出典表記: 各画像の横に author.username とピンの url を残しておき、プレゼン資料のどの画像も出典を示して元のページを開けるようにします。
Pinterest Board Pins API 活用のヒント
- ボード自身の2階層のリンクを使ってください。/{username}/_saved/ や /{username}/pins/ などのプロフィールタブ、さらに深いセクションのパス、pin.it の短縮リンクは受け付けられないため、ボードを開いてアドレスをコピーします。
- 先に Pinterest User Boards API でボードの metrics.pins_count を確認し、それに合わせて results_limit を設定すれば、大きなボードがデフォルトの50件で途切れません。
- グリッドやプレビューには thumbnail_url を読み込み、残す画像だけ media.url を取得すれば、数百のピンがあるボードでも通信量を抑えられます。
関連API
Pinterest Board Pins API 以外に別の種類の公開Pinterestデータが必要な場合は、これらのAPIをご利用ください。
- Pinterest Pins API — 公開ピンのURLから、正規化されたコンテンツ、クリエイター、メディア、分類、タイムスタンプ、表示中の指標を取得します。
- Pinterest User Pins API — プロフィールURLから公開ピンを探します。プロフィールごとの取得上限を指定でき、正規化されたコンテンツ、クリエイター、メディア、タイムスタンプ、表示中の指標を返します。
- Pinterest Profiles API — プロフィールURLから、公開プロフィールのアカウント情報、プロフィール文、画像、Webサイト、表示中のアカウントのカウント、取得情報を取得します。
- Pinterest Search API — テキストクエリで公開ピンを検索します。取得件数の上限を指定でき、正規化されたコンテンツ、クリエイター、メディア、分類、タイムスタンプ、表示中の指標を返します。
- Pinterest User Boards API — プロフィールURLからPinterestのボードを一覧にし、名前、説明、カバー画像、作成日と、ピン・フォロワー・セクション・コラボレーターの数を返します。
- Pinterest Topic API — アイデアページのURLから、各トピックの月間検索数、更新日時、配下に提案される細かいトピックを読み取ります。