Airbnb Occupancy Rates by City

import requests

API_KEY = "your_api_key"
BASE_URL = "https://api.airroi.com/v1"
headers = {"X-API-KEY": API_KEY}

# Search for a market
response = requests.get(
    f"{BASE_URL}/markets/search?query=nashville",
    headers=headers
)
results = response.json()

market = results[0]
print(f"Market: {market['full_name']}")
print(f"Country: {market['country']}")
print(f"Region: {market['region']}")
print(f"Locality: {market['locality']}")
print(f"Active listings: {market['active_listings_count']:,}")

# Save the market object for subsequent calls
market_obj = {
    "country": market["country"],
    "region": market["region"],
    "locality": market["locality"]
}

# Pull 12 months of occupancy data with percentiles
payload = {
    "market": market_obj,
    "num_months": 12
}

response = requests.post(
    f"{BASE_URL}/markets/metrics/occupancy",
    json=payload,
    headers={**headers, "Content-Type": "application/json"}
)
occupancy_data = response.json()

print(f"{'Month':<12} {'Avg':>6} {'p25':>6} {'p50':>6} {'p75':>6} {'p90':>6}")
print("-" * 48)
for month in occupancy_data:
    print(f"{month['date']:<12} "
          f"{month['avg']:>5.0%} "
          f"{month['p25']:>5.0%} "
          f"{month['p50']:>5.0%} "
          f"{month['p75']:>5.0%} "
          f"{month['p90']:>5.0%}")

# Compare average vs top performers
import statistics

avg_occupancies = [m["avg"] for m in occupancy_data]
p90_occupancies = [m["p90"] for m in occupancy_data]

overall_avg = statistics.mean(avg_occupancies)
overall_p90 = statistics.mean(p90_occupancies)
spread = overall_p90 - overall_avg

print(f"Market average occupancy: {overall_avg:.0%}")
print(f"Top 10% (p90) occupancy: {overall_p90:.0%}")
print(f"Spread: {spread:.0%}")
print()

if spread > 0.25:
    print("Large spread — top performers significantly outpace the average.")
    print("This suggests room for optimization if you can match")
    print("what the top 10% are doing (better listing, pricing, reviews).")
elif spread > 0.15:
    print("Moderate spread — top hosts do noticeably better.")
    print("Focus on pricing strategy and listing quality to move up.")
else:
    print("Narrow spread — the market is fairly uniform.")
    print("Occupancy is less about skill and more about market conditions.")

# Filter by bedrooms to see how property size affects occupancy
bedroom_counts = [1, 2, 3]
bedroom_data = {}

for br in bedroom_counts:
    payload = {
        "market": market_obj,
        "filter": {"bedrooms": {"eq": br}},
        "num_months": 12
    }

    response = requests.post(
        f"{BASE_URL}/markets/metrics/occupancy",
        json=payload,
        headers={**headers, "Content-Type": "application/json"}
    )
    bedroom_data[br] = response.json()

# Compare annual average occupancy by bedroom count
print(f"{'Bedrooms':<10} {'Avg Occ':>8} {'p50 Occ':>8} {'p90 Occ':>8}")
print("-" * 36)
for br, data in bedroom_data.items():
    avg = statistics.mean([m["avg"] for m in data])
    p50 = statistics.mean([m["p50"] for m in data])
    p90 = statistics.mean([m["p90"] for m in data])
    print(f"{br} BR{'':<6} {avg:>7.0%} {p50:>7.0%} {p90:>7.0%}")

# Compare seasonal stability across markets
import statistics

cities_to_compare = [
    {"query": "austin", "label": "Austin (year-round)"},
    {"query": "park city", "label": "Park City (seasonal)"},
]

for city_info in cities_to_compare:
    # Search market
    search = requests.get(
        f"{BASE_URL}/markets/search?query={city_info['query']}",
        headers=headers
    ).json()

    if not search:
        continue

    m = search[0]
    payload = {
        "market": {
            "country": m["country"],
            "region": m["region"],
            "locality": m["locality"]
        },
        "num_months": 12
    }

    data = requests.post(
        f"{BASE_URL}/markets/metrics/occupancy",
        json=payload,
        headers={**headers, "Content-Type": "application/json"}
    ).json()

    monthly_avg = [d["avg"] for d in data]
    mean_occ = statistics.mean(monthly_avg)
    std_occ = statistics.stdev(monthly_avg)
    cv = std_occ / mean_occ  # Coefficient of variation

    print(f"{city_info['label']}:")
    print(f"  Mean occupancy: {mean_occ:.0%}")
    print(f"  Std deviation:  {std_occ:.0%}")
    print(f"  CV (stability): {cv:.2f}")
    print(f"  Verdict: {'Stable' if cv < 0.15 else 'Seasonal' if cv < 0.30 else 'Highly seasonal'}")
    print()

# Benchmark your listing against market percentiles
listing_id = "your_listing_id"  # Your Airbnb listing's AirROI ID

response = requests.get(
    f"{BASE_URL}/listings/metrics/all?id={listing_id}&num_months=24",
    headers=headers
)
listing_metrics = response.json()

# Compare listing occupancy vs market percentiles
print(f"{'Month':<12} {'Your Occ':>8} {'Mkt Avg':>8} {'Mkt p75':>8} {'Mkt p90':>8} {'Rank':>14}")
print("-" * 56)

for listing_month in listing_metrics[-12:]:
    date = listing_month["date"]
    my_occ = listing_month["occupancy"]

    # Find matching market month
    market_month = next(
        (m for m in occupancy_data if m["date"] == date), None
    )
    if not market_month:
        continue

    # Determine rank
    if my_occ >= market_month["p90"]:
        rank = "Exceptional"
    elif my_occ >= market_month["p75"]:
        rank = "Strong"
    elif my_occ >= market_month["p25"]:
        rank = "Average"
    else:
        rank = "Below avg"

    print(f"{date:<12} {my_occ:>7.0%} {market_month['avg']:>7.0%} "
          f"{market_month['p75']:>7.0%} {market_month['p90']:>7.0%} "
          f"{rank:>14}")