### Install PyAirbnb

Source: https://github.com/johnbalvin/pyairbnb/blob/main/README.md

Install the pyairbnb package using pip. This is the first step before using the library.

```bash
pip install pyairbnb
```

--------------------------------

### Example: Fetching Host Listings

Source: https://github.com/johnbalvin/pyairbnb/blob/main/_autodocs/api-reference/host.md

Demonstrates how to retrieve and save a host's listings to a JSON file.

```python
import pyairbnb
import json

api_key = pyairbnb.get_api_key("")
listings = pyairbnb.get_listings_from_user(
    host_id=656454528,
    api_key=api_key,
    proxy_url=""
)

with open('listings.json', 'w', encoding='utf-8') as f:
    json.dump(listings, f, indent=2)

print(f"Host has {len(listings)} listings")
```

--------------------------------

### Retrieve listing details

Source: https://github.com/johnbalvin/pyairbnb/blob/main/_autodocs/api-reference/details.md

Examples of fetching listing data with and without pricing parameters.

```python
import pyairbnb

# Get full details with pricing
data = pyairbnb.get_details(
    room_url="https://www.airbnb.com/rooms/21734211",
    check_in="2026-05-12",
    check_out="2026-05-17",
    currency="USD",
    adults=2,
    language="en"
)

print(f"Title: {data['title']}")
print(f"Host: {data['host']['name']}")
print(f"Price: ${data['price']['main']['price']}")
print(f"Reviews: {data['reviews']}")

# Get details without pricing
data_no_price = pyairbnb.get_details(
    room_id=856200458932468228,
    currency="MXN",
    language="ko"
)

print(f"Available from calendar: {len(data_no_price['calendar'])} months")
```

--------------------------------

### Example: Fetching Host Profile

Source: https://github.com/johnbalvin/pyairbnb/blob/main/_autodocs/api-reference/host.md

Shows how to use session data from a listing fetch to retrieve detailed host profile information.

```python
import pyairbnb
import json

api_key = pyairbnb.get_api_key("")

# Get host details using data from get_details
data = pyairbnb.get_details(
    room_url="https://www.airbnb.com/rooms/123456",
    currency="USD"
)

host_id = data["host"]["id"]
host_details = pyairbnb.get_host_details(
    api_key=api_key,
    cookies=data.get("_cookies"),
    host_id=host_id,
    language="en",
    proxy_url=""
)

with open('host_profile.json', 'w', encoding='utf-8') as f:
    json.dump(host_details, f, indent=2)
```

--------------------------------

### Configure Search Timeouts

Source: https://github.com/johnbalvin/pyairbnb/blob/main/_autodocs/configuration.md

Examples of applying different timeout strategies to search_all operations.

```python
import pyairbnb

# Uses DEFAULT_TIMEOUT (60 seconds)
results = pyairbnb.search_all(
    check_in="2025-10-01",
    check_out="2025-10-04",
    ne_lat=10.0,
    ne_long=10.0,
    sw_lat=9.0,
    sw_long=9.0,
    zoom_value=2,
    price_min=100,
    price_max=1000
)
```

```python
import pyairbnb

# 30-second timeout for all operations
results = pyairbnb.search_all(..., timeout=30)
```

```python
import pyairbnb

# 5 seconds to establish connection, 60 seconds to read response
results = pyairbnb.search_all(..., timeout=(5, 60))
```

```python
import pyairbnb

# Disable timeout (not recommended for production)
results = pyairbnb.search_all(..., timeout=None)
```

```python
import pyairbnb

# 2.5 second timeout
results = pyairbnb.search_all(..., timeout=2.5)
```

--------------------------------

### Example Usage of experience_search_by_place_id

Source: https://github.com/johnbalvin/pyairbnb/blob/main/_autodocs/api-reference/experiences.md

Demonstrates how to retrieve place IDs and perform manual pagination to fetch all experiences for a specific location.

```python
import pyairbnb

api_key = pyairbnb.get_api_key("")
markets_data = pyairbnb.get_markets("USD", "en", api_key, "")
markets = pyairbnb.get_nested_value(markets_data, "user_markets", [])

config_token = pyairbnb.get_nested_value(markets[0], "satori_parameters", "")
country_code = pyairbnb.get_nested_value(markets[0], "country_code", "")

place_ids_results = pyairbnb.get_places_ids(
    country_code,
    "cuenca",
    "USD",
    "en",
    config_token,
    api_key,
    ""
)

place_id = pyairbnb.get_nested_value(place_ids_results[0], "location.google_place_id", "")
location_name = pyairbnb.get_nested_value(place_ids_results[0], "location.location_name", "")

# Manual pagination
all_experiences = []
cursor = ""

while True:
    experiences, cursor = pyairbnb.experience_search_by_place_id(
        cursor,
        place_id,
        location_name,
        "USD",
        "en",
        "2026-05-10",
        "2026-05-12",
        api_key,
        ""
    )
    
    if not experiences:
        break
    
    all_experiences.extend(experiences)
    
    if not cursor:
        break

print(f"Total experiences: {len(all_experiences)}")
```

--------------------------------

### Get Reviews

Source: https://github.com/johnbalvin/pyairbnb/blob/main/_autodocs/QUICK_START.md

Retrieve reviews for a specific listing URL.

```python
reviews = pyairbnb.get_reviews(
    room_url="https://www.airbnb.com/rooms/123456",
    language="en"
)

print(f"Found {len(reviews)} reviews")
```

--------------------------------

### Execute search_all query

Source: https://github.com/johnbalvin/pyairbnb/blob/main/_autodocs/api-reference/search.md

Example usage of the search_all function to retrieve listings and iterate through the results.

```python
import pyairbnb

results = pyairbnb.search_all(
    check_in="2025-10-01",
    check_out="2025-10-04",
    ne_lat=-0.6747456399483214,
    ne_long=-90.30058677891441,
    sw_lat=-0.7596840340260731,
    sw_long=-90.36727562895442,
    zoom_value=2,
    price_min=1000,
    price_max=5000,
    place_type="Entire home/apt",
    amenities=[4, 7],
    currency="MXN",
    language="es",
    timeout=30
)

for listing in results:
    print(f"{listing['title']}: ${listing['price']['unit']['amount']}")
```

--------------------------------

### Check package version

Source: https://github.com/johnbalvin/pyairbnb/blob/main/_autodocs/EXPORT_MAP.md

Verify the installed version of the pyairbnb package.

```python
# Check package version
import pyairbnb
# Available in pyproject.toml: version = '2.2.0'
```

--------------------------------

### Retrieve and handle listing pricing

Source: https://github.com/johnbalvin/pyairbnb/blob/main/_autodocs/api-reference/pricing.md

Example usage of get_price to fetch pricing data and handle potential unavailability errors.

```python
import pyairbnb
from datetime import date

# Get pricing with breakdown
price_data = pyairbnb.get_price(
    room_id="1316896675409654026",
    check_in=date(2026, 2, 4),
    check_out=date(2026, 2, 7),
    adults=2,
    currency="USD",
    language="en",
    timeout=30
)

if price_data:
    main_price = price_data["main"]
    print(f"Total: {main_price['price']}")
    print(f"Original: {main_price['originalPrice']}")
    
    # Print breakdown
    for description, amount in main_price["details"].items():
        print(f"{description}: {amount}")

# Handle unavailability
try:
    price_data = pyairbnb.get_price(
        room_id="123456789",
        check_in=date(2026, 1, 1),
        check_out=date(2026, 1, 5)
    )
except pyairbnb.UnavailableError as e:
    print(f"Listing unavailable: {e}")
```

--------------------------------

### Get Pricing

Source: https://github.com/johnbalvin/pyairbnb/blob/main/_autodocs/QUICK_START.md

Fetch pricing information for a specific room ID and date range.

```python
from datetime import date

price = pyairbnb.get_price(
    room_id="123456",
    check_in=date(2025, 5, 12),
    check_out=date(2025, 5, 17),
    adults=2,
    currency="USD"
)

print(price['main']['price'])
print(price['main']['details'])
```

--------------------------------

### Get Host Listings

Source: https://github.com/johnbalvin/pyairbnb/blob/main/_autodocs/QUICK_START.md

Retrieve all listings associated with a specific host ID.

```python
api_key = pyairbnb.get_api_key()

listings = pyairbnb.get_listings_from_user(
    host_id=656454528,
    api_key=api_key,
    proxy_url=""
)

print(f"Host has {len(listings)} listings")
```

--------------------------------

### Get Host Details

Source: https://github.com/johnbalvin/pyairbnb/blob/main/_autodocs/QUICK_START.md

Retrieve host information either from existing listing data or directly using an API key.

```python
api_key = pyairbnb.get_api_key()

# From existing listing data
data = pyairbnb.get_details(room_id=123456)
host_details = data['host_details']

# Or directly
host_details = pyairbnb.get_host_details(
    api_key=api_key,
    cookies=None,
    host_id="host_id_string",
    language="en",
    proxy_url=""
)
```

--------------------------------

### Get Listing Details

Source: https://github.com/johnbalvin/pyairbnb/blob/main/_autodocs/QUICK_START.md

Retrieve detailed information for a specific listing using either a URL or a room ID.

```python
data = pyairbnb.get_details(
    room_url="https://www.airbnb.com/rooms/123456",
    check_in="2025-05-12",
    check_out="2025-05-17",
    currency="USD",
    adults=2,
    language="en"
)

print(data['title'])
print(data['host']['name'])
print(data['rating']['value'])
```

```python
data = pyairbnb.get_details(
    room_id=123456,
    check_in="2025-05-12",
    check_out="2025-05-17"
)
```

--------------------------------

### Search Experiences Using Autocompletions

Source: https://github.com/johnbalvin/pyairbnb/blob/main/README.md

Searches for Airbnb experiences by first obtaining autocompletions to get market and place IDs. This method is useful when the exact location name might be ambiguous. It requires check-in/out dates, currency, locale, API key, and an optional proxy URL. Results are paginated and saved to 'experiences.json'.

```Python
import pyairbnb
import json
check_in = "2026-05-06"
check_out = "2026-05-10"
currency = "USD"
user_input_text = "cuenca"
locale = "pt"
proxy_url = ""  # Proxy URL (if needed)
api_key = pyairbnb.get_api_key("")
markets_data = pyairbnb.get_markets(currency,locale,api_key,proxy_url)
markets = pyairbnb.get_nested_value(markets_data,"user_markets", [])
if len(markets)==0:
    raise Exception("markets are empty")
config_token = pyairbnb.get_nested_value(markets[0],"satori_parameters", "")
country_code = pyairbnb.get_nested_value(markets[0],"country_code", "")
if config_token=="" or country_code=="":
    raise Exception("config_token or country_code are empty")
place_ids_results = pyairbnb.get_places_ids(country_code, user_input_text, currency, locale, config_token, api_key, proxy_url)
if len(place_ids_results)==0:
    raise Exception("empty places ids")
place_id = pyairbnb.get_nested_value(place_ids_results[0],"location.google_place_id", "")
location_name = pyairbnb.get_nested_value(place_ids_results[0],"location.location_name", "")
if place_id=="" or location_name=="":
    raise Exception("place_id or location_name are empty")
[result,cursor] = pyairbnb.experience_search_by_place_id("", place_id, location_name, currency, locale, check_in, check_out, api_key, proxy_url)
while cursor!="":
    [result_tmp,cursor] = pyairbnb.experience_search_by_place_id(cursor, place_id, location_name, currency, locale, check_in, check_out, api_key, proxy_url)
    if len(result_tmp)==0:
        break
    result = result + result_tmp
with open('experiences.json', 'w', encoding='utf-8') as f:
    f.write(json.dumps(result))
```

--------------------------------

### Get Listing Details by URL

Source: https://github.com/johnbalvin/pyairbnb/blob/main/README.md

Retrieves detailed information about an Airbnb listing using its URL. Allows specifying currency, check-in/out dates, number of adults, and language. The retrieved data is saved to 'details_data.json'.

```Python
import pyairbnb
import json

# Define listing URL and parameters
room_url = "https://www.airbnb.com/rooms/21734211"  # Listing URL
currency = "USD"  # Currency for the listing details
checkin = "2026-05-12"
checkout = "2026-05-17"
# Retrieve listing details without including the price information (no check-in/check-out dates)
data = pyairbnb.get_details(room_url=room_url, currency=currency,adults=2, language="ja")

# Save the retrieved details to a JSON file
with open('details_data.json', 'w', encoding='utf-8') as f:
    f.write(json.dumps(data))  # Convert the data to JSON and save it
```

--------------------------------

### Get Listings from User

Source: https://github.com/johnbalvin/pyairbnb/blob/main/README.md

Retrieves a list of all listings associated with a given Airbnb host user ID. Requires the host ID and an API key. Accepts an optional proxy URL.

```APIDOC
## get_listings_from_user

### Description
Retrieves all listings associated with a specific Airbnb host user ID.

### Method
`pyairbnb.get_listings_from_user`

### Parameters
- `host_id` (int) - Required - The ID of the Airbnb host.
- `api_key` (str) - Required - The API key for authentication.
- `proxy_url` (str) - Optional - URL for a proxy server.

### Request Example
```python
import pyairbnb

host_id = 656454528
api_key = pyairbnb.get_api_key("") # Assuming get_api_key can fetch or is provided
listings = pyairbnb.get_listings_from_user(host_id, api_key, "")
```
```

--------------------------------

### Get Host Details

Source: https://github.com/johnbalvin/pyairbnb/blob/main/README.md

Retrieves detailed information about an Airbnb host, including their listings and profile details. Requires the host ID, an API key, and optionally a language and proxy URL.

```APIDOC
## get_host_details

### Description
Retrieves detailed information about an Airbnb host.

### Method
`pyairbnb.get_host_details`

### Parameters
- `api_key` (str) - Required - The API key for authentication.
- `None` - Placeholder for an unspecified parameter, potentially related to authentication or session.
- `host_id` (str) - Required - The ID of the Airbnb host.
- `language` (str) - Optional - The language for the returned details.
- `proxy_url` (str) - Optional - URL for a proxy server.

### Request Example
```python
import pyairbnb

host_id = "656454528"
language = "en"
api_key = pyairbnb.get_api_key("") # Assuming get_api_key can fetch or is provided
listings = pyairbnb.get_host_details(api_key, None, host_id, language, "")
```
```

--------------------------------

### Get Calendar Availability

Source: https://github.com/johnbalvin/pyairbnb/blob/main/_autodocs/QUICK_START.md

Get the availability calendar for a specific room ID.

```python
calendar = pyairbnb.get_calendar(
    room_id="123456"
)

print(f"Calendar data for {len(calendar)} months")
```

--------------------------------

### Typical PyAirbnb Workflow

Source: https://github.com/johnbalvin/pyairbnb/blob/main/_autodocs/00_START_HERE.md

Demonstrates the standard sequence of operations for searching listings, retrieving details, and checking pricing.

```python
import pyairbnb

# 1. Search listings
results = pyairbnb.search_all(...)

# 2. Get details
data = pyairbnb.get_details(...)

# 3. Check pricing
price = pyairbnb.get_price(...)
```

--------------------------------

### Perform full search and details retrieval

Source: https://github.com/johnbalvin/pyairbnb/blob/main/_autodocs/QUICK_START.md

Demonstrates the complete workflow of initializing the API, searching for listings, and fetching specific details for a listing.

```python
import pyairbnb
from datetime import date
import json

# Initialize
api_key = pyairbnb.get_api_key()

# Search
results = pyairbnb.search_all(
    check_in="2025-10-01",
    check_out="2025-10-04",
    ne_lat=10.0,
    ne_long=10.0,
    sw_lat=9.0,
    sw_long=9.0,
    zoom_value=2,
    price_min=100,
    price_max=5000,
    currency="USD"
)

print(f"Found {len(results)} listings")

# Get details for first listing
if results:
    first_room_id = results[0]['room_id']
    
    details = pyairbnb.get_details(
        room_id=first_room_id,
        check_in=date(2025, 10, 1),
        check_out=date(2025, 10, 4),
        currency="USD"
    )
    
    print(f"Title: {details['title']}")
    print(f"Host: {details['host']['name']}")
    print(f"Price: {details['price']['main']['price']}")
    print(f"Reviews: {len(details['reviews'])}")
    
    # Save full details
    with open('listing_details.json', 'w') as f:
        json.dump(details, f, indent=2)
```

--------------------------------

### Configure proxy with authentication

Source: https://github.com/johnbalvin/pyairbnb/blob/main/_autodocs/00_START_HERE.md

Sets up a proxy connection using credentials before passing it to search functions.

```python
import pyairbnb

proxy = pyairbnb.parse_proxy(
    ip_or_domain="proxy.example.com",
    port="8080",
    username="user",
    password="pass"
)

results = pyairbnb.search_all(..., proxy_url=proxy)
```

--------------------------------

### Retrieve pricing via get_details

Source: https://github.com/johnbalvin/pyairbnb/blob/main/_autodocs/api-reference/pricing.md

Demonstrates how get_details automatically includes pricing information when check-in and check-out dates are provided.

```python
import pyairbnb

# get_details includes pricing when dates are provided
data = pyairbnb.get_details(
    room_url="https://www.airbnb.com/rooms/123456",
    check_in="2026-05-12",
    check_out="2026-05-17",
    currency="USD"
)

# Price is automatically included in the response
if "price" in data:
    print(data["price"])
```

--------------------------------

### Raw API Request Parameters

Source: https://github.com/johnbalvin/pyairbnb/blob/main/_autodocs/types.md

Structure and example usage for filter parameters in search API requests.

```python
[
    {
        "filterName": str,          # Filter identifier (e.g., "checkin", "price_min")
        "filterValues": list[str],  # String values for the filter
    }
]
```

```python
[
    {"filterName": "checkin", "filterValues": ["2025-10-01"]},
    {"filterName": "checkout", "filterValues": ["2025-10-04"]},
    {"filterName": "price_min", "filterValues": ["1000"]},
    {"filterName": "amenities", "filterValues": ["4", "7"]},
]
```

--------------------------------

### Handle UnavailableError during price retrieval

Source: https://github.com/johnbalvin/pyairbnb/blob/main/_autodocs/api-reference/pricing.md

Example of catching the UnavailableError exception when calling get_price with specific dates.

```python
import pyairbnb
from datetime import date

try:
    price = pyairbnb.get_price(
        room_id="12345",
        check_in=date(2026, 1, 1),
        check_out=date(2026, 1, 5)
    )
except pyairbnb.UnavailableError as e:
    print(f"Cannot book: {str(e)}")
```

--------------------------------

### Perform an experience search

Source: https://github.com/johnbalvin/pyairbnb/blob/main/_autodocs/api-reference/experiences.md

Demonstrates how to search for experiences and save the results to a JSON file.

```python
import pyairbnb
import json

api_key = pyairbnb.get_api_key("")

experiences = pyairbnb.experience_search(
    user_input_text="Estados Unidos",
    currency="EUR",
    locale="es",
    check_in="2026-05-10",
    check_out="2026-05-12",
    api_key=api_key,
    proxy_url=""
)

with open('experiences.json', 'w', encoding='utf-8') as f:
    json.dump(experiences, f, indent=2)

print(f"Found {len(experiences)} experiences")
```

--------------------------------

### Import and use pyairbnb functions

Source: https://github.com/johnbalvin/pyairbnb/blob/main/_autodocs/EXPORT_MAP.md

Directly import the package to access public functions like search_all.

```python
import pyairbnb

# Example
result = pyairbnb.search_all(...)
```

--------------------------------

### Import PyAirbnb

Source: https://github.com/johnbalvin/pyairbnb/blob/main/_autodocs/QUICK_START.md

Import the library into your Python project.

```python
import pyairbnb
```

--------------------------------

### Configure Proxy Settings

Source: https://github.com/johnbalvin/pyairbnb/blob/main/_autodocs/QUICK_START.md

Define proxy URLs directly or use the parse_proxy helper for authenticated connections.

```python
# Simple proxy
proxy_url="http://proxy.example.com:8080"

# With authentication
proxy_url = pyairbnb.parse_proxy(
    ip_or_domain="proxy.example.com",
    port="8080",
    username="user",
    password="pass"
)
```

--------------------------------

### Import Timeout Utility

Source: https://github.com/johnbalvin/pyairbnb/blob/main/_autodocs/configuration.md

Import the Timeout utility class for type hinting or configuration.

```python
from pyairbnb.utils import Timeout
```

--------------------------------

### Get Price

Source: https://github.com/johnbalvin/pyairbnb/blob/main/README.md

Retrieves the price for a specific Airbnb room for a given date range. Requires the room ID and check-in/check-out dates. Accepts an optional timeout argument.

```APIDOC
## get_price

### Description
Retrieves the price for a specific Airbnb room for a given date range.

### Method
`pyairbnb.get_price`

### Parameters
- `room_id` (str) - Required - The ID of the Airbnb room.
- `check_in` (date) - Required - The check-in date.
- `check_out` (date) - Required - The check-out date.
- `timeout` (int or float or tuple or None) - Optional - Timeout for the request. Defaults to 60 seconds.

### Request Example
```python
from datetime import date
import pyairbnb

data = pyairbnb.get_price(
    room_id="1316896675409654026",
    check_in=date(2026, 2, 4),
    check_out=date(2026, 2, 7),
    timeout=30
)
```
```

--------------------------------

### Search Experiences

Source: https://github.com/johnbalvin/pyairbnb/blob/main/_autodocs/QUICK_START.md

Search for Airbnb experiences based on location and date criteria.

```python
api_key = pyairbnb.get_api_key()

experiences = pyairbnb.experience_search(
    user_input_text="Paris",
    currency="EUR",
    locale="en",
    check_in="2025-05-10",
    check_out="2025-05-12",
    api_key=api_key,
    proxy_url=""
)

for exp in experiences:
    print(f"{exp['title']}: ${exp['price']['amount']}")
```

--------------------------------

### Configure Airbnb Domain

Source: https://github.com/johnbalvin/pyairbnb/blob/main/_autodocs/configuration.md

Specify the target Airbnb domain for room detail requests. Defaults to www.airbnb.com if not provided.

```python
import pyairbnb

# Use UK domain
data = pyairbnb.get_details(
    room_id=123456,
    domain="www.airbnb.co.uk"
)

# Use EU domain
data = pyairbnb.get_details(
    room_id=123456,
    domain="www.airbnb.ie"
)

# Default is www.airbnb.com
data = pyairbnb.get_details(
    room_id=123456
    # domain="www.airbnb.com"  # implicit
)
```

--------------------------------

### Get Details for a Specific Airbnb Host

Source: https://github.com/johnbalvin/pyairbnb/blob/main/README.md

Retrieve detailed information about an Airbnb host using their ID. Supports specifying the desired language and optionally accepts a proxy URL. The results are saved to a JSON file.

```python
import pyairbnb
import json
host_id = "656454528"
language = "en"
api_key = pyairbnb.get_api_key("")
listings = pyairbnb.get_host_details(api_key, None, host_id, language, "")
with open('listings.json', 'w', encoding='utf-8') as f:
    f.write(json.dumps(listings))

```

--------------------------------

### pyairbnb.get_details

Source: https://github.com/johnbalvin/pyairbnb/blob/main/_autodocs/api-reference/pricing.md

Retrieves full listing details, including pricing if dates are provided.

```APIDOC
## get_details(room_url, check_in, check_out, currency)

### Description
Fetches comprehensive details for a listing. If check-in and check-out dates are provided, it automatically includes pricing information in the response.

### Parameters
- **room_url** (string) - Required - The URL of the Airbnb listing.
- **check_in** (string) - Optional - The start date in YYYY-MM-DD format.
- **check_out** (string) - Optional - The end date in YYYY-MM-DD format.
- **currency** (string) - Optional - The currency code for the price.
```

--------------------------------

### Get Listings from a Specific Airbnb Host

Source: https://github.com/johnbalvin/pyairbnb/blob/main/README.md

Retrieve a list of all listings associated with a given Airbnb host ID. Requires an API key and optionally accepts a proxy URL. The results are saved to a JSON file.

```python
import pyairbnb
import json
host_id = 656454528
api_key = pyairbnb.get_api_key("")
listings = pyairbnb.get_listings_from_user(host_id,api_key,"")
with open('listings.json', 'w', encoding='utf-8') as f:
    f.write(json.dumps(listings))

```

--------------------------------

### Fetch first page of search results

Source: https://github.com/johnbalvin/pyairbnb/blob/main/_autodocs/api-reference/search.md

Retrieves the initial page of listings without pagination. Requires geographic bounds and date parameters.

```python
def search_first_page(
    check_in: str,
    check_out: str,
    ne_lat: float,
    ne_long: float,
    sw_lat: float,
    sw_long: float,
    zoom_value: int,
    price_min: int,
    price_max: int,
    place_type: str = "",
    amenities: list = [],
    free_cancellation: bool = False,
    adults: int = 0,
    children: int = 0,
    infants: int = 0,
    min_bedrooms: int = 0,
    min_beds: int = 0,
    min_bathrooms: int = 0,
    currency: str = "USD",
    language: str = "en",
    proxy_url: str = "",
    hash: str = "",
    timeout: Timeout = DEFAULT_TIMEOUT
) -> list
```

```python
import pyairbnb

first_page = pyairbnb.search_first_page(
    check_in="2025-10-01",
    check_out="2025-10-04",
    ne_lat=49.76537,
    ne_long=6.56057,
    sw_lat=49.31155,
    sw_long=6.03263,
    zoom_value=10,
    price_min=100,
    price_max=500,
    currency="EUR",
    language="en"
)

print(f"Found {len(first_page)} listings on first page")
```

--------------------------------

### Get Listing Details by Room ID with Proxy

Source: https://github.com/johnbalvin/pyairbnb/blob/main/README.md

Retrieves detailed information about an Airbnb listing using its room ID. Supports specifying currency, language, number of adults, and an optional proxy URL. The results are saved to 'details_data.json'.

```Python
import pyairbnb
from urllib.parse import urlparse
import json

# Define listing parameters
room_id = 856200458932468228  # Listing room ID
currency = "MXN"  # Currency for the listing details
proxy_url = ""  # Proxy URL (if needed)

# Retrieve listing details by room ID with a proxy
checkin = "2026-05-12"
checkout = "2026-05-17"
data = pyairbnb.get_details(room_id=room_id, currency=currency, proxy_url=proxy_url,adults=3, language="ko")

# Save the retrieved details to a JSON file
with open('details_data.json', 'w', encoding='utf-8') as f:
    f.write(json.dumps(data))  # Convert the data to JSON and save it
```

--------------------------------

### Get Price for a Specific Airbnb Room

Source: https://github.com/johnbalvin/pyairbnb/blob/main/README.md

Retrieve the price for a specific Airbnb room by providing its ID and the desired check-in and check-out dates. The date range is crucial for accurate pricing due to recent Airbnb changes. Uses the `datetime.date` object for dates.

```python
import pyairbnb
from datetime import date

data = pyairbnb.get_price(
    room_id="1316896675409654026",
    check_in=date(2026, 2, 4),
    check_out=date(2026, 2, 7),
    timeout=30,
)

```

--------------------------------

### Perform Advanced Manual Pagination Search

Source: https://github.com/johnbalvin/pyairbnb/blob/main/_autodocs/api-reference/experiences.md

Retrieves experiences by manually handling market configuration, place ID resolution, and cursor-based pagination.

```python
# Step 1: Get market configuration
markets = pyairbnb.get_markets(currency, locale, api_key, proxy_url)
market = markets["user_markets"][0]
config_token = market["satori_parameters"]
country_code = market["country_code"]

# Step 2: Get place IDs
places = pyairbnb.get_places_ids(
    country_code,
    "paris",
    currency,
    locale,
    config_token,
    api_key,
    proxy_url
)
place = places[0]
place_id = place["location"]["google_place_id"]
location_name = place["location"]["location_name"]

# Step 3: Manually paginate
cursor = ""
all_exp = []
while True:
    exp, cursor = pyairbnb.experience_search_by_place_id(
        cursor, place_id, location_name,
        currency, locale, check_in, check_out,
        api_key, proxy_url
    )
    all_exp.extend(exp)
    if not cursor:
        break
```

--------------------------------

### Configure Manual Proxy URL in Python

Source: https://github.com/johnbalvin/pyairbnb/blob/main/_autodocs/configuration.md

Pass a proxy URL directly to search functions to route HTTP/HTTPS requests.

```python
import pyairbnb

results = pyairbnb.search_all(
    ...,
    proxy_url="http://proxy.example.com:8080"
)
```

--------------------------------

### pyairbnb.get_listings_from_user

Source: https://github.com/johnbalvin/pyairbnb/blob/main/_autodocs/QUICK_START.md

Retrieves all listings associated with a specific host.

```APIDOC
## pyairbnb.get_listings_from_user

### Description
Returns a list of all active listings for a given host ID.

### Parameters
- **host_id** (int) - Required - Host identifier
- **api_key** (string) - Required - Authentication key
- **proxy_url** (string) - Optional - Proxy configuration
```

--------------------------------

### Import and use pyairbnb

Source: https://github.com/johnbalvin/pyairbnb/blob/main/_autodocs/00_START_HERE.md

Basic import statement and usage pattern for library functions.

```python
import pyairbnb

# Use any function
result = pyairbnb.search_all(...)
```

--------------------------------

### Accessing Host Details via get_details

Source: https://github.com/johnbalvin/pyairbnb/blob/main/_autodocs/api-reference/host.md

Shows how host details are automatically included when using the primary get_details function.

```python
import pyairbnb

data = pyairbnb.get_details(
    room_id=123456,
    currency="USD"
)

# Host details are automatically included
host_details = data["host_details"]
```

--------------------------------

### get_details

Source: https://github.com/johnbalvin/pyairbnb/blob/main/_autodocs/EXPORT_MAP.md

Retrieves detailed information for a specific Airbnb listing.

```APIDOC
## get_details(room_url=None, room_id=None, domain="www.airbnb.com", check_in=None, check_out=None, adults=1, currency="USD", language="en", proxy_url="", timeout=60)

### Description
Fetches comprehensive details for a listing using either a URL or a room ID.

### Returns
dict
```

--------------------------------

### get_reviews

Source: https://github.com/johnbalvin/pyairbnb/blob/main/_autodocs/api-reference/details.md

Retrieves all guest reviews for a specified Airbnb listing.

```APIDOC
## get_reviews(room_url, language="en", proxy_url="", timeout=60)

### Description
Retrieves all guest reviews for a specified listing.

### Parameters
- **room_url** (str) - Required - Full Airbnb listing URL
- **language** (str) - Optional - Language code (default: "en")
- **proxy_url** (str) - Optional - HTTP proxy URL (default: "")
- **timeout** (Timeout) - Optional - Request timeout in seconds (default: 60)

### Return Type
- **list** - Array of review objects containing author information, rating, text content, and metadata.

### Example
```python
import pyairbnb
reviews_data = pyairbnb.get_reviews("https://www.airbnb.com/rooms/30931885", language="fr", proxy_url="")
```
```

--------------------------------

### Retrieve market configuration data

Source: https://github.com/johnbalvin/pyairbnb/blob/main/_autodocs/api-reference/search.md

Fetches market configuration details including satori parameters and country codes for a specified currency and locale.

```python
def get_markets(
    currency: str,
    locale: str,
    api_key: str,
    proxy_url: str,
    timeout: Timeout = DEFAULT_TIMEOUT
) -> dict
```

```python
import pyairbnb

api_key = pyairbnb.get_api_key("")
markets_data = pyairbnb.get_markets(
    currency="EUR",
    locale="es",
    api_key=api_key,
    proxy_url=""
)

markets = pyairbnb.get_nested_value(markets_data, "user_markets", [])
if markets:
    print(f"Found {len(markets)} markets")
```

--------------------------------

### Search listings from a URL

Source: https://github.com/johnbalvin/pyairbnb/blob/main/_autodocs/QUICK_START.md

Use this method to perform a search using a pre-constructed Airbnb search URL.

```python
import pyairbnb

url = "https://www.airbnb.com/s/Luxembourg--Luxembourg/homes?checkin=2026-02-09&checkout=2026-02-16&price_min=154&price_max=700"

results = pyairbnb.search_all_from_url(
    url,
    currency="EUR",
    language="en"
)
```

--------------------------------

### Retrieve listing metadata

Source: https://github.com/johnbalvin/pyairbnb/blob/main/_autodocs/api-reference/details.md

Fetches standardized listing details, price query parameters, and session cookies from a given Airbnb URL.

```python
def get_metadata_from_url(
    room_url: str,
    language: str,
    proxy_url: str,
    timeout: Timeout = DEFAULT_TIMEOUT
) -> tuple
```

```python
import pyairbnb

data, price_info, cookies = pyairbnb.get_metadata_from_url(
    "https://www.airbnb.com/rooms/30931885",
    "en",
    ""
)

print(f"Product ID: {price_info['product_id']}")
print(f"API Key: {price_info['api_key']}")
```

--------------------------------

### Accessing API via package namespace

Source: https://github.com/johnbalvin/pyairbnb/blob/main/_autodocs/EXPORT_MAP.md

Recommended pattern for accessing all library functions through the main package namespace.

```python
import pyairbnb

# All functions accessed via pyairbnb.
results = pyairbnb.search_all(...)
```

--------------------------------

### Configure Timeout Options

Source: https://github.com/johnbalvin/pyairbnb/blob/main/_autodocs/QUICK_START.md

Set request timeouts using integers, tuples for separate connect/read times, or None to disable.

```python
# 30 seconds
timeout=30

# Separate connect/read timeouts
timeout=(5, 60)

# No timeout
timeout=None
```

--------------------------------

### Check Date Availability Safely

Source: https://github.com/johnbalvin/pyairbnb/blob/main/_autodocs/errors.md

Wraps price fetching in a try-except block to handle UnavailableError and general exceptions gracefully.

```python
import pyairbnb
from datetime import date

def get_price_safe(room_id, check_in, check_out):
    try:
        return pyairbnb.get_price(
            room_id=room_id,
            check_in=check_in,
            check_out=check_out
        )
    except pyairbnb.UnavailableError:
        return None  # Dates not available
    except Exception as e:
        print(f"Error fetching price: {e}")
        return None
```

--------------------------------

### Fetch complete listing details

Source: https://github.com/johnbalvin/pyairbnb/blob/main/_autodocs/00_START_HERE.md

Retrieves comprehensive information for a specific room ID, including pricing, availability, and host details.

```python
import pyairbnb
from datetime import date

# Get complete information
data = pyairbnb.get_details(
    room_id=123456,
    check_in=date(2025, 10, 1),
    check_out=date(2025, 10, 4),
    currency="USD"
)

# Access all data
print(data['title'])           # Listing name
print(data['host']['name'])    # Host name
print(data['reviews'])         # Guest reviews
print(data['price'])           # Pricing breakdown
print(data['calendar'])        # Availability
print(data['amenities'])       # Features
```

--------------------------------

### get_price(room_id, check_in, check_out, ...)

Source: https://github.com/johnbalvin/pyairbnb/blob/main/_autodocs/api-reference/pricing.md

Retrieves complete pricing information for a listing including base rate, fees, discounts, and price breakdown.

```APIDOC
## get_price

### Description
Retrieves complete pricing information for a listing including base rate, fees, discounts, and price breakdown.

### Parameters
- **room_id** (str) - Required - Listing room ID
- **check_in** (date) - Required - Check-in date as datetime.date object
- **check_out** (date) - Required - Check-out date as datetime.date object
- **adults** (int) - Optional (Default: 1) - Number of adults for pricing calculation
- **currency** (str) - Optional (Default: "USD") - Currency code
- **language** (str) - Optional (Default: "en") - Language code
- **impresion_id** (str) - Optional - Impression ID from listing details
- **api_key** (str) - Optional - Airbnb API key
- **cookies** (list) - Optional - Session cookies
- **proxy_url** (str) - Optional - HTTP proxy URL
- **timeout** (Timeout) - Optional (Default: 60) - Request timeout in seconds

### Response
- **dict** - Pricing information containing 'raw' (list of price group objects) and 'main' (object with price, discountedPrice, originalPrice, qualifier, and details breakdown).

### Throws
- **UnavailableError** - Raised if listing is unavailable for the specified dates
- **HTTPError** - Raised if the API request fails
```

--------------------------------

### Importing specific functions directly

Source: https://github.com/johnbalvin/pyairbnb/blob/main/_autodocs/EXPORT_MAP.md

Alternative patterns for importing specific functions to use them directly in the local namespace.

```python
from pyairbnb import (
    search_all,
    search_first_page,
    get_details,
    get_reviews,
    get_price,
    get_api_key,
    get_nested_value,
    parse_proxy,
)

# Functions used directly
results = search_all(...)
```

```python
from pyairbnb import search_all, get_details

results = search_all(...)
data = get_details(...)
```

--------------------------------

### Perform Search with Filters

Source: https://github.com/johnbalvin/pyairbnb/blob/main/_autodocs/QUICK_START.md

Execute a search query with specific location, date, price, and amenity constraints.

```python
results = pyairbnb.search_all(
    check_in="2025-10-01",
    check_out="2025-10-04",
    ne_lat=10.0,
    ne_long=10.0,
    sw_lat=9.0,
    sw_long=9.0,
    zoom_value=2,
    price_min=100,
    price_max=5000,
    place_type="Entire home/apt",      # or "Private room"
    amenities=[4, 7],                  # WiFi, Pool
    free_cancellation=True,
    min_bedrooms=2,
    min_beds=3,
    min_bathrooms=1,
    adults=2,
    children=1,
    currency="USD",
    language="en"
)
```

--------------------------------

### Retrieve Reviews for a Listing

Source: https://github.com/johnbalvin/pyairbnb/blob/main/README.md

Extracts reviews and associated metadata for a specific Airbnb listing using its URL. Allows specifying the language and an optional proxy URL. The reviews are saved to 'reviews.json'.

```Python
import pyairbnb
import json

# Define listing URL and proxy URL
room_url = "https://www.airbnb.com/rooms/30931885"  # Listing URL
proxy_url = ""  # Proxy URL (if needed)
language = "fr"
# Retrieve reviews for the specified listing
reviews_data = pyairbnb.get_reviews(room_url, language, proxy_url)

# Save the reviews data to a JSON file
with open('reviews.json', 'w', encoding='utf-8') as f:
    f.write(json.dumps(reviews_data))  # Extract reviews and save them to a file
```

--------------------------------

### pyairbnb.experience_search

Source: https://github.com/johnbalvin/pyairbnb/blob/main/_autodocs/QUICK_START.md

Searches for Airbnb experiences based on location and criteria.

```APIDOC
## pyairbnb.experience_search

### Description
Searches for experiences in a specific location.

### Parameters
- **user_input_text** (string) - Required - Location query
- **api_key** (string) - Required - Authentication key
- **currency** (string) - Optional - Currency code
- **locale** (string) - Optional - Locale code
- **check_in** (string) - Optional - Start date
- **check_out** (string) - Optional - End date
- **proxy_url** (string) - Optional - Proxy configuration
```

--------------------------------

### Persist Configuration Across API Calls

Source: https://github.com/johnbalvin/pyairbnb/blob/main/_autodocs/configuration.md

Use a dictionary to store common parameters and unpack them into multiple function calls to maintain consistent settings.

```python
import pyairbnb
from datetime import date

# Set common parameters
CONFIG = {
    "currency": "EUR",
    "language": "es",
    "proxy_url": "http://proxy.example.com:8080",
    "timeout": 30,
}

# Use in multiple calls
api_key = pyairbnb.get_api_key(**{k:v for k,v in CONFIG.items() if k in ['proxy_url', 'timeout']})

results = pyairbnb.search_all(
    check_in="2025-10-01",
    check_out="2025-10-04",
    ne_lat=10.0,
    ne_long=10.0,
    sw_lat=9.0,
    sw_long=9.0,
    zoom_value=2,
    price_min=100,
    price_max=1000,
    **CONFIG
)

data = pyairbnb.get_details(
    room_id=123456,
    check_in=date(2025, 10, 1),
    check_out=date(2025, 10, 4),
    **CONFIG
)
```

--------------------------------

### Search Experiences by Text Input

Source: https://github.com/johnbalvin/pyairbnb/blob/main/README.md

Searches for Airbnb experiences using a direct text input for location. Requires check-in/out dates, currency, locale, API key, and an optional proxy URL. Results are saved to 'experiences.json'.

```Python
import pyairbnb
import json
check_in = "2026-05-10"
check_out = "2026-05-12"
currency = "EUR"
user_input_text = "Estados Unidos"
locale = "es"
proxy_url = ""  # Proxy URL (if needed)
api_key = pyairbnb.get_api_key("")
experiences = pyairbnb.experience_search(user_input_text, currency, locale, check_in, check_out, api_key, proxy_url)
with open('experiences.json', 'w', encoding='utf-8') as f:
    f.write(json.dumps(experiences))
```

--------------------------------

### Construct Authenticated Proxy URL in Python

Source: https://github.com/johnbalvin/pyairbnb/blob/main/_autodocs/configuration.md

Use the parse_proxy utility to generate a properly formatted proxy string with credentials.

```python
import pyairbnb

proxy_url = pyairbnb.parse_proxy(
    ip_or_domain="proxy.example.com",
    port="8080",
    username="user",
    password="pass"
)

results = pyairbnb.search_all(..., proxy_url=proxy_url)
```

--------------------------------

### pyairbnb.get_reviews

Source: https://github.com/johnbalvin/pyairbnb/blob/main/_autodocs/QUICK_START.md

Fetches reviews for a specific listing.

```APIDOC
## pyairbnb.get_reviews

### Description
Retrieves a list of reviews for a given listing URL.

### Parameters
- **room_url** (string) - Required - Listing URL
- **language** (string) - Optional - Language code
```

--------------------------------

### experience_search()

Source: https://github.com/johnbalvin/pyairbnb/blob/main/_autodocs/README.md

Searches for experiences based on location.

```APIDOC
## experience_search()

### Description
Searches for experiences based on location.

### Method
SDK Method

### Parameters
- **location** (str) - Required - The location to search for experiences.
```

--------------------------------

### Fetch place IDs and location information

Source: https://github.com/johnbalvin/pyairbnb/blob/main/_autodocs/api-reference/search.md

Resolves user input text into location data, requiring a configuration token obtained from market data.

```python
def get_places_ids(
    country: str,
    location_name: str,
    currency: str,
    locale: str,
    config_token: str,
    api_key: str,
    proxy_url: str,
    timeout: Timeout = DEFAULT_TIMEOUT
) -> list
```

```python
import pyairbnb

api_key = pyairbnb.get_api_key("")
markets_data = pyairbnb.get_markets("USD", "en", api_key, "")
markets = pyairbnb.get_nested_value(markets_data, "user_markets", [])

config_token = pyairbnb.get_nested_value(markets[0], "satori_parameters", "")
country_code = pyairbnb.get_nested_value(markets[0], "country_code", "")

place_ids_results = pyairbnb.get_places_ids(
    country_code,
    "cuenca",
    "USD",
    "en",
    config_token,
    api_key,
    ""
)

if place_ids_results:
    place_id = pyairbnb.get_nested_value(place_ids_results[0], "location.google_place_id", "")
    location_name = pyairbnb.get_nested_value(place_ids_results[0], "location.location_name", "")
```

--------------------------------

### Execute paginated search from URL

Source: https://github.com/johnbalvin/pyairbnb/blob/main/_autodocs/api-reference/search.md

Parses an existing Airbnb search URL to execute a full, paginated search. URL parameters override function arguments.

```python
def search_all_from_url(
    url: str,
    currency: str = "USD",
    language: str = "en",
    proxy_url: str = "",
    hash: str = "",
    timeout: Timeout = DEFAULT_TIMEOUT
) -> list
```

```python
import pyairbnb

url = "https://www.airbnb.com/s/Luxembourg--Luxembourg/homes?checkin=2026-02-09&checkout=2026-02-16&ne_lat=49.76537&ne_lng=6.56057&sw_lat=49.31155&sw_lng=6.03263&zoom=10&price_min=154&price_max=700&room_types%5B%5D=Entire%20home%2Fapt&amenities%5B%5D=4"

results = pyairbnb.search_all_from_url(
    url,
    currency="EUR",
    language="es"
)

print(f"Found {len(results)} listings from URL search")
```