📌 Pinterest Details Scraper

A production-ready Apify Actor for scraping structured Pinterest data using search queries and direct Pinterest URLs (pins, profiles, boards, ideas, and search pages).

Works in two modes:

• Direct scrape mode — scrapes Pinterest directly (requires proxy for high volume)
• API mode — routes requests through your own backend API (API_URL + PINTEREST_API_KEY)

---

✨ Features

• 🔍 Keyword Search — collect Pinterest pins using plain text search queries
• 📌 Pin Details — title, description, images (orig/564x/236x), engagement metrics, board info, comments
• 📋 Board Scraping — all pins from any public board with full pagination
• 👤 User Profile — follower/following counts, board count, monthly views, verified status
• 💡 Ideas URL Support — auto-converts /ideas/<topic>/... to keyword search
• 🔗 Search URL Support — scrapes /search/pins/?q=... URLs directly
• 🔄 Automatic URL Classification — detects pin, profile, board, ideas, or search URL automatically
• 📜 Optional Comments — fetch comments for individual pin URLs
• 📄 Pagination Control — max_items and end_page for fine-tuned result limits
• 🔁 Retry Logic — automatic retries and safe error handling
• 🧹 Structured JSON Output — clean, normalized data ready for analytics or storage

---

🚀 How to Use

Step 1 — Choose Your Input

Use search queries, start URLs, or both.

Search by Keywords

{
  "queries": ["home decor", "fashion ideas", "logo design"]
}

Scrape by Direct URLs

{
  "start_urls": [
    "https://www.pinterest.com/pin/123456789/",
    "https://www.pinterest.com/username/",
    "https://www.pinterest.com/username/boardname/",
    "https://www.pinterest.com/ideas/beauty/935541271955/",
    "https://www.pinterest.com/search/pins/?q=Valentine%E2%80%99s%20Nail%20Art"
  ]
}

Step 2 — Configure Optional Settings

{
  "max_items": 50,
  "end_page": 3,
  "include_comments": true,
  "only_user_info": false
}

Step 3 — Run the Actor

• Save your input configuration
• Click Run in the Apify Console
• Monitor logs for real-time progress
• Access results in the Apify Dataset

---

📥 Input Parameters

Parameter	Type	Default	Description
queries	string[]	—	Pinterest keyword searches
start_urls	string[]	—	Direct Pinterest URLs to scrape
include_comments	boolean	false	Include comments for pin detail URLs
only_user_info	boolean	false	Return only profile/board metadata (no pins)
max_items	integer	20	Max items per URL or query
end_page	integer	1	Pagination depth (increase for more results)

---

📤 Output Examples

Search Result

{
  "type": "search_query",
  "query": "dress",
  "count": 20,
  "items": [
    {
      "pin_id": "846324954995310675",
      "url": "https://www.pinterest.com/pin/846324954995310675",
      "title": "Red Sequins V-neck Long 1920s Dress",
      "description": "Fabric: Sequins...",
      "link": "https://zapaka.com/products/red-sequins-dress",
      "dominant_color": "#732e2b",
      "image_original": "https://i.pinimg.com/originals/48/a0/f5/48a0f5.jpg",
      "image_564": "https://i.pinimg.com/564x/48/a0/f5/48a0f5.jpg",
      "image_236": "https://i.pinimg.com/236x/48/a0/f5/48a0f5.jpg",
      "creator_username": "zapakaretro",
      "creator_fullname": "Zapaka Retro",
      "creator_profile_url": "https://www.pinterest.com/zapakaretro/",
      "repin_count": 1423,
      "like_count": 0,
      "comment_count": 2,
      "is_promoted": false
    }
  ]
}

Pin Detail

{
  "type": "pin_detail",
  "source_url": "https://www.pinterest.com/pin/4222193395681386/",
  "count": 1,
  "items": [
    {
      "type": "pin",
      "url": "https://www.pinterest.com/pin/4222193395681386/",
      "id": "4222193395681386",
      "description": "Beautiful minimalist design",
      "grid_title": "Modern Home",
      "dominant_color": "#65625e",
      "created_at": "Sun, 23 Nov 2025 23:29:44 +0000",
      "repin_count": 179,
      "like_count": 0,
      "share_count": 12,
      "comment_count": 0,
      "images": {
        "236x": { "url": "https://i.pinimg.com/236x/55/86/54/558654.jpg" },
        "564x": { "url": "https://i.pinimg.com/564x/55/86/54/558654.jpg" },
        "orig": { "url": "https://i.pinimg.com/originals/55/86/54/558654.jpg" }
      },
      "board": {
        "name": "Home Ideas",
        "privacy": "public",
        "owner": { "username": "johndoe", "full_name": "John Doe" }
      },
      "comments": []
    }
  ]
}

User Profile

{
  "type": "user_profile",
  "source_url": "https://www.pinterest.com/dudadelsanto/",
  "count": 1,
  "items": [
    {
      "type": "user",
      "id": "495648099432234901",
      "url": "https://www.pinterest.com/dudadelsanto/",
      "username": "dudadelsanto",
      "full_name": "Duda Del Santo",
      "about": "Fashion & beauty enthusiast",
      "follower_count": 15200,
      "following_count": 430,
      "board_count": 48,
      "pin_count": 3200,
      "monthly_views": 2100000,
      "verified_identity": {}
    }
  ]
}

---

⚙️ Environment Variables

Variable	Required	Description
PROXY_HOST	No	Proxy host:port (e.g. p.webshare.io:80)
PROXY_USER	No	Proxy username
PROXY_PASS	No	Proxy password
API_URL	No	Backend API URL (enables API mode)
PINTEREST_API_KEY	No	API key for backend API mode

---

🔧 Project Structure

pinterest-details-scraper/
├── .actor/
│   └── actor.json          # Apify actor configuration
├── src/
│   ├── __init__.py
│   └── scraper.py          # Core scraping functions
├── main.py                 # Actor entry point
├── Dockerfile              # Docker build config
├── requirements.txt        # Python dependencies
├── input_schema.json       # Apify input schema
└── README.md

---

🛠 How It Works

1. Reads input from Apify (queries and start_urls)
2. Processes keyword searches via Pinterest's internal search API
3. Auto-classifies each URL as pin, profile, board, ideas, or search
4. Fetches data with full pagination support
5. Pushes structured JSON results to the Apify Dataset

---

⚠️ Error Handling

• Unsupported URLs are safely skipped with a log message
• All requests use retry logic (3 attempts) with 2-second delays
• Clear error logs via Actor.log.error()
• Graceful handling of missing or empty API responses

---

📌 Use Cases

• Pinterest market & trend research
• Content inspiration & discovery
• Social media analytics
• Lead generation for creators/brands
• Data aggregation for dashboards

---

📄 License

Free to use and extend for your own projects.