pinterest-api

Pinterest API スキル

OAuth 認証、Pin／Board の管理、分析、API 統合のパターンなど、Pinterest API v5 の開発を包括的に支援します。

このスキルを使用する場面

次のような場合に、このスキルを使用してください。

• Pinterest の OAuth 2.0 認証フローを実装する
• API を使用して Pin や Board を作成、更新、管理する
• Pinterest の分析データや指標をアプリケーションに統合する
• Pinterest API クライアントや SDK を構築する
• Pinterest ユーザーアカウントのデータを扱う
• Pinterest API のリクエストやレスポンスをデバッグする
• Web／モバイルアプリに Pinterest の共有機能を実装する
• Pinterest ビジネスアカウントとの連携を設定する
• Pinterest 広告アカウント API を扱う

主な概念

Pinterest API v5 の概要

• ベース URL：https://api.pinterest.com/v5/
• 認証：アクセストークンを使用する OAuth 2.0
• レート制限：トークンベースのレート制限（エンドポイントによって異なります）
• レスポンス形式：JSON
• 必須ヘッダー：Authorization: Bearer {access_token}

主なリソース

• Pin：Pinterest に保存される個々のコンテンツ（画像、動画）
• Board：テーマやトピックごとに Pin を整理するコレクション
• セクション：Board 内のコンテンツをさらに整理するためのサブセクション
• ユーザーアカウント：Pinterest のユーザープロフィールとアカウント情報
• 広告アカウント：広告機能を利用するためのビジネスアカウント

アクセスレベル

• パブリックアクセス：公開データへの読み取り専用アクセス
• ユーザー認証：ユーザーの Pin、Board、アカウントへのフルアクセス
• ビジネスアクセス：分析や広告アカウント管理などの追加機能（適切なロールが必要です）

クイックリファレンス

OAuth 2.0 認証フロー

ステップ 1：認証 URL を生成する

// Redirect user to Pinterest authorization page
const authUrl = `https://www.pinterest.com/oauth/?client_id={CLIENT_ID}&redirect_uri={REDIRECT_URI}&response_type=code&scope=boards:read,pins:read,user_accounts:read`;

window.location.href = authUrl;

ステップ 2：コードをアクセストークンと交換する

# After user authorizes, exchange authorization code for access token
curl -X POST https://api.pinterest.com/v5/oauth/token \
  --header "Authorization: Basic {BASE64_ENCODED_CLIENT_CREDENTIALS}" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=authorization_code" \
  --data-urlencode "code={AUTHORIZATION_CODE}" \
  --data-urlencode "redirect_uri={REDIRECT_URI}"

クライアント認証情報の Base64 エンコード：

# Encode client_id:client_secret
echo -n "your_client_id:your_client_secret" | base64

レスポンス：

{
  "access_token": "pina_ABC123...",
  "token_type": "bearer",
  "expires_in": 2592000,
  "refresh_token": "DEF456...",
  "scope": "boards:read,pins:read,user_accounts:read"
}

Pin の管理

Pin を作成する

curl -X POST https://api.pinterest.com/v5/pins \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "link": "https://example.com/my-article",
    "title": "My Amazing Pin Title",
    "description": "Detailed description of the pin content",
    "board_id": "123456789",
    "media_source": {
      "source_type": "image_url",
      "url": "https://example.com/image.jpg"
    }
  }'

Pin の詳細を取得する

curl -X GET https://api.pinterest.com/v5/pins/{PIN_ID} \
  -H "Authorization: Bearer {ACCESS_TOKEN}"

レスポンス：

{
  "id": "987654321",
  "created_at": "2025-01-15T10:30:00",
  "link": "https://example.com/my-article",
  "title": "My Amazing Pin Title",
  "description": "Detailed description of the pin content",
  "board_id": "123456789",
  "media": {
    "media_type": "image",
    "images": {
      "150x150": { "url": "...", "width": 150, "height": 150 },
      "400x300": { "url": "...", "width": 400, "height": 300 },
      "originals": { "url": "...", "width": 1200, "height": 800 }
    }
  }
}

Pin を更新する

curl -X PATCH https://api.pinterest.com/v5/pins/{PIN_ID} \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated Pin Title",
    "description": "Updated description",
    "link": "https://example.com/updated-link"
  }'

Pin を削除する

curl -X DELETE https://api.pinterest.com/v5/pins/{PIN_ID} \
  -H "Authorization: Bearer {ACCESS_TOKEN}"

Board の管理

Board を作成する

curl -X POST https://api.pinterest.com/v5/boards \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My New Board",
    "description": "A collection of my favorite ideas",
    "privacy": "PUBLIC"
  }'

プライバシー設定： PUBLIC、PROTECTED、SECRET

ユーザーの Board 一覧を取得する

curl -X GET https://api.pinterest.com/v5/boards \
  -H "Authorization: Bearer {ACCESS_TOKEN}"

Board の Pin を取得する

curl -X GET https://api.pinterest.com/v5/boards/{BOARD_ID}/pins \
  -H "Authorization: Bearer {ACCESS_TOKEN}"

ユーザーアカウント

現在のユーザーアカウントを取得する

curl -X GET https://api.pinterest.com/v5/user_account \
  -H "Authorization: Bearer {ACCESS_TOKEN}"

レスポンス：

{
  "account_type": "BUSINESS",
  "id": "123456789",
  "username": "myusername",
  "website_url": "https://example.com",
  "profile_image": "https://i.pinimg.com/...",
  "follower_count": 1500,
  "following_count": 320,
  "board_count": 25,
  "pin_count": 450
}

分析

Pin の分析データを取得する

curl -X GET "https://api.pinterest.com/v5/pins/{PIN_ID}/analytics?start_date=2025-01-01&end_date=2025-01-31&metric_types=IMPRESSION,SAVE,PIN_CLICK" \
  -H "Authorization: Bearer {ACCESS_TOKEN}"

利用可能な指標：

• IMPRESSION - Pin が表示された回数
• SAVE - Pin が保存された回数
• PIN_CLICK - Pin のリンク先がクリックされた回数
• OUTBOUND_CLICK - 外部サイトへのクリック数
• VIDEO_START - 動画の再生が開始された回数

レスポンス：

{
  "all": {
    "daily_metrics": [
      {
        "date": "2025-01-01",
        "data_status": "READY",
        "metrics": {
          "IMPRESSION": 1250,
          "SAVE": 45,
          "PIN_CLICK": 89
        }
      }
    ]
  }
}

エラー処理

一般的なエラーレスポンス

{
  "code": 3,
  "message": "Requested pin not found"
}

一般的なエラーコード：

• 1 - リクエストパラメーターが無効です
• 2 - レート制限を超過しました
• 3 - リソースが見つかりません
• 4 - 権限が不足しています
• 8 - アクセストークンが無効です

Python のエラー処理例

import requests

def create_pin(access_token, board_id, title, image_url):
    url = "https://api.pinterest.com/v5/pins"
    headers = {
        "Authorization": f"Bearer {access_token}",
        "Content-Type": "application/json"
    }
    data = {
        "board_id": board_id,
        "title": title,
        "media_source": {
            "source_type": "image_url",
            "url": image_url
        }
    }

    try:
        response = requests.post(url, headers=headers, json=data)
        response.raise_for_status()
        return response.json()
    except requests.exceptions.HTTPError as e:
        error_data = e.response.json()
        print(f"Error {error_data.get('code')}: {error_data.get('message')}")
        return None
    except requests.exceptions.RequestException as e:
        print(f"Request failed: {str(e)}")
        return None

JavaScript／Node.js の統合

// Pinterest API Client Example
class PinterestClient {
  constructor(accessToken) {
    this.accessToken = accessToken;
    this.baseUrl = 'https://api.pinterest.com/v5';
  }

  async request(endpoint, options = {}) {
    const url = `${this.baseUrl}${endpoint}`;
    const headers = {
      'Authorization': `Bearer ${this.accessToken}`,
      'Content-Type': 'application/json',
      ...options.headers
    };

    const response = await fetch(url, {
      ...options,
      headers
    });

    if (!response.ok) {
      const error = await response.json();
      throw new Error(`Pinterest API Error: ${error.message}`);
    }

    return response.json();
  }

  async createPin(boardId, title, imageUrl, description = '', link = '') {
    return this.request('/pins', {
      method: 'POST',
      body: JSON.stringify({
        board_id: boardId,
        title: title,
        description: description,
        link: link,
        media_source: {
          source_type: 'image_url',
          url: imageUrl
        }
      })
    });
  }

  async getUserBoards() {
    return this.request('/boards');
  }

  async getPinAnalytics(pinId, startDate, endDate) {
    const params = new URLSearchParams({
      start_date: startDate,
      end_date: endDate,
      metric_types: 'IMPRESSION,SAVE,PIN_CLICK'
    });
    return this.request(`/pins/${pinId}/analytics?${params}`);
  }
}

// Usage
const client = new PinterestClient('your_access_token');
const pin = await client.createPin('board_id', 'Pin Title', 'https://example.com/image.jpg');

リファレンスファイル

このスキルには、references/ に包括的なドキュメントが含まれています。

• api.md - 公式ドキュメントから抽出した Pinterest API v5 エンドポイントの完全なリファレンス

特定のエンドポイントについて詳しい情報が必要な場合は、view を使用してリファレンスファイルを読み込んでください。

このスキルの使い方

初心者向け

1. まず、OAuth 2.0 認証フローを理解します（上記のクイックリファレンスを参照してください）
2. Pinterest Developer Portal で API 認証情報を取得します
3. アプリケーションに実装する前に、curl コマンドで認証をテストします
4. 提供されている Python／JavaScript の例を出発点のテンプレートとして使用します

API 統合向け

1. アクセストークンを取得するための OAuth フローを実装します
2. 長期的なアクセスのために、リフレッシュトークンを安全に保存します
3. CRUD 操作には、Pin／Board 管理の例を使用します
4. レート制限や API エラーに適切に対処できるエラー処理を実装します

分析とビジネス機能

1. 適切なビジネスアカウントへのアクセス権があることを確認します
2. 分析エンドポイントを使用して、Pin のパフォーマンスを追跡します
3. レポート用に、日付範囲を指定して指標を集計します
4. 不要な API 呼び出しを避けるため、キャッシュを実装します

ベストプラクティス

• トークンのセキュリティ：クライアント側のコードやバージョン管理でアクセストークンを決して公開しないでください
• レート制限：レート制限エラーに対して、指数バックオフを実装してください
• ページネーション：大きな結果セットには、カーソルベースのページネーションを使用してください
• Webhook：ポーリングの代わりに、リアルタイム更新のための Webhook の使用を検討してください
• スコープ：アプリケーションに必要な最小限の OAuth スコープのみをリクエストしてください

よくあるパターン

ページネーション

# Initial request
curl -X GET "https://api.pinterest.com/v5/boards/{BOARD_ID}/pins?page_size=25" \
  -H "Authorization: Bearer {ACCESS_TOKEN}"

# Follow-up with bookmark from response
curl -X GET "https://api.pinterest.com/v5/boards/{BOARD_ID}/pins?page_size=25&bookmark={BOOKMARK}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}"

一括操作

# Create multiple pins efficiently
def bulk_create_pins(access_token, board_id, pin_data_list):
    results = []
    for pin_data in pin_data_list:
        result = create_pin(
            access_token,
            board_id,
            pin_data['title'],
            pin_data['image_url']
        )
        results.append(result)
        time.sleep(0.5)  # Respect rate limits
    return results

リソース

公式ドキュメント

• Pinterest API v5 ドキュメント：https://developers.pinterest.com/docs/api/v5/
• API クイックスタート：https://github.com/pinterest/api-quickstart
• OAuth ドキュメント：https://developers.pinterest.com/docs/getting-started/authentication/

OAuth スコープ

必要になる一般的なスコープ：

• boards:read - ボードデータの読み取り
• boards:write - ボードの作成／更新
• pins:read - Pin データの読み取り
• pins:write - Pin の作成／更新
• user_accounts:read - ユーザーアカウントデータの読み取り
• ads:read - 広告アカウントの分析データの読み取り（ビジネスアカウント）

レート制限

• Pinterest はユーザーごとのレート制限を適用します
• 一般的な制限：ユーザーあたり毎時 1000 リクエスト
• レスポンス内のレート制限ヘッダー：
  • X-RateLimit-Limit
  • X-RateLimit-Remaining
  • X-RateLimit-Reset

注記

• Pinterest API v5 は現行バージョンです（2025 年時点）
• すべてのエンドポイントで OAuth 2.0 による認証が必要です
• アクセストークンは 30 日後に期限切れになります
• リフレッシュトークンを使用して、新しいアクセストークンを取得してください
• ビジネスアカウントでは、追加の分析機能を利用できます
• 動画 Pin は画像 Pin とは異なる特別な処理が必要です
• 一部の機能を利用するには、Pinterest によるアプリの審査が必要です

トラブルシューティング

「無効なアクセストークン」

• トークンの有効期限が切れていないことを確認します（有効期間は 30 日間）
• リフレッシュトークンを使用して、新しいアクセストークンを取得します
• Authorization ヘッダーの形式を確認します：Bearer {token}

「権限が不足しています」

• OAuth スコープに必要な権限が含まれていることを確認します
• ビジネス機能には、確認済みのビジネスアカウントが必要です
• 一部の操作には、ボードまたは Pin の所有権が必要です

「レート制限を超過しました」

• 指数バックオフを実装します
• 可能な場合はレスポンスをキャッシュします
• ポーリングの代わりに Webhook を使用します
• 再試行時刻を確認するには、X-RateLimit-Reset ヘッダーを確認します

「メディアのアップロードに失敗しました」

• 画像 URL にパブリックアクセスできることを確認します
• 画像がサイズ要件（最大 10MB）を満たしていることを確認します
• 画像形式がサポートされていることを確認します（JPG、PNG、GIF）
• 動画の場合は、動画専用のエンドポイントを使用します

更新

このスキルは Pinterest の公式 API ドキュメントをもとに生成されました。最新の API 変更を確認するには：

1. https://developers.pinterest.com/docs/api/v5/ にアクセスします
2. API の更新について変更履歴を確認します
3. 非推奨に関する通知を確認します
4. 新機能が追加された場合は OAuth スコープを更新します