zillow_api.py

"""
Zillow Scraper API - Python Client
Powered by RealtyAPI.io

A comprehensive Python wrapper for the Zillow Scraper API.
Supports property data, search, agent lookup, market analytics,
skip tracing, and more.
"""

import requests
from config import BASE_URL, get_headers


class ZillowAPI:
    """
    Zillow Scraper API client for real estate data extraction.

    Provides access to Zillow property data, listings, agent info,
    market analytics, and skip tracing via the RealtyAPI.io platform.

    Get your API key at: https://www.realtyapi.io
    """

    def __init__(self, api_key):
        self.api_key = api_key
        self.headers = get_headers(api_key)
        self.base_url = BASE_URL

    def _get(self, endpoint, params=None):
        """Make a GET request and return the JSON response."""
        url = f"{self.base_url}{endpoint}"
        # Remove None values from params
        if params:
            params = {k: v for k, v in params.items() if v is not None}
        try:
            response = requests.get(url, headers=self.headers, params=params, timeout=30)
            response.raise_for_status()
            return response.json()
        except requests.exceptions.HTTPError as e:
            if response.status_code == 401:
                print("Error: Invalid API key. Get your key at https://www.realtyapi.io")
            elif response.status_code == 429:
                print("Error: Rate limit exceeded. Check your plan at https://www.realtyapi.io")
            else:
                print(f"HTTP Error: {e}")
            return {"error": str(e), "status_code": response.status_code}
        except requests.exceptions.RequestException as e:
            print(f"Request Error: {e}")
            return {"error": str(e)}

    # ─────────────────────────────────────────────
    # 1. Property Info - Advanced
    # ─────────────────────────────────────────────

    def get_property_by_address(self, address):
        """
        Get detailed property data by address.

        Args:
            address (str): Full property address
                Example: "1875 AVONDALE Circle, Jacksonville, FL 32205"

        Returns:
            dict: Comprehensive property data including zestimate, details, etc.
        """
        return self._get("/pro/byaddress", {"propertyaddress": address})

    def get_property_by_zpid(self, zpid):
        """
        Get detailed property data by Zillow Property ID (ZPID).

        Args:
            zpid (str): Zillow Property ID
                Example: "44471319"

        Returns:
            dict: Comprehensive property data
        """
        return self._get("/pro/byzpid", {"zpid": zpid})

    def get_property_by_url(self, url):
        """
        Get detailed property data by Zillow URL.
        For URLs with ZPIDs only (not apartment /b/ URLs).

        Args:
            url (str): Zillow property URL
                Example: "https://www.zillow.com/homedetails/2762-Downing-St-Jacksonville-FL-32205/44471319_zpid/"

        Returns:
            dict: Comprehensive property data
        """
        return self._get("/pro/byurl", {"url": url})

    # ─────────────────────────────────────────────
    # 2. Search Zillow
    # ─────────────────────────────────────────────

    def search_by_address(self, location, listing_status="For_Sale", page=1,
                          sort_order=None, home_type=None, bed_min=None,
                          bed_max=None, bathrooms=None, list_price_range=None,
                          square_feet_range=None, lot_size_range=None,
                          year_built_range=None, days_on_zillow=None,
                          sold_in_last=None, keywords=None, max_hoa=None,
                          parking_spots=None, have_garage=None,
                          must_have_basement=None, single_story_only=None,
                          listing_type=None, property_status=None,
                          pets=None, other_amenities=None, view=None):
        """
        Search Zillow listings by address, city, neighborhood, or ZIP code.
        Supports up to 5 multi-location inputs separated by semicolons.

        Args:
            location (str): Address, city, neighborhood, or ZIP code.
                Multi-input: "New York, NY; Seattle, WA; 78006"
            listing_status (str): "For_Sale", "For_Rent", or "Sold"
            page (int): Page number (1-5). 200 results per page, max 1000 total.
            sort_order (str): Sort by - Homes_for_you, Price_High_to_Low,
                Price_Low_to_High, Newest, Bedrooms, Bathrooms,
                Square_Feet, Lot_Size, Year_Built
            home_type (str): Comma-separated. For Sale/Sold: Houses, Townhomes,
                Multi-family, Condos/Co-ops, Lots-Land, Apartments, Manufactured.
                For Rent: Houses, Apartments/Condos/Co-ops, Townhomes
            bed_min (str): Min bedrooms - No_Min, Studio, 1, 2, 3, 4, 5
            bed_max (str): Max bedrooms - No_Max, Studio, 1, 2, 3, 4, 5
            bathrooms (str): Any, OnePlus, OneHalfPlus, TwoPlus, ThreePlus, FourPlus
            list_price_range (str): "min:5000, max:500000" or "min:5000" or "max:500000"
            square_feet_range (str): "min:500, max:5000"
            lot_size_range (str): In sqft. "min:1000, max:7500" (1 acre = 43560 sqft)
            year_built_range (str): "min:2011, max:2024"
            days_on_zillow (str): Any, 1_day, 7_days, 14_days, 30_days, 90_days,
                6_months, 12_months, 24_months, 36_months
            sold_in_last (str): Same options as days_on_zillow. Only for Sold.
            keywords (str): Free text search - MLS #, yard, fireplace, etc.
            max_hoa (str): For Sale/Sold only. Any, No_HOA_Fee, 50_dollars_month, etc.
            parking_spots (str): Any, OnePlus, TwoPlus, ThreePlus, FourPlus
            have_garage (bool): Filter for garage
            must_have_basement (str): No, Yes_Finished, Yes_Unfinished, Yes_Both
            single_story_only (bool): Single story homes only
            listing_type (str): For Sale only. Any, By_Agent, By_Owner_and_Other
            property_status (str): For Sale only. Comma-separated:
                Coming soon, Accepting backup offers, Pending & under contract
            pets (str): For Rent only. Allow large dogs, Allow small dogs, Allow cats
            other_amenities (str): Must have A/C, Must have pool, Waterfront, etc.
            view (str): City, Mountain, Park, Water

        Returns:
            dict: Search results with property listings
        """
        params = {
            "location": location,
            "listingStatus": listing_status,
            "page": page,
            "sortOrder": sort_order,
            "homeType": home_type,
            "bed_min": bed_min,
            "bed_max": bed_max,
            "bathrooms": bathrooms,
            "listPriceRange": list_price_range,
            "squareFeetRange": square_feet_range,
            "lotSizeRange": lot_size_range,
            "yearBuiltRange": year_built_range,
            "daysOnZillow": days_on_zillow,
            "soldInLast": sold_in_last,
            "keywords": keywords,
            "maxHOA": max_hoa,
            "parkingSpots": parking_spots,
            "haveGarage": have_garage,
            "mustHaveBasement": must_have_basement,
            "singleStoryOnly": single_story_only,
            "listingType": listing_type,
            "propertyStatus": property_status,
            "pets": pets,
            "otherAmenities": other_amenities,
            "view": view,
        }
        return self._get("/search/byaddress", params)

    def search_by_coordinates(self, latitude, longitude, radius,
                              listing_status="For_Sale", page=1,
                              sort_order=None, **kwargs):
        """
        Search Zillow listings by geographic coordinates (circle search).

        Args:
            latitude (str): Latitude coordinate. Example: "40.599283"
            longitude (str): Longitude coordinate. Example: "-74.129194"
            radius (str): Search radius in miles. Example: "0.5"
            listing_status (str): "For_Sale", "For_Rent", or "Sold"
            page (int): Page number (1-5)
            sort_order (str): Sort order option
            **kwargs: Additional search filters (same as search_by_address)

        Returns:
            dict: Search results with property listings
        """
        params = {
            "latitude": str(latitude),
            "longitude": str(longitude),
            "radius": str(radius),
            "listingStatus": listing_status,
            "page": page,
            "sortOrder": sort_order,
            **kwargs,
        }
        return self._get("/search/bycoordinates", params)

    def search_by_url(self, url):
        """
        Search Zillow by providing a direct Zillow search URL.

        Args:
            url (str): A Zillow search results URL

        Returns:
            dict: Search results
        """
        return self._get("/search/byurl", {"url": url})

    def search_by_mls(self, mls):
        """
        Search Zillow by MLS number.

        Args:
            mls (str): MLS listing number

        Returns:
            dict: Property data matching the MLS number
        """
        return self._get("/search/bymls", {"mls": mls})

    def autocomplete(self, query):
        """
        Get Zillow autocomplete suggestions for a search query.

        Args:
            query (str): Search text for autocomplete.
                Example: "649 Keller St, Bay St Louis, MS 39520"

        Returns:
            dict: Autocomplete suggestions
        """
        return self._get("/autocomplete", {"query": query})

    # ─────────────────────────────────────────────
    # 3. Property Info - Specific
    # ─────────────────────────────────────────────

    def get_property_images(self, byzpid=None, byurl=None, byaddress=None):
        """
        Get property images. Provide one of: ZPID, Zillow URL, or address.
        Priority: ZPID > URL > Address.

        Args:
            byzpid (str): Zillow Property ID
            byurl (str): Zillow property URL
            byaddress (str): Full property address

        Returns:
            dict: Property image URLs
        """
        return self._get("/propimages", {
            "byzpid": byzpid, "byurl": byurl, "byaddress": byaddress
        })

    def get_price_history(self, byzpid=None, byurl=None, byaddress=None):
        """
        Get property price history. Priority: ZPID > URL > Address.

        Args:
            byzpid (str): Zillow Property ID
            byurl (str): Zillow property URL
            byaddress (str): Full property address

        Returns:
            dict: Price history data
        """
        return self._get("/pricehistory", {
            "byzpid": byzpid, "byurl": byurl, "byaddress": byaddress
        })

    def get_comparable_homes(self, byzpid=None, byurl=None, byaddress=None):
        """
        Get comparable homes nearby. Priority: ZPID > URL > Address.

        Args:
            byzpid (str): Zillow Property ID
            byurl (str): Zillow property URL
            byaddress (str): Full property address

        Returns:
            dict: Comparable property listings
        """
        return self._get("/comparable_homes", {
            "byzpid": byzpid, "byurl": byurl, "byaddress": byaddress
        })

    def get_similar_properties(self, byzpid=None, byurl=None, byaddress=None):
        """
        Get similar properties. Priority: ZPID > URL > Address.

        Returns:
            dict: Similar property data
        """
        return self._get("/similar_properties", {
            "byzpid": byzpid, "byurl": byurl, "byaddress": byaddress
        })

    def get_nearby_properties(self, byzpid=None, byurl=None, byaddress=None):
        """
        Get nearby properties. Priority: ZPID > URL > Address.

        Returns:
            dict: Nearby property data
        """
        return self._get("/nearby_properties", {
            "byzpid": byzpid, "byurl": byurl, "byaddress": byaddress
        })

    def get_walk_transit_bike_scores(self, byzpid=None, byurl=None, byaddress=None):
        """
        Get walk, transit, and bike scores. Priority: ZPID > URL > Address.

        Returns:
            dict: Walk score, transit score, bike score data
        """
        return self._get("/walk_transit_bike", {
            "byzpid": byzpid, "byurl": byurl, "byaddress": byaddress
        })

    def get_climate_data(self, byzpid=None, byurl=None, byaddress=None):
        """
        Get climate risk data for a property. Priority: ZPID > URL > Address.

        Returns:
            dict: Climate and environmental risk data
        """
        return self._get("/climate", {
            "byzpid": byzpid, "byurl": byurl, "byaddress": byaddress
        })

    def get_tax_history(self, byzpid=None, byurl=None, byaddress=None):
        """
        Get tax assessment history. Priority: ZPID > URL > Address.

        Returns:
            dict: Tax info and assessment history
        """
        return self._get("/taxinfo_history", {
            "byzpid": byzpid, "byurl": byurl, "byaddress": byaddress
        })

    def get_owner_agent_info(self, byzpid=None, byurl=None, byaddress=None):
        """
        Get listing agent / owner info. Priority: ZPID > URL > Address.

        Returns:
            dict: Owner and agent details
        """
        return self._get("/owner-agent", {
            "byzpid": byzpid, "byurl": byurl, "byaddress": byaddress
        })

    def get_apartment_details(self, byzpid=None, byurl=None, byaddress=None):
        """
        Get apartment-specific details. Priority: ZPID > URL > Address.

        Returns:
            dict: Apartment detail data
        """
        return self._get("/apartment_details", {
            "byzpid": byzpid, "byurl": byurl, "byaddress": byaddress
        })

    def get_lotid_from_address(self, address):
        """
        Get LOT ID from a property address.

        Args:
            address (str): Full property address

        Returns:
            dict: LOT ID data
        """
        return self._get("/lotid_from_address", {"byaddress": address})

    # ─────────────────────────────────────────────
    # 4. Graphs and Charts (Estimates)
    # ─────────────────────────────────────────────

    def get_zestimate_history(self, byzpid=None, byurl=None, byaddress=None,
                              recent_first="True"):
        """
        Get Zestimate (home value) history for last 10 years.

        Args:
            byzpid (str): Zillow Property ID
            byurl (str): Zillow property URL
            byaddress (str): Full property address
            recent_first (str): "True" for current month first, "False" for oldest first

        Returns:
            dict: Zestimate history chart data
        """
        return self._get("/graph_charts", {
            "which": "zestimate_history",
            "recent_first": recent_first,
            "byzpid": byzpid,
            "byurl": byurl,
            "byaddress": byaddress,
        })

    # ─────────────────────────────────────────────
    # 5. Market Analytics
    # ─────────────────────────────────────────────

    def get_housing_market(self, search_query, home_type=None,
                           exclude_rental_trends=None,
                           exclude_neighborhoods=None):
        """
        Get Zillow Home Value Index (ZHVI) and housing market data.

        Args:
            search_query (str): City/state/ZIP. Use "USA" for nationwide data.
                Example: "Austin, TX"
            home_type (str): All_Homes, Single_Family, or Condo
            exclude_rental_trends (bool): Default True. Set False to include rental data.
            exclude_neighborhoods (bool): Exclude neighborhood-level ZHVI data.

        Returns:
            dict: Housing market analytics and ZHVI data
        """
        return self._get("/housing_market", {
            "search_query": search_query,
            "home_type": home_type,
            "exclude_rentalMarketTrends": exclude_rental_trends,
            "exclude_neighborhoods_zhvi": exclude_neighborhoods,
        })

    # ─────────────────────────────────────────────
    # 6. Find an Agent
    # ─────────────────────────────────────────────

    def search_agents(self, location=None, agent_name=None, page=1,
                      is_buying=None, is_selling=None, is_top_agent=None,
                      price_range=None, specialties=None, languages=None):
        """
        Search for real estate agents on Zillow.

        Args:
            location (str): City, neighborhood, or ZIP code.
                Example: "Saint Louis, MO" or "30043"
            agent_name (str): Filter by agent name
            page (int): Results page number
            is_buying (bool): Filter agents handling buying
            is_selling (bool): Filter agents handling selling
            is_top_agent (bool): Show only top-rated agents
            price_range (str): "min,max" format. Example: "300000,10000000"
            specialties (str): Comma-separated specialties:
                first-time-home-buyers, foreclosure, investment-properties,
                lot-or-land, luxury-homes, military-or-veterans,
                new-construction, property-management, relocation, rentals,
                senior-communities, vacation-short-term-rentals
            languages (str): Comma-separated languages. Default: English.
                arabic, bengali, cantonese, farsi, filipino, french, german,
                greek, hebrew, hindi, hungarian, italian, japanese, korean,
                mandarin, polish, portuguese, russian, spanish, thai,
                turkish, vietnamese

        Returns:
            dict: Agent search results
        """
        return self._get("/agent/search", {
            "location": location,
            "agentName": agent_name,
            "page": page,
            "isBuying": is_buying,
            "isSelling": is_selling,
            "isTopAgent": is_top_agent,
            "priceRange": price_range,
            "specialties": specialties,
            "languages": languages,
        })

    def get_agent_details(self, agent_link=None, username=None):
        """
        Get detailed agent profile information.

        Args:
            agent_link (str): Agent's Zillow profile URL.
                Example: "https://www.zillow.com/profile/Alex-Antigua"
            username (str): Agent's Zillow username.
                Example: "Alex-Antigua"
            Note: agent_link takes priority over username.

        Returns:
            dict: Agent profile details
        """
        return self._get("/agent/details", {
            "agent_link": agent_link,
            "username": username,
        })

    def get_agent_for_sale(self, agent_link=None, username=None):
        """Get agent's active for-sale listings."""
        return self._get("/agent/forSaleProperties", {
            "agent_link": agent_link, "username": username,
        })

    def get_agent_for_rent(self, agent_link=None, username=None):
        """Get agent's active rental listings."""
        return self._get("/agent/forRentProperties", {
            "agent_link": agent_link, "username": username,
        })

    def get_agent_sold(self, agent_link=None, username=None):
        """Get agent's sold property history."""
        return self._get("/agent/soldProperties", {
            "agent_link": agent_link, "username": username,
        })

    def get_agent_reviews(self, agent_link=None, username=None):
        """Get agent reviews from Zillow."""
        return self._get("/agent/reviews", {
            "agent_link": agent_link, "username": username,
        })

    # ─────────────────────────────────────────────
    # 7. Skip Tracing
    # ─────────────────────────────────────────────

    def skip_trace_by_address(self, street, citystatezip, page=1):
        """
        Skip trace a property to find owner information.
        Note: Each call costs 10 API requests.

        Args:
            street (str): Street address. Example: "3828 Double Oak Ln"
            citystatezip (str): City, state, ZIP. Example: "Irving, TX 75061"
            page (int): Pagination for 10+ records

        Returns:
            dict: Owner/person details matching the address
        """
        return self._get("/skip/byaddress", {
            "street": street,
            "citystatezip": citystatezip,
            "page": page,
        })