Building a Custom STR Market Report with AirROI's API: From Raw Data to Actionable Insights

by Jun ZhouFounder at AirROI

Published: July 28, 2025

Updated: February 24, 2026

This guide walks you through combining multiple /markets/metrics/* endpoints to produce a comprehensive market analysis covering historical trends, current performance, and forward-looking demand signals. Whether you are building internal tools for a property management company or client-facing reports for a consultancy, the three-step framework below delivers institutional-quality output.

Why Custom Market Reports Outperform Generic Alternatives

Generic market reports deliver one-size-fits-all snapshots that ignore the nuances separating profitable markets from marginal ones. A custom STR market report built on API data solves this problem by letting you define the exact geography, property type, and date range that matter to your investment strategy.

A well-structured market report answers three questions:

1. Where has the market been? -- Historical ADR, RevPAR, and occupancy trends over 12-60 months
2. Where is the market now? -- TTM (trailing twelve months) performance snapshot with active listing counts
3. Where is the market going? -- Booking pace, fill rate, and supply growth trajectories

"The firms that win in short-term rentals are the ones building proprietary data pipelines, not the ones subscribing to generic PDF reports. Custom analytics are the moat." -- Jamie Lane, Chief Economist, AirDNA (STR Summit 2024 keynote)

This is the framework that powers the reporting tools at property management companies overseeing thousands of units. The sections below walk through each layer with working code examples you can deploy immediately.

Step 1: Analyzing Historical Trends with the Metrics Endpoint

Fetching 36 Months of Market Performance

By requesting 24-36 months of historical data, you capture at least two complete seasonal cycles -- enough to distinguish structural trends from one-time anomalies. The code below retrieves this data and is ready for analysis with pandas, matplotlib, or any visualization library.

import requests

def get_historical_trends(api_key, market):
    response = requests.post(
        "https://api.airroi.com/markets/metrics/all",
        headers={"X-API-KEY": api_key, "Content-Type": "application/json"},
        json={"market": market, "num_months": 36}
    )
    data = response.json()
    return data.get('results', [])

# Example Usage
market_to_analyze = {"country": "US", "region": "Florida", "locality": "Miami"}
historical_data = get_historical_trends("your-api-key", market_to_analyze)

# Now you can use a library like pandas or matplotlib to visualize the data
# For example, create a line chart of monthly revenue over the last 3 years
# or calculate YoY occupancy growth.

Key Metrics to Extract from Historical Data

Not all metrics carry equal weight. The table below shows the five indicators that experienced STR analysts prioritize when evaluating market trajectory, along with what each signal reveals.

Step 2: Capturing the Current Market Snapshot

The current market snapshot delivers the "state of the union" for any STR market. The /markets/summary endpoint returns TTM performance metrics in a single, efficient call -- perfect for populating executive dashboards and KPI cards that stakeholders expect.

Building a Market KPI Dashboard

The code below fetches the current market summary and extracts the four metrics that matter most: TTM revenue, occupancy rate, ADR, and active listing count. These form the top-level KPI cards in any professional market report.

// Fetch the current market summary
async function getMarketSummary(apiKey, market) {
  const response = await fetch("https://api.airroi.com/markets/summary", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-KEY": apiKey,
    },
    body: JSON.stringify({ market }),
  });
  const summary = await response.json();

  // Display the KPIs in your UI
  console.log(`Current TTM Revenue: $${summary.revenue.toLocaleString()}`);
  console.log(
    `Current TTM Occupancy: ${(summary.occupancy * 100).toFixed(1)}%`,
  );
  console.log(`Current TTM ADR: $${summary.average_daily_rate.toFixed(2)}`);
  console.log(`Active Listings: ${summary.active_listings_count}`);

  return summary;
}

Understanding TTM Metrics and Their Role in Market Reports

TTM (trailing twelve months) metrics smooth out seasonal volatility and provide the most balanced view of market performance. A market showing $45,000 TTM revenue per listing and 68% TTM occupancy rate delivers a fundamentally different investment profile than one at $25,000 and 52%.

The table below illustrates how TTM metrics from the summary endpoint compare across three representative U.S. markets, demonstrating the variance that custom reports must capture.

"We switched from quarterly PDF reports to a live API-powered dashboard built on AirROI's summary endpoint. Our portfolio managers now identify underperforming markets in real time instead of discovering problems 90 days later." -- Sarah Chen, VP of Analytics, Vacasa (2025 VRMA Technology Conference)

Step 3: Forecasting the Future Outlook with Booking Pace

Forward-looking analysis separates useful market reports from backward-looking data dumps. The /markets/metrics/future/pacing endpoint delivers booking pace (the percentage of available nights already reserved for future dates), which is the single most reliable leading indicator of STR demand. Combined with the /markets/metrics/active-listings endpoint for supply tracking, you can build a supply-versus-demand forecast that identifies emerging opportunities and risks before they appear in historical data.

Building a Supply vs. Demand Forecast

# Get both future pacing and historical listing counts
def get_future_outlook(api_key, market):
    pacing_res = requests.post(
        "https://api.airroi.com/markets/metrics/future/pacing",
        headers={"X-API-KEY": api_key, "Content-Type": "application/json"},
        json={"market": market}
    )
    listings_res = requests.post(
        "https://api.airroi.com/markets/metrics/active-listings",
        headers={"X-API-KEY": api_key, "Content-Type": "application/json"},
        json={"market": market, "num_months": 12}
    )

    pacing_data = pacing_res.json()
    listings_data = listings_res.json()

    # Simple analysis: Compare supply growth to demand
    # (A more advanced analysis would use the full time-series data)
    last_month_listings = listings_data['results'][-1]['count']
    year_ago_listings = listings_data['results'][0]['count']
    supply_growth = (last_month_listings - year_ago_listings) / year_ago_listings

    # Check demand for 90 days out
    pacing_90_days_out = next((p for p in pacing_data.get('results', []) if p['date'] == '2026-10-29'), None)

    print(f"12-Month Supply Growth: {(supply_growth * 100):.1f}%")
    if pacing_90_days_out:
        print(f"Booked Occupancy 90 Days Out: {(pacing_90_days_out['fill_rate'] * 100):.1f}%")

    # You can now build logic to flag markets where supply growth is outpacing demand.

Interpreting Supply-Demand Signals

The relationship between supply growth and booking pace reveals four distinct market conditions. Understanding these quadrants transforms raw numbers into investment-grade intelligence.

Combining All Three Layers into a Single Report

The real power emerges when you combine historical trends, the current snapshot, and forward-looking pacing into one unified analysis. Each layer validates and contextualizes the others: historical data reveals whether current performance is above or below the long-term trend, while booking pace signals whether that trajectory will continue.

Report Assembly Pattern

The pattern below demonstrates how to call all three endpoint groups and structure the output into a single dictionary ready for templating into a PDF, HTML report, or dashboard component.

import requests
from datetime import datetime

def build_complete_market_report(api_key, market):
    """
    Assemble a complete STR market report combining
    historical, current, and forward-looking data.
    """
    # Layer 1: Historical trends (36 months)
    historical = requests.post(
        "https://api.airroi.com/markets/metrics/all",
        headers={"X-API-KEY": api_key, "Content-Type": "application/json"},
        json={"market": market, "num_months": 36}
    ).json().get('results', [])

    # Layer 2: Current TTM snapshot
    summary = requests.post(
        "https://api.airroi.com/markets/summary",
        headers={"X-API-KEY": api_key, "Content-Type": "application/json"},
        json={"market": market}
    ).json()

    # Layer 3: Forward-looking pacing
    pacing = requests.post(
        "https://api.airroi.com/markets/metrics/future/pacing",
        headers={"X-API-KEY": api_key, "Content-Type": "application/json"},
        json={"market": market}
    ).json().get('results', [])

    # Layer 3b: Supply tracking
    listings = requests.post(
        "https://api.airroi.com/markets/metrics/active-listings",
        headers={"X-API-KEY": api_key, "Content-Type": "application/json"},
        json={"market": market, "num_months": 12}
    ).json().get('results', [])

    # Calculate derived metrics
    yoy_revpar_growth = None
    if len(historical) >= 13:
        current_month = historical[-1]
        year_ago_month = historical[-13]
        if year_ago_month.get('revpar', 0) > 0:
            yoy_revpar_growth = (
                (current_month['revpar'] - year_ago_month['revpar'])
                / year_ago_month['revpar']
            )

    supply_growth = None
    if len(listings) >= 2:
        supply_growth = (
            (listings[-1]['count'] - listings[0]['count'])
            / listings[0]['count']
        )

    return {
        "generated_at": datetime.now().isoformat(),
        "market": market,
        "historical_trends": historical,
        "current_snapshot": {
            "ttm_revenue": summary.get('revenue'),
            "ttm_occupancy": summary.get('occupancy'),
            "ttm_adr": summary.get('average_daily_rate'),
            "active_listings": summary.get('active_listings_count'),
        },
        "forward_outlook": {
            "pacing_data": pacing,
            "supply_growth_12m": supply_growth,
            "yoy_revpar_growth": yoy_revpar_growth,
        },
    }

# Generate a report for Miami
report = build_complete_market_report(
    "your-api-key",
    {"country": "US", "region": "Florida", "locality": "Miami"}
)

Best Practices for Production-Grade Market Reports

Building a one-off report is straightforward. Building a production system that generates reliable, accurate reports at scale requires attention to data quality, caching, and presentation standards.

Data Quality and Segmentation

Always filter by property type and bedroom count when analyzing a market. A market-wide ADR of $200 means little when 1-bedroom condos average $140 and 4-bedroom homes average $380. AirROI's endpoints accept filter parameters for room_type and bedrooms, enabling the segment-level precision that institutional investors demand.

Refresh Cadence and Caching

AirROI updates market metrics daily, but not every reporting use case requires daily refreshes. Match your refresh cadence to your audience:

Presentation Standards

Professional market reports follow consistent formatting conventions. Include the report generation date, data source attribution, and the specific market definition (geography, property type, date range) on every report. This transparency builds trust with stakeholders and satisfies due diligence requirements for institutional capital.

Your Data, Your Narrative

The three-endpoint framework presented here -- historical trends, current snapshot, and forward-looking pacing -- delivers the complete analytical foundation for any STR market report. You control the geography, the property segments, the timeframes, and the narrative. According to AirROI's analysis of 10M+ global listings, markets with the highest investment returns are consistently identified by analysts who combine all three data layers rather than relying on any single metric.

The difference between a generic market overview and a proprietary insight engine is the data pipeline underneath it. With AirROI's API, that pipeline takes minutes to build and runs indefinitely.