pulte.com APIwww.pulte.com ↗

curl -X GET 'https://api.parse.bot/scraper/e8ec1397-4efb-456e-8214-b6668c0e4f74/get_community_plans?community_id=211654' \
  -H 'X-API-Key: $PARSE_API_KEY'

"""
Pulte Homes API Client
Retrieve home floor plans and Quick Move-In inventory for Pulte Homes communities.
Get your API key from: https://parse.bot/settings
"""

import os
import requests
from typing import Any, Optional


class ParseClient:
    """Client for interacting with the Pulte Homes API via Parse."""

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

        Args:
            api_key: API key for authentication. If not provided, uses PARSE_API_KEY env var.
        """
        self.base_url = "https://api.parse.bot"
        self.scraper_id = "e8ec1397-4efb-456e-8214-b6668c0e4f74"
        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
    ) -> dict[str, Any]:
        """
        Make a request to the Parse API.

        Args:
            endpoint: The endpoint name (e.g., 'get_community_plans')
            method: HTTP method ('GET' or 'POST')
            **params: Query/body parameters for the request

        Returns:
            Response JSON as a dictionary
        """
        url = f"{self.base_url}/scraper/{self.scraper_id}/{endpoint}"
        headers = {"X-API-Key": self.api_key, "Content-Type": "application/json"}

        if method.upper() == "GET":
            response = requests.get(url, headers=headers, params=params, timeout=30)
        elif method.upper() == "POST":
            response = requests.post(url, headers=headers, json=params, timeout=30)
        else:
            raise ValueError(f"Unsupported HTTP method: {method}")

        response.raise_for_status()
        return response.json()

    def get_community_plans(self, community_id: str) -> dict[str, Any]:
        """
        Retrieve all home floor plans and QMI inventory homes for a Pulte community.

        Args:
            community_id: Numeric Pulte community identifier from the community page URL.

        Returns:
            Dictionary containing community_id, community_name, home_plans, qmi_homes,
            total_plans, and total_qmi.
        """
        return self._call("get_community_plans", method="GET", community_id=community_id)


def main():
    """Main function demonstrating a practical workflow with the Pulte Homes API."""

    # Initialize the client
    client = ParseClient()

    # Define a list of community IDs to check
    community_ids = ["211654"]

    print("=" * 70)
    print("PULTE HOMES INVENTORY SEARCH")
    print("=" * 70)

    all_communities_data = []

    for community_id in community_ids:
        try:
            print(f"\nFetching data for community ID: {community_id}")
            print("-" * 70)

            # Get community plans and QMI inventory
            response = client.get_community_plans(community_id)

            # Verify successful response
            if response.get("status") != "success":
                print(f"Error: API returned status '{response.get('status')}'")
                continue

            data = response.get("data", {})
            all_communities_data.append(data)

            # Display community information
            print(f"Community: {data.get('community_name')}")
            print(f"Total Plans: {data.get('total_plans')}")
            print(f"Total QMI Homes: {data.get('total_qmi')}")

            # Process and display home plans
            home_plans = data.get("home_plans", [])
            if home_plans:
                print(f"\n  Available Floor Plans ({len(home_plans)}):")
                print("  " + "-" * 66)

                for idx, plan in enumerate(home_plans, 1):
                    print(f"\n    {idx}. {plan.get('plan_name', 'Unknown')}")
                    print(f"       Plan ID: {plan.get('plan_id')}")
                    print(f"       Square Feet: {plan.get('square_feet'):,}")
                    print(
                        f"       Bedrooms: {plan.get('bedrooms')} | Bathrooms: {plan.get('bathrooms')}"
                    )
                    price = plan.get("price")
                    print(
                        f"       Price: {f'${price:,.0f}' if price else 'Contact for pricing'}"
                    )
                    print(f"       URL: {plan.get('listing_url')}")

            # Process QMI homes
            qmi_homes = data.get("qmi_homes", [])
            if qmi_homes:
                print(f"\n  Quick Move-In (QMI) Homes ({len(qmi_homes)}):")
                print("  " + "-" * 66)

                for idx, home in enumerate(qmi_homes, 1):
                    print(f"\n    {idx}. {home.get('home_name', 'QMI Home')}")
                    print(f"       Home ID: {home.get('home_id')}")
                    print(
                        f"       Bedrooms: {home.get('bedrooms')} | Bathrooms: {home.get('bathrooms')}"
                    )
                    print(f"       Status: {home.get('status')}")
            else:
                print("\n  No Quick Move-In homes currently available.")

        except requests.exceptions.RequestException as e:
            print(f"Error fetching community {community_id}: {e}")
        except Exception as e:
            print(f"Unexpected error for community {community_id}: {e}")

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

    total_communities = len(all_communities_data)
    total_all_plans = sum(c.get("total_plans", 0) for c in all_communities_data)
    total_all_qmi = sum(c.get("total_qmi", 0) for c in all_communities_data)

    print(f"Communities Analyzed: {total_communities}")
    print(f"Total Floor Plans: {total_all_plans}")
    print(f"Total QMI Homes Available: {total_all_qmi}")

    if total_all_plans > 0:
        print("\nTop opportunities for buyers:")
        all_plans = []
        for community in all_communities_data:
            for plan in community.get("home_plans", []):
                all_plans.append(
                    {
                        "community": community.get("community_name"),
                        "plan_name": plan.get("plan_name"),
                        "bedrooms": plan.get("bedrooms"),
                        "bathrooms": plan.get("bathrooms"),
                        "sqft": plan.get("square_feet"),
                    }
                )

        # Group by bedroom count
        bedrooms_groups = {}
        for plan in all_plans:
            bed_count = plan["bedrooms"]
            if bed_count not in bedrooms_groups:
                bedrooms_groups[bed_count] = []
            bedrooms_groups[bed_count].append(plan)

        for bed_count in sorted(bedrooms_groups.keys()):
            plans = bedrooms_groups[bed_count]
            print(
                f"\n  {bed_count}-Bedroom Plans: {len(plans)} available"
                if bed_count
                else f"\n  Plans: {len(plans)} available"
            )

    print("\n" + "=" * 70)


if __name__ == "__main__":
    main()