williamshomes.com APIwilliamshomes.com ↗

curl -X GET 'https://api.parse.bot/scraper/12ca6019-2528-4693-96c4-c70b23f44cb9/get_community_homes' \
  -H 'X-API-Key: $PARSE_API_KEY'

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

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


class ParseClient:
    """Client for interacting with the Williams Homes 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, reads from PARSE_API_KEY env var.
        """
        self.base_url = "https://api.parse.bot"
        self.scraper_id = "12ca6019-2528-4693-96c4-c70b23f44cb9"
        self.api_key = api_key or os.getenv("PARSE_API_KEY")

        if not self.api_key:
            raise ValueError("API key not provided and PARSE_API_KEY environment variable not set")

    def _call(self, endpoint: str, method: str = "POST", **params) -> Dict[str, Any]:
        """
        Make a request to the Parse API.

        Args:
            endpoint: API endpoint name
            method: HTTP method (GET or POST)
            **params: Query/body parameters

        Returns:
            Response JSON as dictionary
        """
        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 list_communities(self) -> Dict[str, Any]:
        """
        List all active Williams Homes communities.

        Returns:
            Dictionary containing list of communities and total count
        """
        return self._call("list_communities", method="GET")

    def get_community_homes(
        self,
        community_slug: str,
        state_code: str,
        city_slug: str
    ) -> Dict[str, Any]:
        """
        Retrieve all floor plans and available homes for a specific community.

        Args:
            community_slug: URL slug of the community (e.g., 'palmera')
            state_code: Two-letter lowercase US state code (e.g., 'ca')
            city_slug: URL slug of the city (e.g., 'camarillo')

        Returns:
            Dictionary containing community info, floor plans, and available homes
        """
        return self._call(
            "get_community_homes",
            method="GET",
            community_slug=community_slug,
            state_code=state_code,
            city_slug=city_slug
        )


def main():
    """Example workflow: explore communities and find homes in a specific community."""
    # Initialize client
    client = ParseClient()

    print("=" * 70)
    print("Williams Homes Community & Inventory Search")
    print("=" * 70)

    # Step 1: List all communities
    print("\n[Step 1] Fetching all Williams Homes communities...")
    communities_response = client.list_communities()

    if communities_response.get("status") != "success":
        print("Failed to fetch communities")
        return

    communities = communities_response["data"]["communities"]
    total_communities = communities_response["data"]["total"]

    print(f"Found {total_communities} communities:")
    print("-" * 70)

    for i, community in enumerate(communities[:5], 1):
        print(f"{i}. {community['community_name']} - {community['city']}, {community['state']}")

    # Step 2: Pick a community and get detailed inventory
    print("\n[Step 2] Selecting first community and fetching inventory...")
    selected_community = communities[0]

    print(f"\nSelected: {selected_community['community_name']}")
    print(f"Location: {selected_community['city']}, {selected_community['state']}")

    # Step 3: Get homes and plans for selected community
    homes_response = client.get_community_homes(
        community_slug=selected_community["community_slug"],
        state_code=selected_community["state_code"],
        city_slug=selected_community["city_slug"]
    )

    if homes_response.get("status") != "success":
        print("Failed to fetch community homes")
        return

    community_data = homes_response["data"]

    # Step 4: Display floor plans
    print("\n" + "=" * 70)
    print("FLOOR PLANS")
    print("=" * 70)

    plans = community_data.get("plans", [])
    print(f"Total Plans: {community_data.get('total_plans', 0)}\n")

    for plan in plans:
        print(f"Plan: {plan['plan_name']}")
        print(f"  Starting Price: ${plan['from_price']:,}")
        print(f"  Bedrooms: {plan['bedrooms']} | Bathrooms: {plan['bathrooms']}")
        print(f"  Square Footage: {plan['square_footage']}")
        print()

    # Step 5: Display available homes
    print("=" * 70)
    print("AVAILABLE HOMES")
    print("=" * 70)

    available_homes = community_data.get("available_homes", [])
    print(f"Total Available: {community_data.get('total_available_homes', 0)}\n")

    # Group homes by plan and show summary
    homes_by_plan = {}
    for home in available_homes:
        plan_name = home["plan_name"]
        if plan_name not in homes_by_plan:
            homes_by_plan[plan_name] = []
        homes_by_plan[plan_name].append(home)

    for plan_name, homes_in_plan in homes_by_plan.items():
        print(f"\n{plan_name} ({len(homes_in_plan)} available)")
        print("-" * 70)

        for home in homes_in_plan[:3]:  # Show first 3 homes per plan
            qmi_label = " [QMI Available]" if home.get("is_qmi") else ""
            print(f"  • {home['address']}")
            print(f"    Lot: {home['lot_number']} | Price: ${home['price']:,}{qmi_label}")
            print(f"    {home['bedrooms']} bed, {home['bathrooms']} bath | {home['square_footage']} sqft")

        if len(homes_in_plan) > 3:
            print(f"  ... and {len(homes_in_plan) - 3} more homes")

    # Step 6: Summary statistics
    print("\n" + "=" * 70)
    print("SUMMARY")
    print("=" * 70)

    qmi_count = sum(1 for h in available_homes if h.get("is_qmi"))
    avg_price = sum(h["price"] for h in available_homes) / len(available_homes) if available_homes else 0

    print(f"Total Available Homes: {len(available_homes)}")
    print(f"QMI Available: {qmi_count}")
    print(f"Average Price: ${avg_price:,.0f}")
    print(f"Price Range: ${min(h['price'] for h in available_homes):,} - ${max(h['price'] for h in available_homes):,}")

    # Find the most expensive and least expensive
    if available_homes:
        most_expensive = max(available_homes, key=lambda x: x["price"])
        least_expensive = min(available_homes, key=lambda x: x["price"])

        print(f"\nMost Expensive: {most_expensive['address']} (${most_expensive['price']:,})")
        print(f"Least Expensive: {least_expensive['address']} (${least_expensive['price']:,})")


if __name__ == "__main__":
    main()