redfin_api.py

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

A comprehensive Python wrapper for the Redfin Scraper API.
Supports property search, property details, agent info, AVM estimates,
walk scores, flood info, and more.
"""

import requests
from config import BASE_URL, get_headers


class RedfinAPI:
    """
    Redfin Scraper API client for real estate data extraction.

    Provides access to Redfin property data, listings, agent info,
    market insights, and valuations 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}"
        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 Search
    # ─────────────────────────────────────────────

    def autocomplete(self, query, listing_status=None):
        """
        Get autocomplete suggestions for a location query.

        Args:
            query (str): Location/query text.
                Example: "New York", "Austin", "Texas"
            listing_status (str): "For_Sale_or_Sold" or "For_Rent".
                Sale/Sold shows standard response. Rent shows rental listings.

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

    def search_by_location(self, location_name, search_type=None, page=1,
                           result_count=None, sort_order=None,
                           min_price=None, max_price=None,
                           min_beds=None, max_beds=None, baths=None,
                           home_type=None, min_square_feet=None,
                           max_square_feet=None, min_lot_size=None,
                           max_lot_size=None, min_year_built=None,
                           max_year_built=None, status=None,
                           time_on_redfin=None, sold_within=None,
                           price_reduced=None, hoa_fees=None,
                           listing_type=None, keyword=None,
                           walk_score=None, transit_score=None,
                           bike_score=None, pool_types=None,
                           garage_spots=None, home_features=None,
                           great_schools_rating=None, pets=None,
                           location_sub_name=None, **kwargs):
        """
        Search Redfin listings by location name.

        Args:
            location_name (str): City, state, ZIP, neighborhood, or address.
                Example: "New York", "Austin, TX", "10001"
            location_sub_name (str): Sub-location filter (optional)
            search_type (str): For_Sale, For_Rent, or Sold
            page (int): Page number for pagination
            result_count (int): Results per page (1-1000, default 100)
            sort_order (str): Recommended, Newest, Oldest, Most_Recently_Sold,
                Price_High_to_Low, Price_Low_to_High, Square_Feet, Lot_Size,
                Price_per_Sqft, Beds, Baths
            min_price (str): Minimum price (e.g., "100000")
            max_price (str): Maximum price (e.g., "500000")
            min_beds (str): Any, Studio, One, Two, Three, Four, FivePlus, SixPlus
            max_beds (str): Any, Studio, One, Two, Three, Four, FivePlus, SixPlus
            baths (str): Any, OnePlus, OnePointFivePlus, Two, TwoPointFivePlus,
                ThreePlus, FourPlus, FivePlus, SixPlus
            home_type (str): Comma-separated. House, Condo, Townhouse,
                Multi family, Land, Other, Mobile, Co-op, Apartment
            min_square_feet (str): Minimum square footage
            max_square_feet (str): Maximum square footage
            min_lot_size (str): Minimum lot size in sqft
            max_lot_size (str): Maximum lot size in sqft
            min_year_built (int): Minimum year built (e.g., 1900)
            max_year_built (str): Maximum year built (e.g., "2025")
            status (str): Active_ComingSoon, Active, ComingSoon,
                UnderContractOrPending, etc.
            time_on_redfin (str): Any, New_listings, Less_than_3d,
                Less_than_7d, Less_than_14d, Less_than_30d, etc.
            sold_within (str): Last_7_Days, Last_1_Month, Last_3_Months,
                Last_6_Months, Last_1_Year, Last_2_Years, Last_3_Years, Last_5_Years
            price_reduced (str): None, AnyTime, Less_than_1d, Less_than_7d, etc.
            hoa_fees (str): No_max, 25, 50, 100, 200, 500, 1000, etc.
            listing_type (str): Comma-separated. New Constructions, By Agent,
                MLS listed Foreclosures, For Sale by owner, Foreclosures
            keyword (str): Free-text search keyword
            walk_score (str): Any, 10plus, 20plus, ... 90plus
            transit_score (str): Any, 10plus, 20plus, ... 90plus
            bike_score (str): Any, 10plus, 20plus, ... 90plus
            pool_types (str): None, Private, Community,
                Private_or_Community, No_private_pool
            garage_spots (str): No_Min, 1plus, 2plus, 3plus, 4plus, 5plus
            home_features (str): Comma-separated. Air conditioning, Fireplace,
                Waterfront, Guest house, Accessible home, Elevator, Green home
            great_schools_rating (str): Any, 1plus, ... 9plus, 10
            pets (str): For Rent only. Cats allowed, Dogs allowed,
                Dogs allowed + Cats allowed

        Returns:
            dict: Search results with property listings
        """
        params = {
            "locationName": location_name,
            "locationSubName": location_sub_name,
            "searchType": search_type,
            "page": page,
            "resultCount": result_count,
            "sortOrder": sort_order,
            "minPrice": min_price,
            "maxPrice": max_price,
            "minBeds": min_beds,
            "maxBeds": max_beds,
            "baths": baths,
            "homeType": home_type,
            "minSquareFeet": min_square_feet,
            "maxSquareFeet": max_square_feet,
            "minLotSize": min_lot_size,
            "maxLotSize": max_lot_size,
            "minYearBuilt": min_year_built,
            "maxYearBuilt": max_year_built,
            "status": status,
            "timeOnRedfin": time_on_redfin,
            "soldWithin": sold_within,
            "priceReduced": price_reduced,
            "HOAfees": hoa_fees,
            "listingType": listing_type,
            "keyword": keyword,
            "walkScore": walk_score,
            "transitScore": transit_score,
            "bikeScore": bike_score,
            "poolTypes": pool_types,
            "garageSpots": garage_spots,
            "homeFeatures": home_features,
            "greatSchoolsRating": great_schools_rating,
            "pets": pets,
            **kwargs,
        }
        return self._get("/search/bylocation", params)

    def search_by_coordinates(self, latitude, longitude, radius,
                              search_type=None, page=1, result_count=None,
                              sort_order=None, min_price=None, max_price=None,
                              min_beds=None, max_beds=None, baths=None,
                              home_type=None, min_square_feet=None,
                              max_square_feet=None, status=None,
                              sold_within=None, keyword=None, **kwargs):
        """
        Search Redfin listings by coordinates (circle search).

        Args:
            latitude (str): Latitude. Example: "40.748817"
            longitude (str): Longitude. Example: "-73.985428"
            radius (str): Radius in miles. Example: "1.5"
            search_type (str): For_Sale, For_Rent, or Sold
            page (int): Page number
            result_count (int): Results per page (1-1000)
            sort_order (str): Sort order option
            min_price (str): Minimum price
            max_price (str): Maximum price
            min_beds (str): Min bedrooms
            max_beds (str): Max bedrooms
            baths (str): Bathroom filter
            home_type (str): Comma-separated home types
            min_square_feet (str): Min sqft
            max_square_feet (str): Max sqft
            status (str): Listing status filter
            sold_within (str): Sold timeframe filter
            keyword (str): Free-text keyword
            **kwargs: Additional search filters

        Returns:
            dict: Search results with property listings
        """
        params = {
            "latitude": str(latitude),
            "longitude": str(longitude),
            "radius": str(radius),
            "searchType": search_type,
            "page": page,
            "resultCount": result_count,
            "sortOrder": sort_order,
            "minPrice": min_price,
            "maxPrice": max_price,
            "minBeds": min_beds,
            "maxBeds": max_beds,
            "baths": baths,
            "homeType": home_type,
            "minSquareFeet": min_square_feet,
            "maxSquareFeet": max_square_feet,
            "status": status,
            "soldWithin": sold_within,
            "keyword": keyword,
            **kwargs,
        }
        return self._get("/search/bycoordinates", params)

    def search_by_polygon(self, polygon, search_type=None, page=1,
                          result_count=None, sort_order=None,
                          min_price=None, max_price=None,
                          min_beds=None, max_beds=None, baths=None,
                          home_type=None, keyword=None, **kwargs):
        """
        Search Redfin listings by polygon coordinates.

        Args:
            polygon (str): Comma-separated lng/lat pairs defining the polygon.
                Example: "-74.006 40.733,-73.981 40.748,-73.958 40.733"
            search_type (str): For_Sale, For_Rent, or Sold
            page (int): Page number
            result_count (int): Results per page (1-1000)
            sort_order (str): Sort order
            min_price (str): Minimum price
            max_price (str): Maximum price
            min_beds (str): Min bedrooms
            max_beds (str): Max bedrooms
            baths (str): Bathroom filter
            home_type (str): Comma-separated home types
            keyword (str): Free-text keyword
            **kwargs: Additional search filters

        Returns:
            dict: Search results
        """
        params = {
            "polygon": polygon,
            "searchType": search_type,
            "page": page,
            "resultCount": result_count,
            "sortOrder": sort_order,
            "minPrice": min_price,
            "maxPrice": max_price,
            "minBeds": min_beds,
            "maxBeds": max_beds,
            "baths": baths,
            "homeType": home_type,
            "keyword": keyword,
            **kwargs,
        }
        return self._get("/search/bypolygon", params)

    def search_by_region_id(self, region_id, search_type=None, page=1,
                            result_count=None, sort_order=None,
                            min_price=None, max_price=None,
                            min_beds=None, max_beds=None, baths=None,
                            home_type=None, keyword=None, **kwargs):
        """
        Search Redfin listings by region ID.

        Args:
            region_id (str): Redfin region identifier. Example: "4_3244"
            search_type (str): For_Sale, For_Rent, or Sold
            page (int): Page number
            result_count (int): Results per page (1-1000)
            sort_order (str): Sort order
            **kwargs: Additional search filters

        Returns:
            dict: Search results
        """
        params = {
            "regionId": region_id,
            "searchType": search_type,
            "page": page,
            "resultCount": result_count,
            "sortOrder": sort_order,
            "minPrice": min_price,
            "maxPrice": max_price,
            "minBeds": min_beds,
            "maxBeds": max_beds,
            "baths": baths,
            "homeType": home_type,
            "keyword": keyword,
            **kwargs,
        }
        return self._get("/search/byregionid", params)

    def search_by_url(self, search_url, result_count=None):
        """
        Search Redfin by passing a Redfin search URL with filters.

        Args:
            search_url (str): Complete Redfin search URL.
                Example: "https://www.redfin.com/zipcode/10002/filter/property-type=house,min-price=150k"
            result_count (int): Number of results (1-350)

        Returns:
            dict: Search results
        """
        return self._get("/search/byurl", {
            "searchUrl": search_url,
            "resultCount": result_count,
        })

    # ─────────────────────────────────────────────
    # 2. Property Details
    # ─────────────────────────────────────────────

    def get_details_by_address(self, property_address):
        """
        Get full property details by address.

        Args:
            property_address (str): Full property address.
                Example: "166 W 22nd St Unit 1D, New York, NY 10011"

        Returns:
            dict: Comprehensive property details
        """
        return self._get("/detailsbyaddress", {
            "property_address": property_address,
        })

    def get_details_by_id(self, property_id, listing_id):
        """
        Get full property details by property ID and listing ID.

        Args:
            property_id (str): Redfin property ID. Example: "20739181"
            listing_id (str): Redfin listing ID. Example: "192575318"

        Returns:
            dict: Comprehensive property details
        """
        return self._get("/detailsbyid", {
            "property_id": property_id,
            "listing_id": listing_id,
        })

    def get_details_by_url(self, property_url):
        """
        Get full property details by Redfin URL.

        Args:
            property_url (str): Full Redfin property URL.
                Example: "https://www.redfin.com/NY/Saint-Albans/10970-203rd-St-11412/home/20739181"

        Returns:
            dict: Comprehensive property details
        """
        return self._get("/detailsbyurl", {
            "property_url": property_url,
        })

    # ─────────────────────────────────────────────
    # 3. Individual Details
    # ─────────────────────────────────────────────

    def get_agent_info(self, property_id, listing_id):
        """
        Get listing agent details.

        Args:
            property_id (str): Redfin property ID
            listing_id (str): Redfin listing ID

        Returns:
            dict: Agent information
        """
        return self._get("/agentInfo", {
            "property_id": property_id,
            "listing_id": listing_id,
        })

    def get_amenities(self, property_id, listing_id):
        """
        Get property amenities details.

        Args:
            property_id (str): Redfin property ID
            listing_id (str): Redfin listing ID

        Returns:
            dict: Property amenities
        """
        return self._get("/amenities", {
            "property_id": property_id,
            "listing_id": listing_id,
        })

    def get_avm_estimate(self, property_id, listing_id):
        """
        Get Automated Valuation Model (AVM) estimate.

        Args:
            property_id (str): Redfin property ID
            listing_id (str): Redfin listing ID

        Returns:
            dict: AVM estimate data
        """
        return self._get("/avm", {
            "property_id": property_id,
            "listing_id": listing_id,
        })

    def get_basic_details(self, property_url):
        """
        Get basic property details from a Redfin URL.
        Useful for getting property_id and listing_id from a URL.

        Args:
            property_url (str): Full Redfin property URL.

        Returns:
            dict: Basic details including property_id and listing_id
        """
        return self._get("/basicDetails", {
            "property_url": property_url,
        })

    def get_customer_conversion_info(self, property_id, listing_id):
        """
        Get customer conversion information data.

        Args:
            property_id (str): Redfin property ID
            listing_id (str): Redfin listing ID

        Returns:
            dict: Customer conversion data
        """
        return self._get("/customerConversionInfo", {
            "property_id": property_id,
            "listing_id": listing_id,
        })

    def get_flood_info(self, fips_code, apn, lat, lng):
        """
        Get flood risk information for a property.

        Args:
            fips_code (str): FIPS county code. Example: "36081"
            apn (str): Assessor's Parcel Number. Example: "4109420115"
            lat (str): Latitude. Example: "40.7059662"
            lng (str): Longitude. Example: "-73.754585"

        Returns:
            dict: Flood risk data
        """
        return self._get("/floodInfo", {
            "fipsCode": fips_code,
            "apn": apn,
            "lat": lat,
            "lng": lng,
        })

    def get_date_picker_data(self, listing_id):
        """
        Get date picker data for scheduling property tours.

        Args:
            listing_id (str): Redfin listing ID

        Returns:
            dict: Available tour dates
        """
        return self._get("/getDatePickerData", {
            "listing_id": listing_id,
        })

    def get_hot_market_info(self, property_id):
        """
        Get hot market information for a property's area.

        Args:
            property_id (str): Redfin property ID

        Returns:
            dict: Market heat data
        """
        return self._get("/hotMarketInfo", {
            "property_id": property_id,
        })

    def get_insights(self, property_id, listing_id):
        """
        Get property insights (below the fold data).

        Args:
            property_id (str): Redfin property ID
            listing_id (str): Redfin listing ID

        Returns:
            dict: Property insights
        """
        return self._get("/insights", {
            "property_id": property_id,
            "listing_id": listing_id,
        })

    def get_main_house_info(self, property_id, listing_id):
        """
        Get main house information panel details.

        Args:
            property_id (str): Redfin property ID
            listing_id (str): Redfin listing ID

        Returns:
            dict: Main house info panel data
        """
        return self._get("/mainHouseInfoPanelInfo", {
            "property_id": property_id,
            "listing_id": listing_id,
        })

    def get_mortgage_calculator(self, property_id, listing_id):
        """
        Get mortgage calculator information.

        Args:
            property_id (str): Redfin property ID
            listing_id (str): Redfin listing ID

        Returns:
            dict: Mortgage calculation data
        """
        return self._get("/mortgageCalculatorInfo", {
            "property_id": property_id,
            "listing_id": listing_id,
        })

    def get_overview(self, property_id, listing_id):
        """
        Get property overview (above the fold data).

        Args:
            property_id (str): Redfin property ID
            listing_id (str): Redfin listing ID

        Returns:
            dict: Property overview
        """
        return self._get("/overview", {
            "property_id": property_id,
            "listing_id": listing_id,
        })

    def get_popularity_info(self, listing_id):
        """
        Get property popularity information.

        Args:
            listing_id (str): Redfin listing ID

        Returns:
            dict: Popularity metrics
        """
        return self._get("/popularityInfo", {
            "listing_id": listing_id,
        })

    def get_price_drop_info(self, listing_id):
        """
        Get price drop information for a listing.

        Args:
            listing_id (str): Redfin listing ID

        Returns:
            dict: Price drop history
        """
        return self._get("/priceDropInfo", {
            "listing_id": listing_id,
        })

    def get_tour_insights(self, property_id, listing_id):
        """
        Get tour insights data.

        Args:
            property_id (str): Redfin property ID
            listing_id (str): Redfin listing ID

        Returns:
            dict: Tour insight data
        """
        return self._get("/tourInsights", {
            "property_id": property_id,
            "listing_id": listing_id,
        })

    def get_walk_score(self, property_id, listing_id):
        """
        Get walk, transit, and bike scores.

        Args:
            property_id (str): Redfin property ID
            listing_id (str): Redfin listing ID

        Returns:
            dict: Walk score, transit score, bike score
        """
        return self._get("/walkScore", {
            "property_id": property_id,
            "listing_id": listing_id,
        })