Coolblue APIcoolblue.nl ↗

"""
Coolblue Laptop Scraper API - Python Client

Get your API key from: https://parse.bot/settings
"""

import os
import requests
from typing import Any, Dict, List, Optional


class ParseClient:
    """Client for interacting with the Coolblue Laptop Scraper API."""

    def __init__(self, api_key: Optional[str] = None):
        """
        Initialize the Parse API client.

        Args:
            api_key: API key for authentication. If not provided, reads from PARSE_API_KEY env var.
        """
        self.base_url = "https://api.parse.bot"
        self.scraper_id = "3313b917-e6fd-4f12-affa-3f1888f5cfa9"
        self.api_key = api_key or os.getenv("PARSE_API_KEY")

        if not self.api_key:
            raise ValueError(
                "API key not provided. Pass it as argument or set PARSE_API_KEY environment variable."
            )

    def _call(
        self, endpoint: str, method: str = "POST", **params
    ) -> Dict[str, Any]:
        """
        Make a request to the Parse API.

        Args:
            endpoint: The endpoint name (e.g., 'search_products')
            method: HTTP method ('GET' or 'POST')
            **params: Query/body parameters

        Returns:
            JSON response as dictionary
        """
        url = f"{self.base_url}/scraper/{self.scraper_id}/{endpoint}"
        headers = {"X-API-Key": self.api_key, "Content-Type": "application/json"}

        if method == "GET":
            response = requests.get(url, headers=headers, params=params)
        elif method == "POST":
            response = requests.post(url, headers=headers, json=params)
        else:
            raise ValueError(f"Unsupported method: {method}")

        response.raise_for_status()
        return response.json()

    def search_products(
        self,
        query: str,
        page: int = 1,
        sort: str = "relevance",
    ) -> Dict[str, Any]:
        """
        Search for products across all categories.

        Args:
            query: Search keyword
            page: Page number for pagination (default: 1)
            sort: Sorting option - relevance, price_asc, price_desc, newest, rating (default: relevance)

        Returns:
            Dictionary with 'total' count and 'products' list
        """
        return self._call(
            "search_products", method="GET", query=query, page=page, sort=sort
        )

    def search_laptops(
        self,
        query: Optional[str] = None,
        page: int = 1,
        sort: str = "relevance",
    ) -> Dict[str, Any]:
        """
        Search specifically for laptops with spec highlights.

        Args:
            query: Search keyword for laptops (optional)
            page: Page number (default: 1)
            sort: Sorting option (default: relevance)

        Returns:
            Dictionary with 'total' count and 'products' list with laptop specs
        """
        params = {"page": page, "sort": sort}
        if query:
            params["query"] = query
        return self._call("search_laptops", method="GET", **params)

    def get_laptop_listings_by_category(
        self, category: str = "laptops", page: int = 1
    ) -> Dict[str, Any]:
        """
        Browse laptop listings by category.

        Args:
            category: Category slug (default: laptops)
            page: Page number (default: 1)

        Returns:
            Dictionary with 'total' count and 'products' list
        """
        return self._call(
            "get_laptop_listings_by_category",
            method="GET",
            category=category,
            page=page,
        )

    def get_laptop_listings_by_brand(
        self, brand: str, page: int = 1
    ) -> Dict[str, Any]:
        """
        Browse laptops by brand.

        Args:
            brand: Brand name (e.g., hp, lenovo, apple, asus)
            page: Page number (default: 1)

        Returns:
            Dictionary with 'total' count and 'products' list
        """
        return self._call(
            "get_laptop_listings_by_brand", method="GET", brand=brand, page=page
        )

    def get_laptop_details(self, product_id: str, slug: str) -> Dict[str, Any]:
        """
        Get detailed specifications for a laptop.

        Args:
            product_id: The numeric product ID
            slug: The product URL slug

        Returns:
            Dictionary with 'name' and 'specifications' object
        """
        return self._call(
            "get_laptop_details", method="GET", product_id=product_id, slug=slug
        )

    def get_new_laptops(self, page: int = 1) -> Dict[str, Any]:
        """
        Retrieve newly added laptop items.

        Args:
            page: Page number (default: 1)

        Returns:
            Dictionary with 'products' list
        """
        return self._call("get_new_laptops", method="GET", page=page)

    def get_laptop_reviews(
        self, product_id: str, slug: str, page: int = 1
    ) -> Dict[str, Any]:
        """
        Retrieve customer reviews for a specific laptop.

        Args:
            product_id: The numeric product ID
            slug: The product URL slug
            page: Page number (default: 1)

        Returns:
            Dictionary with 'reviews' list containing rating, text, and author
        """
        return self._call(
            "get_laptop_reviews",
            method="GET",
            product_id=product_id,
            slug=slug,
            page=page,
        )

    def get_affordable_second_chance(self, page: int = 1) -> Dict[str, Any]:
        """
        Retrieve refurbished/second-chance laptops.

        Args:
            page: Page number (default: 1)

        Returns:
            Dictionary with 'products' list
        """
        return self._call(
            "get_affordable_second_chance", method="GET", page=page
        )


def extract_slug_from_url(url: str) -> str:
    """Extract product slug from URL."""
    if not url:
        return "unknown"
    return url.rstrip("/").split("/")[-1]


def main():
    """
    Practical workflow: Find high-rated MacBooks, compare their specifications,
    read customer reviews, and check for refurbished alternatives.
    """
    client = ParseClient()

    print("=" * 80)
    print("COOLBLUE LAPTOP FINDER - MACBOOK ANALYSIS & COMPARISON")
    print("=" * 80)

    # Step 1: Search for MacBooks
    print("\n[STEP 1] Searching for MacBooks sorted by rating...")
    search_results = client.search_products(
        query="MacBook", sort="rating", page=1
    )
    all_macbooks = search_results.get("products", [])
    total_found = search_results.get("total", 0)

    print(f"Found {total_found} total MacBook results")
    print(f"Retrieved {len(all_macbooks)} products\n")

    if not all_macbooks:
        print("No MacBooks found. Exiting.")
        return

    # Step 2: Filter and display top-rated MacBooks
    print("--- Top-Rated MacBooks Available ---")
    top_macbooks = all_macbooks[:5]
    
    for idx, macbook in enumerate(top_macbooks, 1):
        name = macbook.get("name", "Unknown")
        price = macbook.get("price", "N/A")
        reviews_count = macbook.get("reviews_count", 0)
        print(f"{idx}. {name}")
        print(f"   Price: €{price} | Customer Reviews: {reviews_count}\n")

    # Step 3: Get detailed specs for the top MacBook
    print("[STEP 2] Retrieving detailed specifications for top MacBook...")
    top_macbook = top_macbooks[0]
    product_id = top_macbook.get("product_id")
    url = top_macbook.get("url", "")
    slug = extract_slug_from_url(url)

    try:
        details = client.get_laptop_details(product_id=product_id, slug=slug)
        spec_name = details.get("name", "Unknown")
        specifications = details.get("specifications", {})

        print(f"Detailed specs for: {spec_name}")
        if specifications:
            for spec_key, spec_value in list(specifications.items())[:8]:
                print(f"  • {spec_key}: {spec_value}")
        else:
            print("  (No detailed specifications available)")
    except Exception as e:
        print(f"  Could not retrieve details: {str(e)}")

    # Step 4: Search with laptop-specific endpoint
    print("\n[STEP 3] Searching with laptop-specific endpoint for MacBooks...")
    laptop_search = client.search_laptops(query="MacBook", page=1)
    laptop_products = laptop_search.get("products", [])

    print(f"Found {len(laptop_products)} MacBooks with detailed specs\n")
    print("--- MacBook Specs Comparison ---")
    
    for idx, laptop in enumerate(laptop_products[:4], 1):
        name = laptop.get("name", "Unknown")
        processor = laptop.get("processor", "N/A")
        screen = laptop.get("screen_size", "N/A")
        price = laptop.get("price", "N/A")
        rating = laptop.get("rating", "N/A")
        print(f"{idx}. {name}")
        print(f"   Processor: {processor} | Screen: {screen}")
        print(f"   Price: €{price} | Rating: {rating}\n")

    # Step 5: Browse Apple MacBooks via brand filter
    print("[STEP 4] Browsing all Apple laptops by brand...")
    apple_laptops = client.get_laptop_listings_by_brand(brand="apple", page=1)
    apple_products = apple_laptops.get("products", [])
    apple_total = apple_laptops.get("total", 0)

    print(f"Total Apple laptops available: {apple_total}")
    print(f"Showing {len(apple_products)} results:\n")

    for idx, apple in enumerate(apple_products[:4], 1):
        name = apple.get("name", "Unknown")
        price = apple.get("price", "N/A")
        rating = apple.get("rating", "N/A")
        print(f"{idx}. {name}")
        print(f"   Price: €{price} | Rating: {rating}\n")

    # Step 6: Get customer reviews for the top MacBook
    print("[STEP 5] Fetching customer reviews for top MacBook...")
    try:
        reviews_data = client.get_laptop_reviews(
            product_id=product_id, slug=slug, page=1
        )
        reviews = reviews_data.get("reviews", [])
        avg_rating = reviews_data.get("average_rating", "N/A")
        total_reviews = reviews_data.get("total_reviews", 0)
        rating_categories = reviews_data.get("rating_categories", [])

        print(f"Average Rating: {avg_rating}/10 ({total_reviews} total reviews)")
        
        if rating_categories:
            print("\nRating Breakdown by Category:")
            for category in rating_categories[:4]:
                cat_name = category.get("name", "Unknown")
                cat_avg = category.get("averageRating", "N/A")
                print(f"  • {cat_name}: {cat_avg}/10")
        
        if reviews:
            print("\n--- Recent Customer Reviews ---\n")
            for idx, review in enumerate(reviews[:3], 1):
                title = review.get("title", "No title")
                author = review.get("author", "Anonymous")
                rating = review.get("rating", "N/A")
                text = review.get("text", "")[:120]
                votes_up = review.get("votes_up", 0)
                pros = review.get("pros", [])

                print(f"{idx}. {title}")
                print(f"   By {author} | Rating: {rating}/10 | Helpful: {votes_up}👍")
                print(f'   "{text}..."')
                if pros:
                    print(f"   Pros: {', '.join(pros[:2])}")
                print()
    except Exception as e:
        print(f"Could not retrieve reviews: {str(e)}")

    # Step 7: Check for refurbished MacBook deals
    print("[STEP 6] Checking for refurbished/second-chance MacBook deals...")
    refurb_results = client.get_affordable_second_chance(page=1)
    refurb_products = refurb_results.get("products", [])
    
    # Filter for MacBooks in refurbished section
    refurb_macbooks = [p for p in refurb_products if "macbook" in p.get("name", "").lower()]

    if refurb_macbooks:
        print(f"Found {len(refurb_macbooks)} refurbished MacBooks\n")
        print("--- Refurbished MacBook Deals ---\n")

        for idx, refurb in enumerate(refurb_macbooks[:4], 1):
            name = refurb.get("name", "Unknown")
            price = refurb.get("price", "N/A")
            highlights = refurb.get("highlights", [])

            print(f"{idx}. {name}")
            print(f"   Price: €{price}")
            if highlights:
                for highlight in highlights[:2]:
                    print(f"   • {highlight}")
            print()
    else:
        print(f"No refurbished MacBooks found (checked {len(refurb_products)} total refurbished items)")

    # Step 8: Check new arrivals
    print("[STEP 7] Checking for newly added laptops...")
    new_arrivals = client.get_new_laptops(page=1)
    new_products = new_arrivals.get("products", [])
    
    # Filter for new MacBooks
    new_macbooks = [p for p in new_products if "macbook" in p.get("name", "").lower()]

    if new_macbooks:
        print(f"Found {len(new_macbooks)} newly added MacBooks\n")
        print("--- Latest MacBook Arrivals ---\n")
        for idx, new_laptop in enumerate(new_macbooks[:3], 1):
            name = new_laptop.get("name", "Unknown")
            price = new_laptop.get("price", "N/A")
            print(f"{idx}. {name} - €{price}\n")
    else:
        print("No newly arrived MacBooks at this time")

    # Summary and recommendations
    print("=" * 80)
    print("ANALYSIS COMPLETE - SUMMARY & RECOMMENDATIONS")
    print("=" * 80)
    print(f"\n✓ Found {len(top_macbooks)} highly-rated MacBooks (€{top_macbook.get('price', 'N/A')} starting)")
    print(f"✓ Apple brand catalog has {apple_total} total laptop models")
    print(f"✓ Top MacBook has {total_reviews} customer reviews (average: {avg_rating}/10)")
    print(f"✓ {len(refurb_macbooks)} refurbished MacBooks available for cost savings")