bayut_api.py

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

A comprehensive Python wrapper for the Bayut Scraper API.
Supports property search, property details, agent/agency lookup,
TruBroker search, and autocomplete for UAE real estate.
"""

import requests
from config import BASE_URL, get_headers


class BayutAPI:
    """
    Bayut Scraper API client for UAE real estate data extraction.

    Provides access to Bayut property data for Dubai, Abu Dhabi,
    Sharjah, and all UAE emirates 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. Search & Autocomplete
    # ─────────────────────────────────────────────

    def autocomplete(self, query, hits_per_page=None, page=None):
        """
        Get autocomplete suggestions for a location query.
        Returns location_external_id used in property search.

        Args:
            query (str): Search term. Example: "dubai", "abu dhabi"
            hits_per_page (str): Results per page. Default: 25
            page (str): Page number (0-based). Default: 0

        Returns:
            dict: Autocomplete results with location_external_id values
        """
        return self._get("/autocomplete", {
            "query": query,
            "hitsPerPage": hits_per_page,
            "page": page,
        })

    def search_property(self, location_external_id, purpose="for-sale",
                        hits_per_page=None, page=None, category=None,
                        rent_frequency=None, rooms=None, baths=None,
                        min_price=None, max_price=None, min_area=None,
                        max_area=None, furnishing_status=None,
                        agency_external_ids=None, category_external_id=None,
                        product=None, has_floorplan=None, has_panorama=None,
                        has_video=None, completion_status=None):
        """
        Search properties on Bayut.

        Args:
            location_external_id (str): Location ID from /autocomplete.
                Example: "6901" (Dubai Marina)
            purpose (str): "for-sale" or "for-rent"
            hits_per_page (str): Results per page. Default: 25
            page (str): Page number (0-based). Default: 0
            category (str): "residential" or "commercial"
            rent_frequency (str): "monthly", "yearly", "weekly", or "daily"
                (only for for-rent)
            rooms (str): Number of bedrooms. Example: "1", "2", "3"
            baths (str): Number of bathrooms. Example: "1", "2"
            min_price (str): Minimum price
            max_price (str): Maximum price
            min_area (str): Minimum area in sqft
            max_area (str): Maximum area in sqft
            furnishing_status (str): "furnished" or "unfurnished"
            agency_external_ids (str): Filter by agency. Comma-separated IDs.
                Example: "7737,5002"
            category_external_id (str): Property type ID.
                Apartment=4, Townhouses=16, Villas=3, Penthouses=18,
                Hotel Apartments=21, Villa Compound=19, Residential Plot=14,
                Residential Floor=12, Residential Building=17,
                Office=5, Shop=6, Warehouse=7, Labour camp=9,
                Commercial Villa=25, Bulk Units=20, Commercial Plot=15,
                Commercial Floor=13, Commercial Building=10, Factory=8,
                Industrial Land=22, Mixed Use Land=23, Showroom=24,
                Other Commercial=11
            product (str): "superhot" or "hot" (featured listings)
            has_floorplan (bool): Filter listings with floor plans
            has_panorama (bool): Filter listings with 360 panorama
            has_video (bool): Filter listings with video tours
            completion_status (str): "completed" or "under-construction"
                (only for for-sale)

        Returns:
            dict: Search results with property listings
        """
        return self._get("/search/property", {
            "location_external_id": location_external_id,
            "purpose": purpose,
            "hitsPerPage": hits_per_page,
            "page": page,
            "category": category,
            "rent_frequency": rent_frequency,
            "rooms": rooms,
            "baths": baths,
            "min_price": min_price,
            "max_price": max_price,
            "min_area": min_area,
            "max_area": max_area,
            "furnishingStatus": furnishing_status,
            "agency_external_ids": agency_external_ids,
            "category_external_id": category_external_id,
            "product": product,
            "hasFloorplan": has_floorplan,
            "hasPanorama": has_panorama,
            "hasVideo": has_video,
            "completionStatus": completion_status,
        })

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

    def get_property_details(self, property_external_id):
        """
        Get full property details by external ID.

        Args:
            property_external_id (str): The externalID from search results.
                Example: "12372178"

        Returns:
            dict: Full property details
        """
        return self._get("/details/property", {
            "property_external_id": property_external_id,
        })

    # ─────────────────────────────────────────────
    # 3. Agency & Agent
    # ─────────────────────────────────────────────

    def get_agency_details(self, agency_external_id):
        """
        Get agency details and its agents list.

        Args:
            agency_external_id (str): Agency ID from search results.
                Example: "10499"

        Returns:
            dict: Agency details with agent list
        """
        return self._get("/details/agency", {
            "agency_external_id": agency_external_id,
        })

    def get_agent_details(self, agent_slug):
        """
        Get agent profile details.

        Args:
            agent_slug (str): Agent slug from agency details
                (hits -> slug field).
                Example: "salma-mohamed-mahmoud-hashem-2521536"

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

    def get_agents_by_agency(self, agency_external_id):
        """
        Get all agents belonging to an agency.

        Args:
            agency_external_id (str): Agency ID. Example: "10499"

        Returns:
            dict: List of agents in the agency
        """
        return self._get("/agent/agency", {
            "agency_external_id": agency_external_id,
        })

    def get_agent_claimed_deals_count(self, agent_external_id):
        """
        Get the number of claimed deals for an agent.

        Args:
            agent_external_id (str): Agent ID from agency details.
                Example: "1919589"

        Returns:
            dict: Claimed deals count
        """
        return self._get("/agent/claimedDeals/count", {
            "agent_external_id": agent_external_id,
        })

    def get_agent_claimed_deals_total_price(self, agent_external_id):
        """
        Get total price of claimed deals for an agent.

        Args:
            agent_external_id (str): Agent ID from agency details.
                Example: "1919589"

        Returns:
            dict: Total price of claimed deals
        """
        return self._get("/agent/claimedDeals/totalPrice", {
            "agent_external_id": agent_external_id,
        })

    def get_agent_stories(self, agent_external_id, page_size=None):
        """
        Get agent stories/posts.

        Args:
            agent_external_id (str): Agent ID. Example: "1919589"
            page_size (str): Number of stories per page. Default: 50

        Returns:
            dict: Agent stories
        """
        return self._get("/stories/agent", {
            "agent_external_id": agent_external_id,
            "page_size": page_size,
        })

    # ─────────────────────────────────────────────
    # 4. TruBroker
    # ─────────────────────────────────────────────

    def search_trubroker_agents(self, location_external_id,
                                hits_per_page=None, page=None,
                                category=None, purpose=None,
                                completion_status=None):
        """
        Search TruBroker verified agents by location.

        Args:
            location_external_id (str): Location ID from /autocomplete.
                Example: "5152"
            hits_per_page (str): Results per page. Default: 25
            page (str): Page number. Default: 1
            category (str): "residential" or "commercial"
            purpose (str): "for-sale" or "for-rent"
            completion_status (str): "completed" or "under-construction"

        Returns:
            dict: TruBroker agent results
        """
        return self._get("/truBroker/agent", {
            "location_external_id": location_external_id,
            "hitsPerPage": hits_per_page,
            "page": page,
            "category": category,
            "purpose": purpose,
            "completionStatus": completion_status,
        })