short-term-rental-market-research

Short-term rental market research

Build comparable market panels from Airbnb aggregate data, with optional live listing examples kept separate from market statistics.

Setup and API contract

Set CRAWLORA_API_KEY to your key from crawlora.net. Run the bundled scripts/crawlora.sh from this skill directory or by absolute path. It sends x-api-key to https://api.crawlora.net/api/v1; keep the key in the environment. Read reference/endpoints.md for the selected endpoints, required parameters, limits, and response behavior. Check the application code as well as HTTP status; successful payloads are inside data. Stop on 401/403, back off on 429, and retry a transient 5xx once. A failed or partial fetch is not an empty market or catalog. Bound requests to the user's scope and credit budget. For repeated collection, save the query, source IDs, pagination progress, and retrieval timestamps with the results so interrupted work can resume; do not create monitors implicitly.

Build the market panel

1. Define countries/markets, geographic level, freshness cutoff, and comparison

purpose. Discover exact country/market values through /datasets/airbnb-markets/facets; use the same filters in search and facets. Country values are ISO alpha-2 codes. Do not silently substitute a country aggregate for a missing city.

1. /datasets/airbnb-markets/search returns aggregate cells, never listing rows.

group_by accepts country, market, admin1, locality, room_type, or property_type; these are alternative groupings, not independent populations to sum together. The enriched dimensions can remain empty until coverage is sufficient. Empty/suppressed cells mean unavailable evidence, not zero supply.

1. Retain listing counts, rating/review signals, badge shares, and price summaries

with their returned units, timestamps, and coverage. active_since filters last-seen dates: it does not identify stays booked since that date. Superhost and Guest Favorite shares are observed lower bounds. avg_person_capacity describes the detail-enriched sample rather than every listing. Percentage fields such as superhost_pct are already percentages (31.5 means 31.5%), not fractions to multiply by 100.

1. /datasets/airbnb-markets/items/{country} is a country profile with metro

context and per-currency price percentiles. Do not pass a market name as its country identifier. A 404 can reflect suppression. Keep native-currency prices separate; price_usd and median_price_usd use an approximate dated FX snapshot, not a current exchange quote. Do not average medians to create a larger market median or mix currencies into one distribution.

1. /datasets/airbnb-markets/nearby returns geohash-cell centroids and suppressed

aggregate counts, not listing addresses. Compare equal radii and precision, with consistent country, rating, Superhost, and freshness filters. Do not sum overlapping radius searches or portray a cell centroid as a property location.

1. Keep pagination bounded: page_size<=100, page * page_size<=10000. Preserve

suppression floors and returned coverage notes. Do not use repeated narrow queries to reconstruct suppressed cells or individual listings.

scripts/crawlora.sh /datasets/airbnb-markets/search \
  group_by=country page_size=5 sort=listings_desc
scripts/crawlora.sh /datasets/airbnb-markets/facets facet=market country=FR
# Use a discovered market in the next search; country profiles use country codes.

Optional live examples

Use /airbnb/search for a small, explicitly sampled set in the chosen location. Set the same future check_in, check_out, and adults across markets when comparing displayed offers; resolve room IDs from results before detail/reviews. If using map bounds, read the reference for all required coordinate parameters. Live listings cannot be joined to aggregate cells by a dataset listing ID because no such individual records are exposed by these dataset endpoints.

Label nightly, stay-total, fees, taxes, and currency separately when supplied. Do not backfill aggregate missing prices from a handful of live search results. Review snippets are samples, not a complete review history. Calendar endpoints provide public month hints: blocked or unavailable dates can have several causes and do not establish bookings, occupancy, ADR, RevPAR, or host revenue.

Deliverable

Return a market comparison with geography, filter scope, observed supply, density context, room/property mix where available, price basis and FX vintage, review signals, collection dates, and suppression/enrichment limitations. Include example listings separately with source URLs/IDs and dates. Explain which findings support further research; listing density alone does not prove unmet demand, investment returns, or that short-term rentals are legally permitted at a property.