Finish Line APIfinishline.com ↗

"""
Finish Line API Parser Client

A practical example for extracting product data, inventory, and release information
from Finish Line using the Parse API.

Get your API key from: https://parse.bot/settings
"""

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


class ParseClient:
    """Client for interacting with the Finish Line Parse API."""

    def __init__(self, api_key: Optional[str] = None):
        """
        Initialize the Parse client.

        Args:
            api_key: API key for authentication. Falls back to PARSE_API_KEY env var.
        """
        self.base_url = "https://api.parse.bot"
        self.scraper_id = "de510481-7bb5-4661-9ec5-2884b255e511"
        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) -> 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 or body parameters

        Returns:
            JSON response from the API
        """
        url = f"{self.base_url}/scraper/{self.scraper_id}/{endpoint}"
        headers = {
            "X-API-Key": self.api_key,
            "Content-Type": "application/json"
        }

        try:
            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()
        except requests.exceptions.RequestException as e:
            print(f"API Error: {e}")
            raise

    def search_products(
        self,
        query: str,
        page: int = 0,
        limit: int = 20
    ) -> Dict[str, Any]:
        """
        Search for products by keyword.

        Args:
            query: Search keyword (e.g., 'Jordan', 'Nike')
            page: Page number for pagination (default: 0)
            limit: Max results to return (default: 20)

        Returns:
            Dictionary with hits, total_hits, total_pages, and page
        """
        return self._call("search_products", method="GET", query=query, page=page, limit=limit)

    def get_product_details(self, url: str) -> Dict[str, Any]:
        """
        Fetch detailed product information from a PDP URL.

        Args:
            url: Full URL of the product detail page

        Returns:
            Dictionary with product details including name, price, sizes, colors, description
        """
        return self._call("get_product_details", method="GET", url=url)

    def get_search_suggestions(self, query: str) -> List[Dict[str, Any]]:
        """
        Get search autocomplete suggestions and product previews.

        Args:
            query: Partial search term

        Returns:
            List of suggestions with name, image, and url
        """
        return self._call("get_search_suggestions", method="GET", query=query)

    def get_sneaker_releases(self) -> Dict[str, Any]:
        """
        Retrieve upcoming sneaker release dates and details.

        Returns:
            Dictionary with releases array containing upcoming releases
        """
        return self._call("get_sneaker_releases", method="GET")

    def get_store_locator(
        self,
        query: Optional[str] = None,
        lat: Optional[str] = None,
        lng: Optional[str] = None
    ) -> List[Dict[str, Any]]:
        """
        Search for physical store locations by city name or geolocation.

        Args:
            query: City name to search near
            lat: Latitude for geolocation search
            lng: Longitude for geolocation search

        Returns:
            List of store locations with details
        """
        params = {}
        if query:
            params["query"] = query
        if lat:
            params["lat"] = lat
        if lng:
            params["lng"] = lng

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

    def get_product_listing_page(
        self,
        category_slug: str,
        page: int = 0,
        limit: int = 20
    ) -> Dict[str, Any]:
        """
        Browse products by category.

        Args:
            category_slug: Category identifier (e.g., 'mens-shoes', 'womens-shoes')
            page: Page number for pagination (default: 0)
            limit: Max results to return (default: 20)

        Returns:
            Dictionary with hits array and total count
        """
        return self._call(
            "get_product_listing_page",
            method="GET",
            category_slug=category_slug,
            page=page,
            limit=limit
        )


def main():
    """Demonstrate a practical workflow using the Finish Line API."""
    
    # Initialize the client
    client = ParseClient()
    print("✓ Connected to Finish Line API Parser\n")

    # Workflow: Search for sneakers, get details, find local stores, check releases
    print("=" * 80)
    print("WORKFLOW: Sneaker Search → Inventory Check → Store Locator → Release Calendar")
    print("=" * 80)

    # Step 1: Search for Jordan shoes
    print("\n[1/5] Searching for 'Jordan basketball shoes'...")
    search_results = client.search_products(query="Jordan basketball shoes", limit=5)
    
    if not search_results.get("hits"):
        print("No results found.")
        return

    total_hits = search_results.get("total_hits", 0)
    total_pages = search_results.get("total_pages", 0)
    current_page = search_results.get("page", 0)
    
    print(f"✓ Found {total_hits} results across {total_pages} pages")
    print(f"  Showing page {current_page} with {len(search_results['hits'])} items\n")

    # Step 2: Analyze top 2 products with detailed inventory info
    print("[2/5] Fetching inventory and detailed specs for top 2 products...\n")
    selected_products = []

    for idx, product in enumerate(search_results["hits"][:2], 1):
        product_name = product.get("name", "Unknown")
        product_url = product.get("url")
        product_price = product.get("price", "N/A")
        brand = product.get("brand", "Unknown")
        color = product.get("color", "Multiple")
        rating = product.get("rating", "N/A")
        review_count = product.get("review_count", 0)
        style_code = product.get("style_code", "")

        print(f"  Product {idx}: {product_name}")
        print(f"    Brand: {brand} | Style: {style_code}")
        print(f"    Price: ${product_price} | Color: {color}")
        print(f"    Rating: {rating}/5 ({review_count} reviews)")

        if product_url:
            try:
                details = client.get_product_details(url=product_url)
                selected_products.append({
                    "name": product_name,
                    "price": product_price,
                    "url": product_url,
                    "details": details
                })

                # Display size availability
                if details.get("sizes"):
                    sizes_data = details["sizes"]
                    in_stock = [s.get("size") for s in sizes_data if s.get("stock_level") != "OOS"]
                    print(f"    ✓ Available sizes: {', '.join(in_stock[:10])}")
                    
                    # Count stock levels
                    stock_summary = {}
                    for size in sizes_data:
                        level = size.get("stock_level", "UNKNOWN")
                        stock_summary[level] = stock_summary.get(level, 0) + 1
                    print(f"    Stock levels: {', '.join([f'{k}={v}' for k, v in stock_summary.items()])}")
                
                # Display color options
                if details.get("colors"):
                    colors_list = [c.get("name") for c in details["colors"][:3]]
                    print(f"    ✓ Colors: {', '.join(colors_list)}")
                        
            except Exception as e:
                print(f"    ✗ Could not fetch details: {str(e)}")
            
            print()

    # Step 3: Get related product suggestions
    print("[3/5] Getting search suggestions for 'Nike Air'...\n")
    suggestions = client.get_search_suggestions(query="Nike Air")
    
    if suggestions and isinstance(suggestions, list):
        print(f"✓ Found {len(suggestions)} related product suggestions:")
        for suggestion in suggestions[:3]:
            sugg_name = suggestion.get("name", "Unknown")
            print(f"  • {sugg_name}")
        print()

    # Step 4: Find nearby stores in Chicago
    print("[4/5] Locating Finish Line stores in Chicago...\n")
    stores = client.get_store_locator(query="Chicago")
    
    if stores and isinstance(stores, list):
        print(f"✓ Found {len(stores)} store(s):\n")
        for store in stores[:3]:
            store_name = store.get("name", "Store")
            city = store.get("city", "Unknown")
            state = store.get("state", "")
            zip_code = store.get("zip", "")
            store_id = store.get("store_id", "")
            
            print(f"  Store ID: {store_id} | {store_name}")
            print(f"  Location: {city}, {state} {zip_code}\n")
    else:
        print("No stores found in that area.\n")

    # Step 5: Check upcoming sneaker releases
    print("[5/5] Checking upcoming sneaker releases...\n")
    releases = client.get_sneaker_releases()
    
    if releases and releases.get("releases"):
        total_releases = releases.get("total", 0)
        print(f"✓ Found {total_releases} total releases in calendar\n")
        
        # Show upcoming (not yet released) releases
        upcoming = [r for r in releases["releases"] if not r.get("released", False)][:4]
        
        if upcoming:
            print(f"Next {len(upcoming)} upcoming releases:\n")
            for release in upcoming:
                rel_name = release.get("name", "Unknown")
                rel_date = release.get("release_date", "TBA")
                rel_price = release.get("price", "N/A")
                brand = release.get("brand", "Unknown")
                color = release.get("color", "Multiple")
                exclusive = release.get("exclusive_access", False)
                
                # Format release date
                try:
                    dt = datetime.fromisoformat(rel_date.replace("Z", "+00:00"))
                    formatted_date = dt.strftime("%B %d, %Y at %I:%M %p")
                except (ValueError, AttributeError):
                    formatted_date = rel_date
                
                exclusive_label = " [EXCLUSIVE ACCESS]" if exclusive else ""
                print(f"  • {brand} {rel_name}{exclusive_label}")
                print(f"    Release: {formatted_date}")
                print(f"    Price: ${rel_price} | Color: {color}\n")
        else:
            print("No upcoming releases scheduled.\n")

    # Step 6: Browse a category
    print("[Bonus] Browsing 'mens-shoes' category...\n")
    category_results = client.get_product_listing_page(category_slug="mens-shoes", limit=3)
    
    if category_results and category_results.get("hits"):
        total = category_results.get("total", 0)
        page_count = category_results.get("total_pages", 0)
        print(f"✓ Found {total} men's shoes across {page_count} pages\n")
        print("Sample items from category:\n")
        
        for item in category_results["hits"][:3]:
            item_name = item.get("name", "Unknown")
            item_price = item.get("price", "N/A")
            item_brand = item.get("brand", "Unknown")
            item_rating = item.get("rating", "N/A")
            print(f"  • {item_brand} {item_name}")
            print(f"    ${item_price} | Rating: {item_rating}/5\n")

    print("=" * 80)
    print("✓ Workflow completed successfully!")
    print("=" * 80)


if __name__ == "__main__":
    main()