Game APIgame.co.za ↗

"""
Game South Africa Product Search API - Parse Client
Search for products on Game.co.za with pagination support.
Get your API key from: https://parse.bot/settings
"""

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


@dataclass
class Product:
    """Represents a product from Game.co.za"""
    code: str
    name: str
    price: float
    formatted_price: str
    currency: str
    image_url: str
    brand: str
    in_stock: bool
    rating: Optional[float]
    review_count: Optional[int]

    def __str__(self) -> str:
        stock_status = "✓ In Stock" if self.in_stock else "✗ Out of Stock"
        rating_str = f"⭐ {self.rating} ({self.review_count} reviews)" if self.rating else "No ratings"
        return f"{self.name}\n  Brand: {self.brand}\n  Price: {self.formatted_price}\n  {stock_status}\n  {rating_str}"


class ParseClient:
    """Client for Game South Africa Product Search 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 = "1b9ac293-18b9-4a82-812b-21665d25555b"
        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 an API call to the Parse bot
        
        Args:
            endpoint: The endpoint name (e.g., "search_products")
            method: HTTP method ("GET" or "POST")
            **params: Query/body parameters
            
        Returns:
            API response as dictionary
        """
        url = f"{self.base_url}/scraper/{self.scraper_id}/{endpoint}"
        headers = {
            "X-API-Key": self.api_key,
            "Content-Type": "application/json"
        }

        try:
            if method.upper() == "GET":
                response = requests.get(url, headers=headers, params=params, timeout=30)
            else:  # POST
                response = requests.post(url, headers=headers, json=params, timeout=30)
            
            response.raise_for_status()
            return response.json()
        except requests.exceptions.RequestException as e:
            print(f"API Error: {e}")
            raise

    def search_products(self, query: str, page: int = 1, page_size: int = 20) -> Dict[str, Any]:
        """Search for products by name on Game.co.za
        
        Args:
            query: Search query text (e.g., 'samsung', 'laptop')
            page: Page number for pagination (1-based, default: 1)
            page_size: Number of results per page, 1-100 (default: 20)
            
        Returns:
            Dictionary containing search results with products list
        """
        return self._call("search_products", method="POST", query=query, page=page, page_size=page_size)


def main():
    """Practical workflow example: Search for products and analyze results"""
    
    # Initialize the client
    client = ParseClient()
    
    # Practical use case: Find all Samsung products across multiple pages
    search_query = "samsung"
    print(f"\n🔍 Searching for '{search_query}' on Game.co.za...\n")
    
    all_products: List[Product] = []
    pages_to_check = 2  # Check first 2 pages
    
    for page_num in range(1, pages_to_check + 1):
        print(f"📄 Fetching page {page_num}...")
        
        try:
            # Search with pagination
            results = client.search_products(
                query=search_query,
                page=page_num,
                page_size=10  # Get 10 results per page for demo
            )
            
            # Parse results
            total_results = results.get("total_results", 0)
            total_pages = results.get("total_pages", 0)
            products_data = results.get("products", [])
            
            if not products_data:
                print(f"  No more products found.")
                break
            
            print(f"  Found {len(products_data)} products on this page")
            print(f"  Total results available: {total_results} across {total_pages} pages\n")
            
            # Convert to Product objects for easier handling
            for product_data in products_data:
                product = Product(
                    code=product_data.get("code"),
                    name=product_data.get("name"),
                    price=product_data.get("price", 0),
                    formatted_price=product_data.get("formatted_price"),
                    currency=product_data.get("currency"),
                    image_url=product_data.get("image_url"),
                    brand=product_data.get("brand"),
                    in_stock=product_data.get("in_stock", False),
                    rating=product_data.get("rating"),
                    review_count=product_data.get("review_count")
                )
                all_products.append(product)
        
        except Exception as e:
            print(f"  Error fetching page {page_num}: {e}")
            break
    
    # Analysis: Find best deals and in-stock items
    print("\n" + "="*60)
    print("📊 ANALYSIS RESULTS")
    print("="*60)
    
    if all_products:
        # In-stock products
        in_stock = [p for p in all_products if p.in_stock]
        print(f"\n✓ In-stock products: {len(in_stock)}/{len(all_products)}")
        
        # Products with ratings
        rated_products = [p for p in all_products if p.rating is not None]
        print(f"⭐ Products with ratings: {len(rated_products)}/{len(all_products)}")
        
        if rated_products:
            # Find highest rated
            top_rated = max(rated_products, key=lambda x: x.rating)
            print(f"\n🏆 Highest Rated Product:")
            print(f"  {top_rated.name}")
            print(f"  Rating: {top_rated.rating} stars ({top_rated.review_count} reviews)")
            print(f"  Price: {top_rated.formatted_price}")
        
        # Find cheapest in-stock
        if in_stock:
            cheapest = min(in_stock, key=lambda x: x.price)
            print(f"\n💰 Cheapest In-Stock Product:")
            print(f"  {cheapest.name}")
            print(f"  Price: {cheapest.formatted_price}")
            print(f"  Brand: {cheapest.brand}")
        
        # Price range
        prices = [p.price for p in all_products]
        print(f"\n💵 Price Range:")
        print(f"  Lowest: R{min(prices):,.2f}")
        print(f"  Highest: R{max(prices):,.2f}")
        print(f"  Average: R{sum(prices)/len(prices):,.2f}")
        
        # Brand breakdown
        brands = {}
        for product in all_products:
            brands[product.brand] = brands.get(product.brand, 0) + 1
        
        print(f"\n🏢 Top Brands Found:")
        for brand, count in sorted(brands.items(), key=lambda x: x[1], reverse=True)[:5]:
            print(f"  {brand}: {count} products")
    else:
        print("No products found in the search results.")


if __name__ == "__main__":
    main()