Apartments APIapartments.com ↗

"""
Apartments.com Parse API Client
Search apartment listings, get property details, and find properties by management company.
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 Apartments.com 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.
            
        Raises:
            ValueError: If API key is not provided or found in environment.
        """
        self.base_url = "https://api.parse.bot"
        self.scraper_id = "623cb755-df0e-49e0-ae8b-63558585a1c2"
        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[str, Any]:
        """
        Make an API call to the Parse Bot endpoint.
        
        Args:
            endpoint: The endpoint name (e.g., 'search_properties')
            method: HTTP method ('GET' or 'POST')
            **params: Query/body parameters for the request
            
        Returns:
            Response JSON as dictionary
            
        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"
        }
        
        if method.upper() == "GET":
            response = requests.get(url, headers=headers, params=params)
        elif method.upper() == "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 search_properties(
        self,
        query: Optional[str] = None,
        lat: Optional[float] = None,
        lng: Optional[float] = None,
        radius: float = 5,
        min_rent: Optional[int] = None,
        max_rent: Optional[int] = None,
        min_beds: Optional[int] = None,
        max_beds: Optional[int] = None,
        min_sqft: Optional[int] = None,
        page: int = 1
    ) -> Dict[str, Any]:
        """
        Search for apartment listings by city, region, or coordinates.
        
        Either query or lat+lng must be provided.
        
        Args:
            query: Search query (e.g., 'Sunnyvale, CA', 'Boston, MA')
            lat: Latitude for coordinate-based search
            lng: Longitude for coordinate-based search
            radius: Search radius in miles (default: 5)
            min_rent: Minimum rent amount
            max_rent: Maximum rent amount
            min_beds: Minimum number of bedrooms
            max_beds: Maximum number of bedrooms
            min_sqft: Minimum square footage
            page: Page number for pagination (default: 1)
            
        Returns:
            Dictionary with 'total_count', 'page', 'next_page_url', and 'properties' list
        """
        params = {
            k: v for k, v in {
                "query": query,
                "lat": lat,
                "lng": lng,
                "radius": radius,
                "min_rent": min_rent,
                "max_rent": max_rent,
                "min_beds": min_beds,
                "max_beds": max_beds,
                "min_sqft": min_sqft,
                "page": page
            }.items() if v is not None
        }
        return self._call("search_properties", method="GET", **params)

    def get_property_details(self, url: str) -> Dict[str, Any]:
        """
        Get detailed information for a specific property listing.
        
        Args:
            url: Full URL or relative path of the property page
            
        Returns:
            Dictionary with property details including amenities, units, photos, reviews, etc.
        """
        return self._call("get_property_details", method="GET", url=url)

    def get_management_companies(
        self,
        company_name: str,
        market: Optional[str] = None
    ) -> Dict[str, Any]:
        """
        Search for properties managed by a specific company in a market.
        
        Args:
            company_name: Name of the management company (e.g., 'Bozzuto', 'Greystar')
            market: Market name (e.g., 'Boston'). If omitted, searches US-wide.
            
        Returns:
            Dictionary with 'total_count' and 'properties' list
        """
        params = {"company_name": company_name}
        if market:
            params["market"] = market
        return self._call("get_management_companies", method="GET", **params)


def extract_price(price_str: str) -> int:
    """Extract numeric value from price string."""
    try:
        return int(price_str.replace("$", "").replace(",", "").split("-")[0].strip())
    except (ValueError, IndexError):
        return 0


def main():
    """
    Practical workflow: Search for apartments, get details for promising results,
    and identify management companies to contact.
    """
    
    # Initialize client
    client = ParseClient()
    
    print("=" * 90)
    print("APARTMENT HUNTING WORKFLOW - PARSE API DEMO")
    print("=" * 90)
    
    # Step 1: Search for apartments with specific criteria
    print("\n[STEP 1] Searching for apartments...")
    print("         Location: San Francisco, CA")
    print("         Criteria: $3000-$5500/month, 1-2 bedrooms, min 600 sqft\n")
    
    search_results = client.search_properties(
        query="San Francisco, CA",
        min_rent=3000,
        max_rent=5500,
        min_beds=1,
        max_beds=2,
        min_sqft=600,
        page=1
    )
    
    total_found = search_results.get("total_count", 0)
    properties = search_results.get("properties", [])
    current_page = search_results.get("page", 1)
    next_page_url = search_results.get("next_page_url")
    
    print(f"✓ Found {total_found} properties matching criteria")
    print(f"  Displaying page {current_page} with {len(properties)} results")
    if next_page_url:
        print(f"  More results available on next page")
    
    if not properties:
        print("No properties found. Exiting.")
        return
    
    # Display search results summary
    print("\n" + "-" * 90)
    print("TOP SEARCH RESULTS")
    print("-" * 90)
    
    for idx, prop in enumerate(properties[:5], 1):
        listing_id = prop.get("listing_id", "N/A")
        name = prop.get("name", "Unknown")
        address = prop.get("address", "N/A")
        price_range = prop.get("price_range", "N/A")
        beds = prop.get("beds", "N/A")
        phone = prop.get("phone", "Contact for info")
        
        print(f"\n{idx}. {name}")
        print(f"   ID: {listing_id}")
        print(f"   Address: {address}")
        print(f"   Bedrooms: {beds} | Price: {price_range}")
        print(f"   Contact: {phone}")
    
    # Step 2: Get detailed information for top properties
    print("\n" + "=" * 90)
    print("DETAILED PROPERTY ANALYSIS")
    print("=" * 90)
    
    management_companies_found = {}
    detailed_properties = []
    
    for idx, prop in enumerate(properties[:3], 1):
        prop_url = prop.get("url")
        prop_name = prop.get("name", "Unknown Property")
        
        if not prop_url:
            print(f"\n[Property {idx}] ⚠ No URL available, skipping...")
            continue
        
        print(f"\n[Property {idx}] Fetching details for {prop_name}...")
        
        try:
            details = client.get_property_details(prop_url)
            detailed_properties.append(details)
            
            address = details.get("address", "N/A")
            management = details.get("management_company", "Not specified")
            neighborhood = details.get("neighborhood", "N/A")
            pricing_summary = details.get("pricing_summary", "N/A")
            has_ev = details.get("has_ev_charging", False)
            total_units = details.get("total_units_count", 0)
            
            print(f"  ✓ Details retrieved successfully")
            print(f"    Neighborhood: {neighborhood}")
            print(f"    Pricing: {pricing_summary}")
            print(f"    Management: {management}")
            print(f"    Total Units Available: {total_units}")
            print(f"    EV Charging: {'Yes ⚡' if has_ev else 'No'}")
            
            # Track management companies
            if management and management != "Not specified":
                if management not in management_companies_found:
                    management_companies_found[management] = []
                management_companies_found[management].append(prop_name)
            
            # Display amenities
            amenities = details.get("amenities", [])
            if amenities:
                display_amenities = amenities[:5]
                print(f"    Amenities: {', '.join(display_amenities)}", end="")
                if len(amenities) > 5:
                    print(f" + {len(amenities) - 5} more")
                else:
                    print()
            
            # Display pet policy
            pet_policy = details.get("pet_policy", [])
            if pet_policy:
                print(f"    Pet Policy: {', '.join(pet_policy)}")
            else:
                print(f"    Pet Policy: No information available")
            
            # Display unit details
            units = details.get("units", [])
            if units:
                sorted_units = sorted(
                    units,
                    key=lambda u: extract_price(u.get("price", "$0"))
                )
                
                print(f"    Sample Units (showing {min(3, len(sorted_units))} of {len(units)}):") 
                for unit in sorted_units[:3]:
                    beds = unit.get("beds", "?")
                    baths = unit.get("baths", "?")
                    price = unit.get("price", "Call for price")
                    sqft = unit.get("sqft", "?")
                    availability = unit.get("availability", "Contact")
                    
                    print(f"      • {beds}BR/{baths}BA - {price} ({sqft} sqft) - {availability}")
            
            # Display reviews
            reviews = details.get("reviews", [])
            if reviews and reviews[0].get("rating"):
                latest = reviews[0]
                rating = latest.get("rating", "N/A")
                title = latest.get("title", "No title")
                print(f"    Latest Review: ⭐ {rating}/5 - {title}")
            
        except Exception as e:
            print(f"  ✗ Error fetching details: {str(e)}")
    
    # Step 3: Search for properties by management company
    print("\n" + "=" * 90)
    print("MANAGEMENT COMPANY PORTFOLIO")
    print("=" * 90)
    
    if management_companies_found:
        print(f"\nFound {len(management_companies_found)} management company/companies:\n")
        
        for company_name in list(management_companies_found.keys())[:2]:
            properties_in_results = management_companies_found[company_name]
            print(f"[Company] {company_name}")
            print(f"  Properties in search results: {', '.join(properties_in_results)}")
            
            print(f"  Searching all {company_name} properties in San Francisco...")
            
            try:
                company_results = client.get_management_companies(
                    company_name=company_name,
                    market="San Francisco, CA"
                )
                
                total_company_props = company_results.get("total_count", 0)
                company_props = company_results.get("properties", [])
                
                print(f"  ✓ Found {total_company_props} total properties managed by {company_name}")
                
                if company_props:
                    print(f"  Showing {min(3, len(company_props))} additional properties:")
                    for prop in company_props[:3]:
                        prop_name = prop.get("name", "N/A")
                        prop_phone = prop.get("phone", "N/A")
                        print(f"    • {prop_name} - {prop_phone}")
                print()
                
            except Exception as e:
                print(f"  ✗ Error searching by company: {str(e)}\n")
    else:
        print("\nNo specific management companies found in detailed property results.")
        print("Try searching for individual companies using get_management_companies().")
    
    # Summary and recommendations
    print("=" * 90)
    print("SEARCH SUMMARY & RECOMMENDATIONS")
    print("=" * 90)
    
    print(f"\n📊 Statistics:")
    print(f"   • Total properties found: {total_found}")
    print(f"   • Properties analyzed in detail: {len(detailed_properties)}")
    print(f"   • Unique management companies: {len(management_companies_found)}")
    
    if detailed_properties:
        print(f"\n💡 Next Steps:")
        print(f"   1. Review the {len(detailed_properties)} detailed properties above")
        print(f"   2. Contact management companies directly for tours and current availability")
        print(f"   3. Use search_properties() with page=2 to see more listings")
        print(f"   4. Filter by management company to see their full portfolio")
    
    print(f"\n✓ Workflow complete!\n")


if __name__ == "__main__":
    main()