Makro APImakro.co.za ↗

"""
Makro South Africa Product Search API Client

Search for products on Makro South Africa and retrieve detailed product information.
Get your API key from: https://parse.bot/settings
"""

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


class ParseClient:
    """Client for interacting with the Parse API for Makro South Africa product search."""

    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 = "1cdaa9e6-11b8-4b19-8960-115fcba2c0d4"
        self.api_key = api_key or os.getenv("PARSE_API_KEY")

        if not self.api_key:
            raise ValueError(
                "API key not provided. Set PARSE_API_KEY environment variable or pass api_key parameter."
            )

    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 parameters or JSON payload

        Returns:
            Response data as a dictionary

        Raises:
            requests.exceptions.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_products(
        self, query: str, page: int = 1
    ) -> Dict[str, Any]:
        """
        Search for products on Makro South Africa.

        Args:
            query: Search query text (e.g., 'laptop', 'tv', 'headphones')
            page: Page number for pagination (default: 1)

        Returns:
            Dictionary containing search results with product listings
        """
        return self._call(
            "search_products",
            method="POST",
            query=query,
            page=page,
        )


def format_currency(amount: float) -> str:
    """Format amount as South African Rand."""
    return f"R {amount:,.2f}"


def print_product_info(product: Dict[str, Any]) -> None:
    """Print formatted product information."""
    print(f"  📦 {product['name']}")
    print(f"     Brand: {product['brand']}")
    print(f"     Price: {format_currency(product['price'])}")
    if product.get("rating"):
        print(f"     Rating: ⭐ {product['rating']} ({product['rating_count']} reviews)")
    print(f"     Details: {product['subtitle']}")
    print()


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

    # Practical workflow: Search for products and browse through results
    search_query = "laptop"
    print(f"🔍 Searching Makro South Africa for '{search_query}'...\n")

    try:
        # First page of results
        results = client.search_products(query=search_query, page=1)

        # Extract response data
        total_results = results["data"]["total_results"]
        has_more_pages = results["data"]["has_more_pages"]
        products = results["data"]["products"]

        print(f"✅ Found {total_results} products\n")
        print(f"📄 Page 1 - Showing {len(products)} products:\n")

        # Display first page products
        for idx, product in enumerate(products, 1):
            print(f"{idx}. ", end="")
            print_product_info(product)

        # If there are more pages, show pagination capability
        if has_more_pages:
            print(f"📚 More pages available. Fetching page 2...\n")

            # Fetch second page
            page_2_results = client.search_products(query=search_query, page=2)
            page_2_products = page_2_results["data"]["products"]

            print(f"📄 Page 2 - Showing {len(page_2_products)} products:\n")
            for idx, product in enumerate(page_2_products, 1):
                print(f"{idx}. ", end="")
                print_product_info(product)

        # Find the cheapest and most expensive products from page 1
        if products:
            cheapest = min(products, key=lambda x: x["price"])
            most_expensive = max(products, key=lambda x: x["price"])
            avg_price = sum(p["price"] for p in products) / len(products)

            print("💡 Price Analysis (Page 1):")
            print(f"   Cheapest: {cheapest['name'][:50]}... at {format_currency(cheapest['price'])}")
            print(
                f"   Most Expensive: {most_expensive['name'][:50]}... at {format_currency(most_expensive['price'])}"
            )
            print(f"   Average Price: {format_currency(avg_price)}")

    except requests.exceptions.RequestException as e:
        print(f"❌ Error: Failed to fetch products - {e}")
    except KeyError as e:
        print(f"❌ Error: Unexpected response format - {e}")
    except ValueError as e:
        print(f"❌ Configuration error: {e}")