pinterest-research

Pinterest のリサーチ

Pinterest の公開プロフィール、ボード、ピンを調べ、「Ideas」カテゴリの分類を閲覧し、キーワード検索を実行します。Crawlora API から正規化された JSON を取得するため、Pinterest のスクレイピングや非公式のクライアントライブラリは使用しません。

このスキルを使う場面

• 「 の Pinterest プロフィール／フォロワー数／ボードは？」
• 「このボード／このユーザー自身のピンを取得して。」
• 「このピンの内容は？」（タイトル、説明、画像、保存数）
• 「Pinterest で に関するピンを検索して。」
• 「Pinterest の Ideas カテゴリには何があり、 では何がトレンド？」
• Pinterest での競合ボードの監査、コンテンツ案のリサーチ、トレンド調査。

セットアップ（初回のみ）

• https://crawlora.net で無料の Crawlora API キーを取得します（月 2,000 クレジット、カード不要）。
• ヘルパーを実行する前に、環境変数に CRAWLORA_API_KEY を設定します。
• ヘルパーは環境変数から CRAWLORA_API_KEY を読み取り、https://api.crawlora.net/api/v1 にリクエストを送信します。キーがない、または無効な場合は → 401。

仕組み

1. 検索 — /pinterest/search?query= を使ってテキストクエリに一致するピンを検索します（各結果にタイトル、説明、画像、ボード、ピンの投稿者が含まれます）。
2. ピンの詳細 — /pinterest/pin/{id} から、ピンの全詳細（タイトル、説明、画像、ボード、ピンの投稿者、コメント数、保存数、作成日時）を取得します。
3. ボードの詳細 — /pinterest/board/{username}/{slug} から、ボードのメタデータ（名前、説明、カバー画像、ピン数／フォロワー数、所有者）と、そのボードのピンの1ページ分を取得します。
4. ユーザープロフィール — /pinterest/user/{username} から、ユーザーの公開プロフィール（表示名、自己紹介、ウェブサイト、アバター、フォロワー数／フォロー数／ピン数／ボード数）を取得します。
5. ユーザーのボード／ピン — /pinterest/user/{username}/boards と /pinterest/user/{username}/pins から、ユーザー自身のボードまたはピンの1ページ分を取得します。
6. Ideas カテゴリ — /pinterest/categories から、トップレベルの「Ideas」分類（例：「Animals」、「Home Decor」、「Food And Drink」）を取得します。各エントリの id を /pinterest/ideas/{id} に渡すと、そのカテゴリのメタデータとフィード内のピンの1ページ分を取得できます。

すべてのエンドポイント、メソッド、パラメーターについては、reference/endpoints.md を参照してください。

API の呼び出し

# Profile + boards + pins:
scripts/crawlora.sh /pinterest/user/marthastewart | jq '.'
scripts/crawlora.sh /pinterest/user/marthastewart/boards | jq '.'
scripts/crawlora.sh /pinterest/user/marthastewart/pins | jq '.'

# Search + pin detail:
scripts/crawlora.sh /pinterest/search query="minimalist home office" | jq '.'
scripts/crawlora.sh /pinterest/pin/123456789 | jq '.'

# Ideas categories + a category feed:
scripts/crawlora.sh /pinterest/categories | jq '.'
scripts/crawlora.sh /pinterest/ideas/home-decor | jq '.'

すべてのリクエストには scripts/crawlora.sh を使用してください。API キーがコマンドライン引数に含まれないようにできます。

エンドポイントのリファレンス

このスキルで使用するすべての Pinterest エンドポイントについては、reference/endpoints.md を参照してください。

使用例

• 競合ボードの監査： 競合のプロフィールと /pinterest/user/{username}/boards を取得し、ボードのトピック、ピン数、フォロワー数を比較して、コンテンツの不足を見つけます。
• コンテンツ案のリサーチ： /pinterest/categories で関連する「Ideas」カテゴリを探し、次に /pinterest/ideas/{id} で新しいピンを計画する前に、そのカテゴリのフィードで現在注目されている内容を確認します。
• ブランド名の言及／キーワードの調査： /pinterest/search でブランド名または商品名を検索し、上位の結果に対して /pinterest/pin/{id} を実行して、保存数とピンの投稿者の詳細を確認します。

注意事項と制限

• クレジット／成功時課金： 2xx の場合のみ課金されます。無料枠は月あたり2,000クレジットです。 https://crawlora.net でキーを取得してください。
• 公開データのみ — 公開プロフィール／ボード／ピンが対象です。ログインや非公開ボードには対応していません。 Pinterest の利用規約を遵守してください。
• セキュリティ： キーは CRAWLORA_API_KEY のみに保存し、ハードコード、クエリパラメーターへの指定、コミットはしないでください。
• ボードの検索には username と slug の両方が必要です — ボード固有の /{username}/{slug}/ URL からスラッグを取得してください。名前によるボード検索のエンドポイントはありません。
• /pinterest/ideas/{id} を使うには、まず /pinterest/categories からカテゴリ ID を取得する必要があります — ID はカテゴリの表示名から推測できません。
• リストエンドポイント（search、board、user/{username}/boards、user/{username}/pins、ideas/{id}）は結果の1ページ分を返します。最初のページ以降も取得するには、レスポンスでカーソル／オフセットを確認してください。