ShopGoodwill APIshopgoodwill.com ↗

"""
ShopGoodwill API Client
Search and browse auction listings on shopgoodwill.com.
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 ShopGoodwill Parse 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 = "49f1b060-de69-477f-9028-da1eea2aff21"
        self.api_key = api_key or os.getenv("PARSE_API_KEY")

        if not self.api_key:
            raise ValueError("API key must be provided or set in 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_listings')
            method: HTTP method ('GET' or 'POST')
            **params: Query/body parameters for the endpoint

        Returns:
            JSON response from the API

        Raises:
            requests.RequestException: If the request fails
        """
        url = f"{self.base_url}/scraper/{self.scraper_id}/{endpoint}"
        headers = {
            "X-API-Key": self.api_key,
            "Content-Type": "application/json"
        }

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

        response.raise_for_status()
        return response.json()

    def search_listings(
        self,
        query: Optional[str] = None,
        category_id: Optional[int] = None,
        low_price: str = "0",
        high_price: str = "999999",
        page: int = 1,
        page_size: int = 40,
        sort_column: str = "1",
        sort_descending: str = "false",
        seller_id: Optional[str] = None,
        closed_auctions: str = "false"
    ) -> Dict[str, Any]:
        """
        Search for items on shopgoodwill.com with filters.

        Args:
            query: Search keyword
            category_id: Category ID to filter by
            low_price: Minimum price
            high_price: Maximum price
            page: Page number (1-based)
            page_size: Number of items per page
            sort_column: Column to sort by (1=Ending Soonest, 2=Newly Listed)
            sort_descending: Whether to sort descending
            seller_id: Seller ID to filter by
            closed_auctions: Whether to search for closed auctions

        Returns:
            Search results with items and item count
        """
        return self._call(
            "search_listings",
            method="GET",
            query=query,
            category_id=category_id,
            low_price=low_price,
            high_price=high_price,
            page=page,
            page_size=page_size,
            sort_column=sort_column,
            sort_descending=sort_descending,
            seller_id=seller_id,
            closed_auctions=closed_auctions
        )

    def get_item_details(self, item_id: str) -> Dict[str, Any]:
        """
        Get full details for a single item by its ID.

        Args:
            item_id: The item ID

        Returns:
            Item details including title, description, price, and bid count
        """
        return self._call("get_item_details", method="GET", item_id=item_id)

    def get_categories(self) -> List[Dict[str, Any]]:
        """
        Get all top-level categories.

        Returns:
            List of category objects with categoryId, name, and children
        """
        return self._call("get_categories", method="GET")

    def get_subcategories(self, parent_category_id: str) -> List[Dict[str, Any]]:
        """
        Get subcategories for a given parent category ID.

        Args:
            parent_category_id: The parent category ID

        Returns:
            List of subcategory objects
        """
        return self._call("get_subcategories", method="GET", parent_category_id=parent_category_id)

    def get_item_shipping(self, item_id: str) -> Dict[str, Any]:
        """
        Get shipping information for an item.

        Args:
            item_id: The item ID

        Returns:
            Shipping and handling price information
        """
        return self._call("get_item_shipping", method="GET", item_id=item_id)

    def get_item_bid_history(self, item_id: str) -> Dict[str, Any]:
        """
        Get the bid history for an item.

        Args:
            item_id: The item ID

        Returns:
            Bid history and summary information
        """
        return self._call("get_item_bid_history", method="GET", item_id=item_id)

    def get_advanced_search_filters(self) -> Dict[str, Any]:
        """
        Get all available search filters (categories and sellers).

        Returns:
            Dictionary with categories and sellers arrays
        """
        return self._call("get_advanced_search_filters", method="GET")

    def get_featured_items(self) -> Dict[str, Any]:
        """
        Get featured items from the homepage gallery.

        Returns:
            Featured items data with items array and total count
        """
        return self._call("get_featured_items", method="GET")

    def get_newly_listed(
        self,
        category_id: int = 0,
        page: int = 1,
        page_size: int = 40
    ) -> Dict[str, Any]:
        """
        Get the most recently listed auction items.

        Args:
            category_id: Category ID to filter by (0 for all)
            page: Page number (1-based)
            page_size: Number of items per page

        Returns:
            Recently listed search results
        """
        return self._call(
            "get_newly_listed",
            method="GET",
            category_id=category_id,
            page=page,
            page_size=page_size
        )


if __name__ == "__main__":
    # Initialize client
    client = ParseClient()

    print("=" * 80)
    print("ShopGoodwill Auction Deal Finder - Practical Workflow")
    print("=" * 80)

    # Step 1: Search for items matching criteria (vintage items under $100)
    print("\n[STEP 1] Searching for vintage items priced under $100...")
    search_results = client.search_listings(
        query="vintage",
        low_price="0",
        high_price="100",
        page=1,
        page_size=8,
        sort_column="1"  # Sort by ending soonest
    )

    items = search_results.get("searchResults", {}).get("items", [])
    total_count = search_results.get("searchResults", {}).get("itemCount", 0)
    print(f"   ✓ Found {total_count} total vintage items (showing {len(items)} on first page)")

    if not items:
        print("   No items found. Fetching featured items instead...")
        featured_response = client.get_featured_items()
        items = featured_response.get("items", [])[:8]
        print(f"   ✓ Using {len(items)} featured items for analysis")

    # Step 2: Analyze each item's total cost and bid activity
    print("\n[STEP 2] Analyzing item details, shipping, and bid activity...")
    items_analysis = []

    for idx, item in enumerate(items, 1):
        item_id = str(item.get("itemId"))
        title = item.get("title", "Unknown")[:60]  # Truncate for readability
        current_price = float(item.get("currentPrice", 0))
        num_bids = item.get("numBids", 0)

        # Get detailed item information
        try:
            item_details = client.get_item_details(item_id)
            description_length = len(item_details.get("description", ""))
        except Exception as e:
            print(f"   Warning: Could not fetch details for item {item_id}: {e}")
            description_length = 0

        # Get shipping information
        try:
            shipping_info = client.get_item_shipping(item_id)
            shipping_price = float(shipping_info.get("shippingPrice", 0))
            handling_price = float(shipping_info.get("handlingPrice", 0))
            shipper = shipping_info.get("shipper", "Unknown")
        except Exception as e:
            print(f"   Warning: Could not fetch shipping for item {item_id}: {e}")
            shipping_price = 0
            handling_price = 0
            shipper = "Unknown"

        # Get bid history for activity metrics
        try:
            bid_history = client.get_item_bid_history(item_id)
            bid_summary = bid_history.get("bidSummary", [])
            highest_bidder = bid_summary[-1].get("bidderName", "N/A") if bid_summary else "No bids"
        except Exception as e:
            print(f"   Warning: Could not fetch bid history for item {item_id}: {e}")
            highest_bidder = "N/A"

        total_cost = current_price + shipping_price + handling_price

        item_analysis = {
            "item_id": item_id,
            "title": title,
            "current_price": current_price,
            "shipping_price": shipping_price,
            "handling_price": handling_price,
            "total_cost": total_cost,
            "num_bids": num_bids,
            "shipper": shipper,
            "highest_bidder": highest_bidder,
            "description_length": description_length
        }
        items_analysis.append(item_analysis)

        print(f"\n   Item {idx}: {title}")
        print(f"      Current Bid: ${current_price:.2f}")
        print(f"      Shipping: ${shipping_price:.2f} via {shipper}")
        print(f"      Handling: ${handling_price:.2f}")
        print(f"      Total Cost: ${total_cost:.2f}")
        print(f"      Bid Count: {num_bids} | Top Bidder: {highest_bidder}")

    # Step 3: Find the best deals (lowest total cost)
    print("\n[STEP 3] TOP DEALS - Lowest total cost items")
    print("   " + "-" * 70)
    sorted_by_cost = sorted(items_analysis, key=lambda x: x["total_cost"])
    for rank, item in enumerate(sorted_by_cost[:3], 1):
        print(f"   {rank}. {item['title']}")
        print(f"      Total Cost: ${item['total_cost']:.2f} "
              f"(Bid: ${item['current_price']:.2f} + Ship: ${item['shipping_price']:.2f})")

    # Step 4: Find most competitive items (high bid activity)
    print("\n[STEP 4] HOTTEST ITEMS - Most bids/highest competition")
    print("   " + "-" * 70)
    sorted_by_bids = sorted(items_analysis, key=lambda x: x["num_bids"], reverse=True)
    for rank, item in enumerate(sorted_by_bids[:3], 1):
        print(f"   {rank}. {item['title']}")
        print(f"      Bids: {item['num_bids']} | Current Price: ${item['current_price']:.2f}")

    # Step 5: Best value items (low total cost AND good descriptions)
    print("\n[STEP 5] BEST VALUE - Low cost with detailed descriptions")
    print("   " + "-" * 70)
    # Filter items with meaningful descriptions
    detailed_items = [item for item in items_analysis if item["description_length"] > 100]
    if detailed_items:
        sorted_by_value = sorted(detailed_items, key=lambda x: x["total_cost"])
        for rank, item in enumerate(sorted_by_value[:3], 1):
            print(f"   {rank}. {item['title']}")
            print(f"      Total Cost: ${item['total_cost']:.2f} "
                  f"| Description: {item['description_length']} characters")
    else:
        print("   (No items with detailed descriptions found)")

    # Step 6: Browse categories for future searches
    print("\n[STEP 6] Available categories for targeted searches")
    print("   " + "-" * 70)
    try:
        categories = client.get_categories()
        if isinstance(categories, dict):
            categories = categories.get("data", [])
        if isinstance(categories, list):
            print(f"   Total categories: {len(categories)}")
            for cat in categories[:5]:
                cat_name = cat.get("name", "Unknown")
                cat_id = cat.get("categoryId", "N/A")
                num_children = len(cat.get("children", []))
                print(f"   - {cat_name} (ID: {cat_id}) - {num_children} subcategories")
    except Exception as e:
        print(f"   Could not fetch categories: {e}")

    # Summary statistics
    print("\n[SUMMARY] Analysis Results")
    print("   " + "-" * 70)
    avg_cost = sum(item["total_cost"] for item in items_analysis) / len(items_analysis)
    avg_bids = sum(item["num_bids"] for item in items_analysis) / len(items_analysis)
    lowest_cost = min(items_analysis, key=lambda x: x["total_cost"])["total_cost"]
    highest_bids = max(items_analysis, key=lambda x: x["num_bids"])["num_bids"]

    print(f"   Items Analyzed: {len(items_analysis)}")
    print(f"   Average Total Cost: ${avg_cost:.2f}")
    print(f"   Lowest Total Cost: ${lowest_cost:.2f}")
    print(f"   Average Bids per Item: {avg_bids:.1f}")
    print(f"   Highest Bid Count: {highest_bids}")

    print("\n" + "=" * 80)
    print("✓ Deal analysis complete! Review the recommendations above.")
    print("=" * 80)