airbnb_api.py

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

A comprehensive Python wrapper for the Airbnb Scraper API.
Supports searching homes, experiences, and services, getting details
and reviews, checking availability, and browsing filters.
"""

import requests
from config import BASE_URL, get_headers


class AirbnbAPI:
    """
    Airbnb Scraper API client for vacation rental data extraction.

    Provides access to Airbnb homes, experiences, and services data
    worldwide 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 Homes
    # ─────────────────────────────────────────────

    def search_homes_by_destination(self, destination, check_in=None,
                                     check_out=None, adults=None,
                                     children=None, infants=None, pets=None,
                                     next_page_cursor=None, type_of_place=None,
                                     price_min=None, price_max=None,
                                     bedrooms=None, beds=None, bathrooms=None,
                                     amenities=None, property_type=None,
                                     booking_options=None, guest_favorite=None,
                                     luxury_homes=None, superhost=None,
                                     results_type=None, currency=None,
                                     flexible_date_filters=None, months=None,
                                     flexible_stay_period=None,
                                     accessibility_features=None,
                                     host_languages=None):
        """
        Search Airbnb homes by destination/location.

        Args:
            destination (str): Location to search. Example: "toronto, canada"
            check_in (str): Check-in date YYYY-MM-DD
            check_out (str): Check-out date YYYY-MM-DD
            adults (int): Number of adults (ages 13+)
            children (int): Number of children (ages 2-12)
            infants (int): Number of infants (under 2)
            pets (int): Number of pets
            next_page_cursor (str): Cursor from previous page for pagination
            type_of_place (str): Any_type, Room, or Entire_home
            price_min (int): Minimum price per night
            price_max (int): Maximum price per night
            bedrooms (int): Minimum bedrooms
            beds (int): Minimum beds
            bathrooms (int): Minimum bathrooms
            amenities (str): Comma-separated amenity IDs. Example: "4, 8, 33"
                Use /filter/amenities for available IDs.
            property_type (str): House, Flat, Guest house, Hotel
            booking_options (str): Comma-separated. instant book, self checkin,
                allow pets, free cancellation
            guest_favorite (bool): Guest favorite listings only
            luxury_homes (bool): Luxury homes only
            superhost (bool): Superhost listings only
            results_type (str): search_results, map_results, map_plus_search_results
            currency (str): Currency code. Example: "USD"
            flexible_date_filters (str): Exact_dates, plusminus_1day,
                plusminus_2days, plusminus_3days, plusminus_7days, plusminus_14days
            months (str): Stay length in months (1-12)
            flexible_stay_period (str): Weekend, Week, or Month
            accessibility_features (str): Comma-separated IDs from /filter/accessibility
            host_languages (str): Comma-separated codes from /filter/host_language

        Returns:
            dict: Search results with listings
        """
        return self._get("/search/homes/bydestination", {
            "searchDestinations": destination,
            "checkIn": check_in,
            "checkOut": check_out,
            "adults": adults,
            "children": children,
            "infants": infants,
            "pets": pets,
            "nextPageCursor": next_page_cursor,
            "typeOfPlace": type_of_place,
            "priceRangeMin": price_min,
            "priceRangeMax": price_max,
            "bedrooms": bedrooms,
            "beds": beds,
            "bathrooms": bathrooms,
            "amenities": amenities,
            "propertyType": property_type,
            "bookingOptions": booking_options,
            "guestFavorite": guest_favorite,
            "luxuryHomes": luxury_homes,
            "superhost": superhost,
            "resultsType": results_type,
            "currency": currency,
            "flexibleDateFilters": flexible_date_filters,
            "months": months,
            "flexibleStayPeriod": flexible_stay_period,
            "accessibilityFeatures": accessibility_features,
            "hostLanguages": host_languages,
        })

    def search_homes_by_coordinates(self, ne_lat, ne_lng, sw_lat, sw_lng,
                                     check_in=None, check_out=None,
                                     adults=None, children=None, infants=None,
                                     pets=None, next_page_cursor=None,
                                     type_of_place=None, price_min=None,
                                     price_max=None, bedrooms=None, beds=None,
                                     bathrooms=None, amenities=None,
                                     property_type=None, booking_options=None,
                                     guest_favorite=None, luxury_homes=None,
                                     superhost=None, results_type=None,
                                     currency=None, **kwargs):
        """
        Search Airbnb homes by map bounding box coordinates.

        Args:
            ne_lat (str): NorthEast latitude (top-right). Example: "44.029433"
            ne_lng (str): NorthEast longitude. Example: "-79.317392"
            sw_lat (str): SouthWest latitude (bottom-left). Example: "43.824096"
            sw_lng (str): SouthWest longitude. Example: "-79.498301"
            (All other args same as search_homes_by_destination)

        Returns:
            dict: Search results with listings
        """
        return self._get("/search/homes/bycoordinates", {
            "ne_lat": str(ne_lat), "ne_lng": str(ne_lng),
            "sw_lat": str(sw_lat), "sw_lng": str(sw_lng),
            "checkIn": check_in, "checkOut": check_out,
            "adults": adults, "children": children,
            "infants": infants, "pets": pets,
            "nextPageCursor": next_page_cursor,
            "typeOfPlace": type_of_place,
            "priceRangeMin": price_min, "priceRangeMax": price_max,
            "bedrooms": bedrooms, "beds": beds, "bathrooms": bathrooms,
            "amenities": amenities, "propertyType": property_type,
            "bookingOptions": booking_options,
            "guestFavorite": guest_favorite, "luxuryHomes": luxury_homes,
            "superhost": superhost, "resultsType": results_type,
            "currency": currency, **kwargs,
        })

    def search_homes_by_place_id(self, place_id, check_in=None, check_out=None,
                                  adults=None, children=None, infants=None,
                                  pets=None, next_page_cursor=None,
                                  type_of_place=None, price_min=None,
                                  price_max=None, bedrooms=None, beds=None,
                                  bathrooms=None, amenities=None,
                                  property_type=None, guest_favorite=None,
                                  superhost=None, currency=None, **kwargs):
        """
        Search Airbnb homes by Google Place ID.

        Args:
            place_id (str): Google Place ID.
                Example: "ChIJpTvG15DL1IkRd8S0KlBVNTI"
            (All other args same as search_homes_by_destination)

        Returns:
            dict: Search results with listings
        """
        return self._get("/search/homes/byplaceid", {
            "placeId": place_id,
            "checkIn": check_in, "checkOut": check_out,
            "adults": adults, "children": children,
            "infants": infants, "pets": pets,
            "nextPageCursor": next_page_cursor,
            "typeOfPlace": type_of_place,
            "priceRangeMin": price_min, "priceRangeMax": price_max,
            "bedrooms": bedrooms, "beds": beds, "bathrooms": bathrooms,
            "amenities": amenities, "propertyType": property_type,
            "guestFavorite": guest_favorite, "superhost": superhost,
            "currency": currency, **kwargs,
        })

    def search_homes_by_category(self, category_tag, check_in=None,
                                  check_out=None, adults=None, children=None,
                                  infants=None, pets=None,
                                  next_page_cursor=None, type_of_place=None,
                                  price_min=None, price_max=None,
                                  bedrooms=None, beds=None, bathrooms=None,
                                  amenities=None, property_type=None,
                                  guest_favorite=None, superhost=None,
                                  currency=None, **kwargs):
        """
        Search Airbnb homes by category tag.

        Args:
            category_tag (str): Category from /categories endpoint.
                Example: "Tag:4104" (Countryside)
            (All other args same as search_homes_by_destination)

        Returns:
            dict: Search results with listings
        """
        return self._get("/search/homes/bycategory", {
            "category_tag": category_tag,
            "checkIn": check_in, "checkOut": check_out,
            "adults": adults, "children": children,
            "infants": infants, "pets": pets,
            "nextPageCursor": next_page_cursor,
            "typeOfPlace": type_of_place,
            "priceRangeMin": price_min, "priceRangeMax": price_max,
            "bedrooms": bedrooms, "beds": beds, "bathrooms": bathrooms,
            "amenities": amenities, "propertyType": property_type,
            "guestFavorite": guest_favorite, "superhost": superhost,
            "currency": currency, **kwargs,
        })

    # ─────────────────────────────────────────────
    # 2. Search Experiences
    # ─────────────────────────────────────────────

    def search_experiences_by_destination(self, destination, check_in=None,
                                          check_out=None, adults=None,
                                          children=None, infants=None,
                                          next_page_cursor=None,
                                          experience_type=None,
                                          traveler_type=None,
                                          price_min=None, price_max=None,
                                          min_duration=None, max_duration=None,
                                          time_of_day=None,
                                          host_languages=None,
                                          accessibility_features=None):
        """
        Search Airbnb experiences by destination.

        Args:
            destination (str): Location. Example: "toronto, canada"
            check_in (str): Start date YYYY-MM-DD
            check_out (str): End date YYYY-MM-DD
            adults (int): Adults (13+)
            children (int): Children (2-12)
            infants (int): Infants (under 2)
            next_page_cursor (str): Pagination cursor
            experience_type (str): Comma-separated types:
                architecture, art, beauty, cooking, cultural, dining,
                flying, food, galleries, landmarks, museum, outdoor,
                performance, shopping, tasting, water, wellness,
                wildlife, workout
            traveler_type (str): Kids, Big Groups, Solo Travellers, Date Night
            price_min (int): Min price per guest
            price_max (int): Max price per guest
            min_duration (int): Min duration in minutes (30,45,60,90,120,180)
            max_duration (int): Max duration in minutes (45,60,90,120,180)
            time_of_day (str): morning, afternoon, evening (comma-separated)
            host_languages (str): Comma-separated language codes
            accessibility_features (str): Step-free access, Sign language options,
                Designated sighted guide, No extreme sensory stimuli

        Returns:
            dict: Experience search results
        """
        return self._get("/search/exp/bydestination", {
            "searchDestinations": destination,
            "checkIn": check_in, "checkOut": check_out,
            "adults": adults, "children": children, "infants": infants,
            "nextPageCursor": next_page_cursor,
            "experienceType": experience_type,
            "travelerType": traveler_type,
            "pricePerGuest_min": price_min,
            "pricePerGuest_max": price_max,
            "minDuration": min_duration, "maxDuration": max_duration,
            "timeOfDay": time_of_day,
            "hostLanguages": host_languages,
            "accessibilityFeatures": accessibility_features,
        })

    def search_experiences_by_place_id(self, place_id, check_in=None,
                                        check_out=None, adults=None,
                                        children=None, infants=None,
                                        next_page_cursor=None,
                                        experience_type=None,
                                        traveler_type=None,
                                        price_min=None, price_max=None,
                                        min_duration=None, max_duration=None,
                                        time_of_day=None,
                                        host_languages=None,
                                        accessibility_features=None):
        """
        Search Airbnb experiences by Google Place ID.

        Args:
            place_id (str): Google Place ID.
                Example: "ChIJpTvG15DL1IkRd8S0KlBVNTI"
            (All other args same as search_experiences_by_destination)

        Returns:
            dict: Experience search results
        """
        return self._get("/search/exp/byplaceid", {
            "placeId": place_id,
            "checkIn": check_in, "checkOut": check_out,
            "adults": adults, "children": children, "infants": infants,
            "nextPageCursor": next_page_cursor,
            "experienceType": experience_type,
            "travelerType": traveler_type,
            "pricePerGuest_min": price_min,
            "pricePerGuest_max": price_max,
            "minDuration": min_duration, "maxDuration": max_duration,
            "timeOfDay": time_of_day,
            "hostLanguages": host_languages,
            "accessibilityFeatures": accessibility_features,
        })

    # ─────────────────────────────────────────────
    # 3. Search Services
    # ─────────────────────────────────────────────

    def search_services_by_destination(self, destination, check_in, check_out,
                                        type_of_service, next_page_cursor=None,
                                        price_min=None, price_max=None,
                                        min_duration=None, max_duration=None,
                                        time_of_day=None,
                                        host_languages=None,
                                        accessibility_features=None):
        """
        Search Airbnb services by destination.

        Args:
            destination (str): Location. Example: "toronto, canada"
            check_in (str): Check-in date YYYY-MM-DD
            check_out (str): Check-out date YYYY-MM-DD
            type_of_service (str): Photography, Prepared_Meals, Training,
                Makeup, Hair, Spa_Treatment, Catering, Nails, Chefs
            next_page_cursor (str): Pagination cursor
            price_min (int): Min price per guest
            price_max (int): Max price per guest
            min_duration (int): Min duration in minutes (30,45,60,90,120,180)
            max_duration (int): Max duration in minutes (45,60,90,120,180)
            time_of_day (str): morning, afternoon, evening
            host_languages (str): Comma-separated language codes
            accessibility_features (str): Accessibility filters

        Returns:
            dict: Service search results
        """
        return self._get("/search/services/bydestination", {
            "searchDestinations": destination,
            "checkIn": check_in, "checkOut": check_out,
            "typeOfService": type_of_service,
            "nextPageCursor": next_page_cursor,
            "pricePerGuest_min": price_min,
            "pricePerGuest_max": price_max,
            "minDuration": min_duration, "maxDuration": max_duration,
            "timeOfDay": time_of_day,
            "hostLanguages": host_languages,
            "accessibilityFeatures": accessibility_features,
        })

    # ─────────────────────────────────────────────
    # 4. Autocomplete
    # ─────────────────────────────────────────────

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

        Args:
            keyword (str): Search keyword. Example: "paris"
            language_code (str): Language code. Example: "en-US"

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

    # ─────────────────────────────────────────────
    # 5. Home Details
    # ─────────────────────────────────────────────

    def get_home_details(self, stay_listing_id, check_in, check_out):
        """
        Get detailed home/listing information.

        Args:
            stay_listing_id (str): Listing ID from search results
                (searchResults > listing > id).
            check_in (str): Check-in date YYYY-MM-DD
            check_out (str): Check-out date YYYY-MM-DD

        Returns:
            dict: Full home details
        """
        return self._get("/home/details", {
            "stayListingId": stay_listing_id,
            "checkIn": check_in,
            "checkOut": check_out,
        })

    def get_home_reviews(self, stay_listing_id, offset=None,
                         review_limit=None, sorting_preference=None):
        """
        Get home reviews.

        Args:
            stay_listing_id (str): Listing ID from search results
            offset (str): Start index (default 0)
            review_limit (str): Number of reviews (default 20)
            sorting_preference (str): most_relevant, highest_rated,
                lowest_rated, most_recent

        Returns:
            dict: Home reviews
        """
        return self._get("/home/reviews", {
            "stayListingId": stay_listing_id,
            "offset": offset,
            "reviewLimit": review_limit,
            "sortingPreference": sorting_preference,
        })

    def get_home_availability(self, listing_id):
        """
        Get home availability calendar.

        Args:
            listing_id (str): The productId from home details
                (baseData > metadata > clientLoggingContext > productId).
                Example: "868126372367701281"

        Returns:
            dict: Availability calendar data
        """
        return self._get("/home/availability", {"listingId": listing_id})

    # ─────────────────────────────────────────────
    # 6. Experience Details
    # ─────────────────────────────────────────────

    def get_experience_details(self, experience_listing_id):
        """
        Get experience details.

        Args:
            experience_listing_id (str): Experience ID from search results.
                Example: "QWN0aXZpdHlMaXN0aW5nOjMxMDk1ODQ="

        Returns:
            dict: Full experience details
        """
        return self._get("/experience/details", {
            "experienceListingId": experience_listing_id,
        })

    def get_experience_reviews(self, experience_listing_id, offset=None,
                                review_limit=None, sorting_preference=None):
        """
        Get experience reviews.

        Args:
            experience_listing_id (str): Experience ID from search
            offset (str): Start index (default 0)
            review_limit (str): Number of reviews (default 20)
            sorting_preference (str): most_relevant, highest_rated,
                lowest_rated, most_recent

        Returns:
            dict: Experience reviews
        """
        return self._get("/experience/reviews", {
            "experienceListingId": experience_listing_id,
            "offset": offset,
            "reviewLimit": review_limit,
            "sortingPreference": sorting_preference,
        })

    def get_experience_availability(self, experience_listing_id,
                                     start_date, end_date):
        """
        Get experience availability.

        Args:
            experience_listing_id (str): Experience ID
            start_date (str): Start date YYYY-MM-DD
            end_date (str): End date YYYY-MM-DD

        Returns:
            dict: Availability data
        """
        return self._get("/experience/availability", {
            "experienceListingId": experience_listing_id,
            "startDate": start_date,
            "endDate": end_date,
        })

    # ─────────────────────────────────────────────
    # 7. Service Details
    # ─────────────────────────────────────────────

    def get_service_details(self, service_listing_id):
        """
        Get service details.

        Args:
            service_listing_id (str): Service ID from search results.
                Example: "QWN0aXZpdHlMaXN0aW5nOjYwNjcyNzE="

        Returns:
            dict: Full service details
        """
        return self._get("/service/details", {
            "serviceListingId": service_listing_id,
        })

    def get_service_reviews(self, service_listing_id, offset=None,
                             review_limit=None, sorting_preference=None):
        """
        Get service reviews.

        Args:
            service_listing_id (str): Service ID from search
            offset (str): Start index (default 0)
            review_limit (str): Number of reviews (default 20)
            sorting_preference (str): most_recent, highest_rated, lowest_rated

        Returns:
            dict: Service reviews
        """
        return self._get("/service/reviews", {
            "serviceListingId": service_listing_id,
            "offset": offset,
            "reviewLimit": review_limit,
            "sortingPreference": sorting_preference,
        })

    # ─────────────────────────────────────────────
    # 8. Filters & Reference Data
    # ─────────────────────────────────────────────

    def get_categories(self, language_code=None):
        """Get all Airbnb categories (Countryside, Beachfront, etc.)."""
        return self._get("/categories", {"language_code": language_code})

    def get_amenities_filter(self, language_code=None):
        """Get all amenity IDs for search filter."""
        return self._get("/filter/amenities", {"language_code": language_code})

    def get_property_types_filter(self, language_code=None):
        """Get all property types for search filter."""
        return self._get("/filter/property_types", {"language_code": language_code})

    def get_accessibility_filter(self, language_code=None):
        """Get all accessibility feature IDs for search filter."""
        return self._get("/filter/accessibility", {"language_code": language_code})

    def get_host_language_filter(self):
        """Get all host language codes for search filter."""
        return self._get("/filter/host_language")

    def get_currencies(self):
        """Get all available currency codes."""
        return self._get("/currencies")

    def get_language_codes(self):
        """Get all available language codes."""
        return self._get("/language_codes")