sheahomes.com APIwww.sheahomes.com ↗

curl -X GET 'https://api.parse.bot/scraper/1f56327d-6cb2-4539-b7be-20c7915b8c61/get_community_plans' \
  -H 'X-API-Key: $PARSE_API_KEY'

"""
Shea Homes API Client

Access Shea Homes new construction community listings, floor plans, and quick move-in homes.
Get your API key from: https://parse.bot/settings
"""

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


class ParseClient:
    """Client for interacting with the Shea 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 = "1f56327d-6cb2-4539-b7be-20c7915b8c61"
        self.api_key = api_key or os.getenv("PARSE_API_KEY")

        if not self.api_key:
            raise ValueError(
                "API key is required. Pass it as an argument or set PARSE_API_KEY environment variable."
            )

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

        Args:
            endpoint: The endpoint name (e.g., 'list_communities', 'get_community_plans')
            method: HTTP method ('GET' or 'POST')
            **params: Parameters to send with the request

        Returns:
            The JSON response from the API

        Raises:
            requests.RequestException: If the API call 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.upper() == "GET":
                response = requests.get(url, headers=headers, params=params, timeout=30)
            elif method.upper() == "POST":
                payload = params if params else {}
                response = requests.post(url, headers=headers, json=payload, timeout=30)
            else:
                raise ValueError(f"Unsupported HTTP method: {method}")

            response.raise_for_status()
            return response.json()
        except requests.RequestException as e:
            print(f"API call failed: {e}")
            raise

    def list_communities(self, state: Optional[str] = None) -> Dict[str, Any]:
        """
        List all Shea Homes communities.

        Args:
            state: Optional two-letter US state abbreviation to filter communities.
                   Accepted values: AZ, CA, CO, FL, ID, NC, NV, SC, TX, VA, WA

        Returns:
            Response containing list of communities with summary information
        """
        params = {}
        if state:
            params["state"] = state.upper()

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

    def get_community_plans(self, community_url: str) -> Dict[str, Any]:
        """
        Retrieve all home plans and quick move-in homes for a specific community.

        Args:
            community_url: The community page URL path or full URL

        Returns:
            Response containing home plans and quick move-in listings
        """
        return self._call("get_community_plans", method="GET", community_url=community_url)


def print_community_summary(community: Dict[str, Any]) -> None:
    """Print a formatted summary of a community."""
    print(f"\n{'='*70}")
    print(f"Community: {community['name']} ({community['state']})")
    print(f"Location: {community['city']}")
    print(f"Home Type: {community['home_type']}")
    print(f"Starting Price: {community['from_price']}")
    print(f"Square Footage: {community['square_footage']} sq ft")
    print(f"Beds: {community['bedrooms']} | Baths: {community['bathrooms']}")


def print_home_plan(plan: Dict[str, Any], is_qmi: bool = False) -> None:
    """Print a formatted summary of a home plan."""
    status = "QMI" if is_qmi else "Plan"
    print(f"  • {plan['plan_name']} ({status})")
    print(f"    Size: {plan['square_footage']} sq ft | {plan['bedrooms']}B/{plan['bathrooms']}B")
    print(f"    Garage: {plan['garage']} | Stories: {plan['stories']}")
    print(f"    Price: {plan['from_price']} | Status: {plan['status']}")


def main():
    """Main example demonstrating practical usage of the Shea Homes API."""
    # Initialize client
    client = ParseClient()

    print("🏠 Shea Homes Community Explorer")
    print("=" * 70)

    # Step 1: List all communities in Arizona
    print("\n📍 Fetching all communities in Arizona...")
    communities_response = client.list_communities(state="AZ")

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

    communities = communities_response["data"]["communities"]
    total = communities_response["data"]["total"]
    print(f"✓ Found {total} communities in Arizona")

    # Step 2: Show first 3 communities
    print(f"\nShowing first 3 communities:")
    for community in communities[:3]:
        print_community_summary(community)

    # Step 3: Get detailed plans for the first community
    if communities:
        first_community = communities[0]
        community_name = first_community["name"]
        community_url = first_community["community_url"]

        print(f"\n\n📋 Fetching detailed plans for: {community_name}")
        print("-" * 70)

        plans_response = client.get_community_plans(community_url)

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

        plans_data = plans_response["data"]
        print(f"Builder: {plans_data['builder']}")
        print(f"Total Plans: {plans_data['total_plans']}")
        print(f"Quick Move-Ins Available: {plans_data['total_qmi']}")

        # Step 4: Display home plans
        if plans_data.get("home_plans"):
            print(f"\n📐 Home Plans ({len(plans_data['home_plans'])}):")
            for plan in plans_data["home_plans"][:3]:
                print_home_plan(plan, is_qmi=False)

        # Step 5: Display quick move-in homes
        if plans_data.get("quick_move_ins"):
            print(f"\n⚡ Quick Move-In Homes ({len(plans_data['quick_move_ins'])}):")
            for qmi in plans_data["quick_move_ins"][:3]:
                print_home_plan(qmi, is_qmi=True)

    # Step 6: Search for communities in multiple states
    print(f"\n\n🌎 Searching multiple states for Quick Move-In opportunities...")
    print("-" * 70)

    qmi_summary = {}
    states_to_search = ["TX", "FL", "NC"]

    for state in states_to_search:
        state_response = client.list_communities(state=state)
        if state_response.get("status") == "success":
            communities_in_state = state_response["data"]["communities"]
            qmi_summary[state] = len(communities_in_state)
            print(f"{state}: {len(communities_in_state)} communities found")

    print(f"\n✓ Exploration complete!")


if __name__ == "__main__":
    main()