Portal Inmobiliario APIportalinmobiliario.com ↗

"""
Portal Inmobiliario API Client

A Python client for scraping property listings from Portal Inmobiliario (Chile's leading real estate platform).

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

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


class ParseClient:
    """Client for the Portal Inmobiliario Parse API."""
    
    def __init__(self, api_key: Optional[str] = None):
        """
        Initialize the Parse API client.
        
        Args:
            api_key: Optional API key. If not provided, uses PARSE_API_KEY environment variable.
        """
        self.base_url = "https://api.parse.bot"
        self.scraper_id = "f3817e67-e705-4258-a9a6-8fa44f79e1e1"
        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 service.
        
        Args:
            endpoint: The endpoint name to call
            method: HTTP method (GET or POST)
            **params: Query or body parameters
            
        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 == "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 search_listings(
        self,
        property_type: str = "departamento",
        operation: str = "venta",
        location: str = "vitacura-metropolitana",
        page: int = 1
    ) -> Dict[str, Any]:
        """
        Search property listings by type, operation, and location.
        
        Args:
            property_type: Property type slug (e.g., departamento, casa, oficina, terreno, local-comercial)
            operation: Operation type: venta (sale) or arriendo (rent)
            location: Location slug (e.g., vitacura-metropolitana, santiago-metropolitana)
            page: Page number (1-based). Each page returns up to 48 listings.
            
        Returns:
            Dictionary containing total count, current page, listings count, and listings array
        """
        return self._call(
            "search_listings",
            method="GET",
            property_type=property_type,
            operation=operation,
            location=location,
            page=page
        )
    
    def get_listing_detail(
        self,
        listing_url: Optional[str] = None,
        listing_id: Optional[str] = None
    ) -> Dict[str, Any]:
        """
        Get detailed information for a specific property listing.
        
        Args:
            listing_url: Full URL of the listing (from search results)
            listing_id: MLC listing ID (e.g., MLC-1742229599)
            
        Returns:
            Dictionary containing detailed listing information
            
        Raises:
            ValueError: If neither listing_url nor listing_id is provided
        """
        if not listing_url and not listing_id:
            raise ValueError("Either listing_url or listing_id must be provided")
        
        params = {}
        if listing_url:
            params["listing_url"] = listing_url
        if listing_id:
            params["listing_id"] = listing_id
        
        return self._call("get_listing_detail", method="GET", **params)


def format_listing_summary(listing: Dict[str, Any]) -> str:
    """Format a listing for display."""
    price_display = f"{listing.get('price_prefix', '')} {listing['price']}".strip()
    return (
        f"  {listing['title']}\n"
        f"    Price: {price_display} {listing['currency']}\n"
        f"    Rooms: {listing['rooms']} | Bathrooms: {listing['bathrooms']}\n"
        f"    Area: {listing['area_m2']} m² ({listing['area_type']})\n"
        f"    Location: {listing['location']}\n"
        f"    ID: {listing['id']}\n"
    )


def format_listing_detail(detail: Dict[str, Any]) -> str:
    """Format detailed listing information for display."""
    price_display = f"{detail.get('price_prefix', '')} {detail['price']}".strip()
    output = (
        f"Title: {detail['title']}\n"
        f"ID: {detail['id']}\n"
        f"Price: {price_display} {detail['currency']}\n"
        f"Rooms: {detail['rooms']}\n"
        f"Bathrooms: {detail['bathrooms']}\n"
        f"Area: {detail['area_m2']} m²\n"
        f"Location: {detail['location']}\n"
    )
    
    if detail.get('attributes'):
        output += "\nAdditional Attributes:\n"
        for attr_name, attr_value in detail['attributes'].items():
            output += f"  {attr_name}: {attr_value}\n"
    
    return output


if __name__ == "__main__":
    # Initialize the client
    client = ParseClient()
    
    print("=" * 80)
    print("Portal Inmobiliario Property Market Analysis")
    print("=" * 80)
    
    # WORKFLOW: Search apartments for sale, analyze top listings, get details
    print("\n[STEP 1] Searching for apartments (departamentos) for sale in Vitacura...")
    search_results = client.search_listings(
        property_type="departamento",
        operation="venta",
        location="vitacura-metropolitana",
        page=1
    )
    
    total_listings = search_results['data']['total']
    listings = search_results['data']['listings']
    
    print(f"✓ Found {total_listings} total listings in Vitacura")
    print(f"✓ Showing {len(listings)} listings on page 1\n")
    
    # Display summary of first 5 listings
    print("[STEP 2] Top 5 listings summary:\n")
    top_listings = listings[:5]
    for i, listing in enumerate(top_listings, 1):
        print(f"{i}. {format_listing_summary(listing)}")
    
    # Get detailed information for top 3 listings
    print("\n" + "=" * 80)
    print("[STEP 3] Fetching detailed information for top 3 listings...")
    print("=" * 80)
    
    detailed_listings = []
    for i, listing in enumerate(top_listings[:3], 1):
        listing_id = listing['id']
        print(f"\n[{i}/3] Fetching details for: {listing['title']}...")
        
        try:
            detail = client.get_listing_detail(listing_id=listing_id)
            detailed_listings.append(detail['data'])
            print(f"✓ Details retrieved successfully\n")
            print(format_listing_detail(detail['data']))
        except Exception as e:
            print(f"✗ Error fetching details: {e}\n")
    
    # Price comparison analysis
    print("\n" + "=" * 80)
    print("[STEP 4] Price Comparison Analysis")
    print("=" * 80)
    
    uf_prices = []
    clp_prices = []
    
    for detail in detailed_listings:
        if detail['currency'] == 'UF':
            uf_prices.append(detail['price'])
        else:
            clp_prices.append(detail['price'])
    
    if uf_prices:
        avg_uf = sum(uf_prices) / len(uf_prices)
        print(f"\nAverage price (UF): {avg_uf:,.2f}")
        print(f"Price range (UF): {min(uf_prices):,.2f} - {max(uf_prices):,.2f}")
    
    if clp_prices:
        avg_clp = sum(clp_prices) / len(clp_prices)
        print(f"\nAverage price (CLP): {avg_clp:,.2f}")
        print(f"Price range (CLP): {min(clp_prices):,.2f} - {max(clp_prices):,.2f}")
    
    # WORKFLOW: Search rental market in a different location
    print("\n" + "=" * 80)
    print("[STEP 5] Searching rental market in Las Condes...")
    print("=" * 80)
    
    rental_results = client.search_listings(
        property_type="casa",
        operation="arriendo",
        location="las-condes-metropolitana",
        page=1
    )
    
    rental_listings = rental_results['data']['listings']
    print(f"✓ Found {rental_results['data']['total']} total rental listings")
    print(f"✓ Showing {len(rental_listings)} listings on page 1\n")
    
    if rental_listings:
        print("First 3 rental houses available:\n")
        for i, listing in enumerate(rental_listings[:3], 1):
            print(f"{i}. {format_listing_summary(listing)}")
    
    # Get details for a rental property
    if rental_listings:
        first_rental = rental_listings[0]
        print("\n" + "=" * 80)
        print(f"[STEP 6] Detailed view of: {first_rental['title']}")
        print("=" * 80 + "\n")
        
        try:
            rental_detail = client.get_listing_detail(listing_id=first_rental['id'])
            print(format_listing_detail(rental_detail['data']))
        except Exception as e:
            print(f"Error fetching rental details: {e}")
    
    print("\n" + "=" * 80)
    print("Analysis complete!")
    print("=" * 80)