SPAR APIspar.co.za ↗

"""
SPAR South Africa Product Catalog API Client

Search the SPAR South Africa product catalog for grocery items.
Get your API key from: https://parse.bot/settings
"""

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


class ParseClient:
    """Client for interacting with the SPAR South Africa Product Catalog 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 = "3bdd71ec-f83f-486e-ad7d-f41d77d75337"
        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 to call.
            method: HTTP method (GET or POST).
            **params: Parameters to send with the request.

        Returns:
            Response JSON 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) -> Dict[str, Any]:
        """
        Search the SPAR product catalog by keyword.

        Args:
            query: Search term to find products by name or description (e.g., 'milk', 'bread', 'coconut').

        Returns:
            Dictionary containing:
                - query: The search term used
                - total_results: Number of matching products
                - products: List of product objects with product_id, name, description, size, and image_url
        """
        return self._call("search_products", method="GET", query=query)


def format_product(product: Dict[str, Any]) -> str:
    """Format a product dictionary for display."""
    return (
        f"  • {product['name']}\n"
        f"    ID: {product['product_id']} | Size: {product['size']}\n"
        f"    Description: {product['description']}\n"
        f"    Image: {product['image_url']}"
    )


def main():
    """Demonstrate practical usage of the SPAR Product Catalog API."""

    # Initialize the client
    client = ParseClient()

    # Define search queries representing a typical shopping workflow
    shopping_list = ["bread", "milk", "coconut"]

    print("=" * 70)
    print("SPAR South Africa Product Catalog Search")
    print("=" * 70)

    # Search for multiple items and collect results
    all_results = {}

    for item in shopping_list:
        print(f"\nSearching for: {item.upper()}")
        print("-" * 70)

        try:
            result = client.search_products(query=item)

            # Store results for later use
            all_results[item] = result

            # Display search summary
            print(f"Found {result['total_results']} product(s)")

            # Display first 3 products
            products_to_show = result["products"][:3]
            for product in products_to_show:
                print(format_product(product))

            if result["total_results"] > 3:
                print(f"  ... and {result['total_results'] - 3} more products")

        except requests.exceptions.RequestException as e:
            print(f"Error searching for '{item}': {e}")

    # Summary report
    print("\n" + "=" * 70)
    print("SHOPPING SUMMARY")
    print("=" * 70)

    total_products_found = sum(r["total_results"] for r in all_results.values())
    print(f"Total items searched: {len(all_results)}")
    print(f"Total products found: {total_products_found}\n")

    for item, result in all_results.items():
        if result["products"]:
            top_product = result["products"][0]
            print(
                f"• {item.upper()}: {top_product['name']} ({top_product['size']})"
            )


if __name__ == "__main__":
    main()