richmondamerican.com APIwww.richmondamerican.com ↗

curl -X GET 'https://api.parse.bot/scraper/42c19201-00d7-4cd7-a551-37d7fe4f48ca/get_community_listings?community_url=%2Fcalifornia%2Flos-angeles-new-homes%2Fvalencia%2Fesprit-at-valencia%2F' \
  -H 'X-API-Key: $PARSE_API_KEY'

"""
Richmond American Homes API Client
Extracts floor plan and move-in ready home listings from Richmond American Homes communities.
Get your API key from: https://parse.bot/settings
"""

import os
import requests
from typing import Optional, Any
from dataclasses import dataclass


@dataclass
class ListingInfo:
    """Represents a single home listing."""
    plan_name: str
    listing_type: str
    community_name: str
    builder_name: str
    listing_url: str
    lot_id: Optional[str] = None
    square_footage: Optional[int] = None
    bedrooms: Optional[int] = None
    bathrooms: Optional[int] = None


class ParseClient:
    """Client for Richmond American Homes API via Parse.bot"""
    
    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 = "42c19201-00d7-4cd7-a551-37d7fe4f48ca"
        self.api_key = api_key or os.getenv("PARSE_API_KEY")
        
        if not self.api_key:
            raise ValueError("API key required. Pass api_key or set PARSE_API_KEY environment variable.")
    
    def _call(self, endpoint: str, method: str = "POST", **params) -> dict[str, Any]:
        """
        Make an API request to Parse.bot.
        
        Args:
            endpoint: The endpoint name (e.g., "get_community_listings")
            method: HTTP method ("GET" or "POST")
            **params: Query/body parameters
            
        Returns:
            Response JSON as dictionary
            
        Raises:
            requests.RequestException: If the API request fails
        """
        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, timeout=30)
            else:  # POST
                response = requests.post(url, headers=headers, json=params, timeout=30)
            
            response.raise_for_status()
            return response.json()
        except requests.RequestException as e:
            raise Exception(f"API request failed: {str(e)}")
    
    def get_community_listings(self, community_url: str) -> dict[str, Any]:
        """
        Get floor plans and move-in ready homes for a Richmond American Homes community.
        
        Args:
            community_url: URL path of the community (e.g., "/california/los-angeles-new-homes/valencia/esprit-at-valencia/")
            
        Returns:
            Dictionary containing community info and listings
        """
        return self._call(
            "get_community_listings",
            method="GET",
            community_url=community_url
        )


def parse_listings(response: dict) -> list[ListingInfo]:
    """
    Parse API response and convert to ListingInfo objects.
    
    Args:
        response: API response dictionary
        
    Returns:
        List of ListingInfo objects
    """
    listings = []
    
    if response.get("status") != "success" or not response.get("data"):
        return listings
    
    data = response["data"]
    for listing in data.get("listings", []):
        listings.append(ListingInfo(
            plan_name=listing.get("plan_name", "Unknown"),
            listing_type=listing.get("type", "unknown"),
            community_name=listing.get("community_name", ""),
            builder_name=listing.get("builder_name", ""),
            listing_url=listing.get("listing_url", ""),
            lot_id=listing.get("lot_id"),
            square_footage=listing.get("square_footage"),
            bedrooms=listing.get("bedrooms"),
            bathrooms=listing.get("bathrooms")
        ))
    
    return listings


if __name__ == "__main__":
    # Initialize client
    client = ParseClient()
    
    # Community URLs to check
    communities = [
        "/california/los-angeles-new-homes/valencia/esprit-at-valencia/",
        "/colorado/denver-new-homes/castle-rock/ascent-at-castle-rock/",
    ]
    
    all_listings = []
    
    print("=" * 70)
    print("Richmond American Homes Listings Inventory")
    print("=" * 70)
    
    # Fetch listings for each community
    for community_url in communities:
        print(f"\nFetching listings for: {community_url}")
        print("-" * 70)
        
        try:
            response = client.get_community_listings(community_url)
            
            if response.get("status") != "success":
                print(f"  ⚠ Failed to fetch: {response.get('error', 'Unknown error')}")
                continue
            
            data = response.get("data", {})
            community_name = data.get("community_name", "Unknown")
            builder_name = data.get("builder_name", "Richmond American Homes")
            total_listings = data.get("total_listings", 0)
            
            print(f"  Builder: {builder_name}")
            print(f"  Community: {community_name}")
            print(f"  Total Listings: {total_listings}")
            
            # Parse listings
            listings = parse_listings(response)
            all_listings.extend(listings)
            
            # Group by plan and type
            plan_summary = {}
            for listing in listings:
                key = f"{listing.plan_name} ({listing.listing_type})"
                plan_summary[key] = plan_summary.get(key, 0) + 1
            
            print("\n  Plan Summary:")
            for plan_type, count in sorted(plan_summary.items()):
                plan_name, lst_type = plan_type.rsplit(" (", 1)
                lst_type = lst_type.rstrip(")")
                type_label = "Move-In Ready" if lst_type == "move_in_ready" else "Plan to Build"
                print(f"    • {plan_name}: {count} {type_label}")
            
            # Show example move-in ready homes
            qmi_homes = [l for l in listings if l.listing_type == "move_in_ready"]
            if qmi_homes:
                print("\n  Sample Move-In Ready Homes:")
                for home in qmi_homes[:3]:
                    lot_info = f" (Lot: {home.lot_id})" if home.lot_id else ""
                    print(f"    • {home.plan_name}{lot_info}")
                if len(qmi_homes) > 3:
                    print(f"    ... and {len(qmi_homes) - 3} more")
        
        except Exception as e:
            print(f"  ❌ Error: {str(e)}")
    
    # Summary statistics
    print("\n" + "=" * 70)
    print("SUMMARY")
    print("=" * 70)
    print(f"Communities checked: {len(communities)}")
    print(f"Total listings found: {len(all_listings)}")
    
    plan_to_build = [l for l in all_listings if l.listing_type == "plan_to_build"]
    move_in_ready = [l for l in all_listings if l.listing_type == "move_in_ready"]
    
    print(f"  • Plans to Build: {len(plan_to_build)}")
    print(f"  • Move-In Ready: {len(move_in_ready)}")
    
    # Unique plans
    unique_plans = set(l.plan_name for l in all_listings)
    print(f"\nUnique floor plans discovered: {len(unique_plans)}")
    for plan in sorted(unique_plans)[:5]:
        count = sum(1 for l in all_listings if l.plan_name == plan)
        print(f"  • {plan}: {count} listings")
    
    if len(unique_plans) > 5:
        print(f"  ... and {len(unique_plans) - 5} more plans")