Toll Brothers APItollbrothers.com ↗

"""
Toll Brothers Community Homes API Client

This module provides a Python client for the Parse API to retrieve home designs
and quick move-in homes from Toll Brothers community pages.

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

import os
import requests
from typing import Optional


class ParseClient:
    """Client for interacting with the Parse API."""
    
    def __init__(self, api_key: Optional[str] = None):
        """
        Initialize the Parse API client.
        
        Args:
            api_key: API key for authentication. If not provided, will use PARSE_API_KEY env var.
        """
        self.base_url = "https://api.parse.bot"
        self.scraper_id = "fc75b6ab-bf75-4c1e-bc61-c3631a2194e3"
        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:
        """
        Make a request to the Parse API.
        
        Args:
            endpoint: The API endpoint name
            method: HTTP method (GET or POST)
            **params: Parameters to pass to the endpoint
            
        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"
        }
        
        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 get_community_homes(self, community_url: str) -> dict:
        """
        Retrieve all home designs and quick move-in homes from a Toll Brothers community page.
        
        Args:
            community_url: The Toll Brothers community page URL path or full URL
                          e.g., '/luxury-homes-for-sale/California/Metro-Heights/Viewpoint'
        
        Returns:
            Dictionary containing community name, homes list, and total count
        """
        return self._call("get_community_homes", method="GET", community_url=community_url)


def main():
    """Main function demonstrating practical usage of the Toll Brothers API client."""
    
    # Initialize the client
    client = ParseClient()
    
    # List of Toll Brothers communities to analyze
    communities_to_search = [
        "/luxury-homes-for-sale/California/Metro-Heights/Viewpoint",
        "/luxury-homes-for-sale/Pennsylvania/Philadelphia-Area/Moorland",
    ]
    
    print("=" * 80)
    print("TOLL BROTHERS COMMUNITY HOMES ANALYSIS")
    print("=" * 80)
    
    all_homes = []
    total_communities = 0
    
    # Fetch homes from each community
    for community_url in communities_to_search:
        try:
            print(f"\nFetching homes from: {community_url}")
            response = client.get_community_homes(community_url)
            
            if response.get("status") == "success":
                community_data = response.get("data", {})
                community_name = community_data.get("community_name", "Unknown")
                homes = community_data.get("homes", [])
                total = community_data.get("total", 0)
                
                print(f"Community: {community_name}")
                print(f"Total homes found: {total}")
                
                total_communities += 1
                
                # Process each home
                for idx, home in enumerate(homes, 1):
                    all_homes.append(home)
                    
                    # Print home details
                    print(f"\n  Home {idx}:")
                    print(f"    Plan: {home.get('plan_name', 'N/A')}")
                    print(f"    Builder: {home.get('builder_name', 'N/A')}")
                    print(f"    Bedrooms: {home.get('bedrooms', 'N/A')}")
                    print(f"    Bathrooms: {home.get('bathrooms', 'N/A')}")
                    print(f"    Square Footage: {home.get('square_footage', 'N/A'):,}")
                    print(f"    Starting Price: ${home.get('starting_price', 0):,}")
                    
                    if home.get("is_qmi"):
                        qmi_price = home.get("qmi_price")
                        print(f"    Quick Move-In: YES - ${qmi_price:,}")
                    else:
                        print(f"    Quick Move-In: NO")
                    
                    print(f"    URL: {home.get('listing_url', 'N/A')}")
            else:
                print(f"Error: {response.get('message', 'Unknown error')}")
        
        except requests.exceptions.RequestException as e:
            print(f"Error fetching community {community_url}: {e}")
        except Exception as e:
            print(f"Unexpected error processing {community_url}: {e}")
    
    # Summary analysis
    print("\n" + "=" * 80)
    print("SUMMARY ANALYSIS")
    print("=" * 80)
    
    if all_homes:
        print(f"Total communities searched: {total_communities}")
        print(f"Total homes found: {len(all_homes)}")
        
        # Calculate statistics
        prices = [h.get("starting_price", 0) for h in all_homes if h.get("starting_price")]
        if prices:
            avg_price = sum(prices) / len(prices)
            min_price = min(prices)
            max_price = max(prices)
            print(f"\nPrice Statistics:")
            print(f"  Average Price: ${avg_price:,.0f}")
            print(f"  Minimum Price: ${min_price:,}")
            print(f"  Maximum Price: ${max_price:,}")
        
        # Count QMI homes
        qmi_homes = [h for h in all_homes if h.get("is_qmi")]
        print(f"\nQuick Move-In Homes: {len(qmi_homes)} out of {len(all_homes)}")
        
        # Bedroom distribution
        bedroom_counts = {}
        for home in all_homes:
            bedrooms = home.get("bedrooms", "Unknown")
            bedroom_counts[bedrooms] = bedroom_counts.get(bedrooms, 0) + 1
        
        print(f"\nBedroom Distribution:")
        for bedrooms, count in sorted(bedroom_counts.items()):
            print(f"  {bedrooms} bedrooms: {count} homes")
    else:
        print("No homes found in any community.")


if __name__ == "__main__":
    main()