Analyze Airbnb Seasonality Patterns

import requests

API_KEY = "your_api_key_here"
BASE_URL = "https://api.airroi.com"

# Pull 24 months of market-level metrics for Miami
response = requests.post(
    f"{BASE_URL}/markets/metrics/all",
    headers={
        "X-API-KEY": API_KEY,
        "Content-Type": "application/json"
    },
    json={
        "market": {
            "country": "us",
            "region": "florida",
            "locality": "miami"
        },
        "num_months": 24,
        "currency": "usd"
    }
)

data = response.json()
metrics = data["metrics"]  # Array of 24 monthly data points
print(f"Retrieved {len(metrics)} months of data")
print(f"Date range: {metrics[0]['date']} to {metrics[-1]['date']}")

from collections import defaultdict

# Group metrics by month-of-year (1-12) and average across years
monthly_profile = defaultdict(lambda: {"occupancy": [], "adr": [], "revenue": []})

for m in metrics:
    month_num = int(m["date"].split("-")[1])  # Extract month number
    monthly_profile[month_num]["occupancy"].append(m["occupancy"]["p50"])
    monthly_profile[month_num]["adr"].append(m["average_daily_rate"]["p50"])
    monthly_profile[month_num]["revenue"].append(m["revenue"]["p50"])

# Build the 12-month seasonal profile
month_names = ["Jan", "Feb", "Mar", "Apr", "May", "Jun",
               "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"]

print(f"\n{'Month':<6} {'Occupancy':>10} {'ADR':>10} {'Revenue':>10}")
print("-" * 40)
for month_num in range(1, 13):
    data = monthly_profile[month_num]
    avg_occ = sum(data["occupancy"]) / len(data["occupancy"])
    avg_adr = sum(data["adr"]) / len(data["adr"])
    avg_rev = sum(data["revenue"]) / len(data["revenue"])
    print(f"  {month_names[month_num-1]:<6} {avg_occ:>9.0%} ${avg_adr:>8,.0f} ${avg_rev:>8,.0f}")

# Classify months into Peak, Shoulder, and Low seasons
# Based on median occupancy thresholds

seasonal_classification = {}

for month_num in range(1, 13):
    data = monthly_profile[month_num]
    avg_occ = sum(data["occupancy"]) / len(data["occupancy"])

    if avg_occ > 0.70:
        season = "Peak"
    elif avg_occ > 0.50:
        season = "Shoulder"
    else:
        season = "Low"

    seasonal_classification[month_num] = {
        "season": season,
        "occupancy": avg_occ,
        "adr": sum(data["adr"]) / len(data["adr"]),
        "revenue": sum(data["revenue"]) / len(data["revenue"]),
    }

# Display seasonal calendar
print("\nSeasonal Classification:")
print(f"{'Month':<6} {'Season':<10} {'Occupancy':>10} {'ADR':>8} {'Revenue':>10}")
print("-" * 48)
for month_num in range(1, 13):
    s = seasonal_classification[month_num]
    print(
        f"  {month_names[month_num-1]:<6} {s['season']:<10} "
        f"{s['occupancy']:>9.0%} ${s['adr']:>6,.0f} ${s['revenue']:>8,.0f}"
    )

# Summarize seasons
for season_type in ["Peak", "Shoulder", "Low"]:
    months_in = [month_names[m-1] for m, s in seasonal_classification.items()
                 if s["season"] == season_type]
    print(f"\n{season_type} months: {', '.join(months_in)}")

# Year-over-year comparison: same month across different years
# Requires 24+ months of data

print("\nYear-over-Year Comparison:")
print(f"{'Month':<10} {'Year 1 Occ':>10} {'Year 2 Occ':>10} {'YoY Change':>12}")
print("-" * 48)

for month_num in range(1, 13):
    data = monthly_profile[month_num]
    if len(data["occupancy"]) >= 2:
        yr1_occ = data["occupancy"][0]
        yr2_occ = data["occupancy"][1]
        yoy_change = (yr2_occ - yr1_occ) / yr1_occ

        yr1_adr = data["adr"][0]
        yr2_adr = data["adr"][1]
        adr_change = (yr2_adr - yr1_adr) / yr1_adr

        print(
            f"  {month_names[month_num-1]:<10} "
            f"{yr1_occ:>9.0%} {yr2_occ:>9.0%} {yoy_change:>+11.1%}"
        )

# Overall YoY trends
yr1_months = [m for m in metrics if m["date"][:4] == metrics[0]["date"][:4]]
yr2_months = [m for m in metrics if m["date"][:4] != metrics[0]["date"][:4]]

yr1_avg_occ = sum(m["occupancy"]["p50"] for m in yr1_months) / len(yr1_months)
yr2_avg_occ = sum(m["occupancy"]["p50"] for m in yr2_months) / len(yr2_months)
yr1_avg_adr = sum(m["average_daily_rate"]["p50"] for m in yr1_months) / len(yr1_months)
yr2_avg_adr = sum(m["average_daily_rate"]["p50"] for m in yr2_months) / len(yr2_months)

print(f"\nAnnual averages:")
print(f"  Occupancy: {yr1_avg_occ:.0%} -> {yr2_avg_occ:.0%} ({(yr2_avg_occ/yr1_avg_occ - 1):+.1%})")
print(f"  ADR:       ${yr1_avg_adr:,.0f} -> ${yr2_avg_adr:,.0f} ({(yr2_avg_adr/yr1_avg_adr - 1):+.1%})")

# Compare an individual listing's metrics to the market
listing_id = "your_listing_id_here"

# Pull listing-level time series
listing_resp = requests.get(
    f"{BASE_URL}/listings/metrics/all",
    headers={"X-API-KEY": API_KEY},
    params={
        "id": listing_id,
        "currency": "usd",
        "num_months": 24
    }
)

listing_metrics = listing_resp.json()["metrics"]

# Compare listing vs market for each month
print(f"\n{'Month':<10} {'Listing Occ':>12} {'Market Occ':>12} {'Diff':>8}")
print("-" * 46)

for lm in listing_metrics:
    # Find matching market month
    market_month = next((m for m in metrics if m["date"] == lm["date"]), None)
    if market_month:
        listing_occ = lm["occupancy"]
        market_occ = market_month["occupancy"]["p50"]
        diff = listing_occ - market_occ

        date_label = lm["date"]
        status = "+" if diff > 0 else ""
        print(f"  {date_label:<10} {listing_occ:>11.0%} {market_occ:>11.0%} {status}{diff:>6.0%}")

# Summary: months outperforming vs underperforming
outperform = sum(1 for lm in listing_metrics
    for mm in metrics if mm["date"] == lm["date"]
    and lm["occupancy"] > mm["occupancy"]["p50"])
total = len(listing_metrics)
print(f"\nOutperforms market: {outperform}/{total} months ({outperform/total:.0%})")

# Build a seasonal pricing calendar based on market data
# Use seasonal classification from Step 3

# Calculate annual average ADR as baseline
annual_avg_adr = sum(
    s["adr"] for s in seasonal_classification.values()
) / 12

# Apply seasonal multipliers
multipliers = {"Peak": 1.20, "Shoulder": 1.00, "Low": 0.80}

print("\nSeasonal Pricing Calendar")
print("=" * 55)
print(f"Annual average ADR: ${annual_avg_adr:,.0f}")
print(f"\n{'Month':<6} {'Season':<10} {'Multiplier':>11} {'Suggested Rate':>15}")
print("-" * 45)

total_revenue = 0
for month_num in range(1, 13):
    s = seasonal_classification[month_num]
    multiplier = multipliers[s["season"]]
    suggested_rate = annual_avg_adr * multiplier

    # Estimate monthly revenue: rate * occupancy * 30 days
    est_monthly = suggested_rate * s["occupancy"] * 30
    total_revenue += est_monthly

    print(
        f"  {month_names[month_num-1]:<6} {s['season']:<10} "
        f"{multiplier:>10.0%} ${suggested_rate:>13,.0f}"
    )

print(f"\nProjected annual revenue: ${total_revenue:,.0f}")
print(f"\nPricing strategy summary:")
print(f"  Peak months:     ${annual_avg_adr * 1.20:,.0f}/night (120% of avg)")
print(f"  Shoulder months: ${annual_avg_adr * 1.00:,.0f}/night (100% of avg)")
print(f"  Low months:      ${annual_avg_adr * 0.80:,.0f}/night (80% of avg)")