AllModern APIallmodern.com ↗

"""
AllModern Product Search API Client

This module provides a Python client for searching and browsing modern furniture,
lighting, and decor products on AllModern.com.

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 AllModern 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.

        Raises:
            ValueError: If no API key is provided or found in environment.
        """
        self.base_url = "https://api.parse.bot"
        self.scraper_id = "d58dcdc2-e789-49ff-aef9-0a8efd155b9a"
        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 an API call to the Parse service.

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

        Returns:
            Dictionary containing the API response

        Raises:
            requests.RequestException: If the API call fails
            ValueError: If an unsupported HTTP method is provided
        """
        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 HTTP method: {method}")

        response.raise_for_status()
        return response.json()

    def search_products(
        self,
        query: str,
        page: int = 1,
        sort_by: str = "",
    ) -> Dict[str, Any]:
        """
        Search for products on AllModern by keyword.

        Args:
            query: Search keyword (e.g., 'sofa', 'lamp', 'rug', 'desk')
            page: Page number for pagination (default: 1)
            sort_by: Sort order - 'price_low', 'price_high', 'top_rated', 'most_popular', 'newest'

        Returns:
            Dictionary containing search results with products and pagination info
        """
        params = {
            "query": query,
            "page": page,
        }
        if sort_by:
            params["sort_by"] = sort_by

        return self._call("search_products", method="GET", **params)


def format_price(price: float) -> str:
    """Format price as currency string."""
    return f"${price:.2f}"


def print_product_summary(product: Dict[str, Any], index: int = 0) -> None:
    """Print a concise product summary."""
    name = product["name"]
    price = product.get("sale_price") or product.get("original_price", 0)
    rating = product.get("rating", "N/A")
    reviews = product.get("review_count", 0)
    
    if index > 0:
        print(f"\n  {index}. {name}")
    else:
        print(f"  • {name}")
    
    print(f"     Price: {format_price(price)} | Rating: {rating}★ ({reviews} reviews)")
    
    if product.get("badge"):
        print(f"     Badge: {product['badge']}")


def main():
    """Demonstrate practical usage of the AllModern Product Search API."""
    # Initialize the client
    client = ParseClient()

    print("=" * 80)
    print("AllModern Furniture Search - Practical Workflow")
    print("=" * 80)

    try:
        # Workflow 1: Find top-rated furniture for home office setup
        print("\n📍 WORKFLOW: Furnishing a modern home office\n")
        
        furniture_items = ["desk", "office chair", "bookshelf"]
        office_furniture = {}

        for item in furniture_items:
            print(f"\n🔍 Searching for best-rated '{item}'...")
            results = client.search_products(query=item, page=1, sort_by="top_rated")

            if results.get("products"):
                office_furniture[item] = results["products"][0]
                print(f"   Found: {results['total_results']} results")
                print(f"   Top match: {results['products'][0]['name']}")
                print(f"   Price: {format_price(results['products'][0].get('sale_price') or results['products'][0].get('original_price', 0))}")
                print(f"   Rating: {results['products'][0]['rating']}★ ({results['products'][0]['review_count']} reviews)")

        # Workflow 2: Budget comparison - find affordable alternatives
        print("\n" + "-" * 80)
        print("\n💰 WORKFLOW: Finding budget-friendly alternatives\n")

        search_term = "sofa"
        print(f"Comparing {search_term} options by price...\n")

        # Get most expensive
        expensive = client.search_products(query=search_term, page=1, sort_by="price_high")
        # Get cheapest
        affordable = client.search_products(query=search_term, page=1, sort_by="price_low")

        if expensive.get("products") and affordable.get("products"):
            expensive_sofa = expensive["products"][0]
            cheap_sofa = affordable["products"][0]

            print(f"💎 Most Expensive Option:")
            print(f"   {expensive_sofa['name']}")
            print(f"   Price: {format_price(expensive_sofa.get('sale_price') or expensive_sofa.get('original_price', 0))}")
            print(f"   Rating: {expensive_sofa['rating']}★\n")

            print(f"🎯 Most Affordable Option:")
            print(f"   {cheap_sofa['name']}")
            print(f"   Price: {format_price(cheap_sofa.get('sale_price') or cheap_sofa.get('original_price', 0))}")
            print(f"   Rating: {cheap_sofa['rating']}★")

            price_diff = (expensive_sofa.get('sale_price') or expensive_sofa.get('original_price', 0)) - \
                        (cheap_sofa.get('sale_price') or cheap_sofa.get('original_price', 0))
            print(f"\n   💵 Price difference: {format_price(price_diff)}")

        # Workflow 3: Browse multiple pages for lighting options
        print("\n" + "-" * 80)
        print("\n🔦 WORKFLOW: Browsing lighting products across pages\n")

        search_term = "modern lamp"
        total_reviewed = 0
        best_rated_lamp = None
        best_rating = 0

        for page in range(1, 3):
            results = client.search_products(query=search_term, page=page)
            
            print(f"Page {page} of {results['total_pages']}:")
            print(f"  Showing {results['products_count']} products (Total available: {results['total_results']})\n")

            for idx, product in enumerate(results["products"][:3], 1):
                rating = product.get("rating", 0)
                if rating > best_rating:
                    best_rating = rating
                    best_rated_lamp = product

                print_product_summary(product, idx)
                total_reviewed += 1

            if page >= 2:
                break

        if best_rated_lamp:
            print(f"\n⭐ Best-rated lamp found: {best_rated_lamp['name']}")
            print(f"   Rating: {best_rated_lamp['rating']}★ ({best_rated_lamp['review_count']} reviews)")
            print(f"   URL: {best_rated_lamp['url']}")

        # Workflow 4: Sale items discovery
        print("\n" + "-" * 80)
        print("\n🏷️  WORKFLOW: Finding items on sale\n")

        search_term = "rug"
        results = client.search_products(query=search_term, page=1, sort_by="most_popular")

        sale_items = [p for p in results.get("products", []) if p.get("badge") == "Sale"]
        
        print(f"Searching '{search_term}' for sale items...\n")
        print(f"Found {len(sale_items)} items on sale out of {results['products_count']} shown\n")

        if sale_items:
            for idx, item in enumerate(sale_items[:3], 1):
                original = item.get("original_price", 0)
                sale = item.get("sale_price", original)
                savings = original - sale

                print(f"{idx}. {item['name']}")
                print(f"   Was: {format_price(original)} → Now: {format_price(sale)}")
                print(f"   You save: {format_price(savings)} ({(savings/original*100):.0f}% off)")
                print(f"   Rating: {item['rating']}★\n")

        print("=" * 80)
        print("✅ Workflow demonstration completed successfully!")
        print("=" * 80)

    except requests.RequestException as e:
        print(f"❌ API request failed: {e}")
    except KeyError as e:
        print(f"❌ Unexpected response format: Missing key {e}")
    except Exception as e:
        print(f"❌ An error occurred: {e}")


if __name__ == "__main__":
    main()