AirROI APIairroi.com ↗
Access AirROI Market Atlas data via API: occupancy rates, ADR, estimated revenue, amenities, and monthly metrics for Airbnb listings worldwide.
What is the AirROI API?
The AirROI API exposes short-term rental property data from AirROI's Market Atlas across two endpoints. The list_properties endpoint returns summary metrics — occupancy rate, average daily rate (ADR), and estimated revenue — for all STR listings in a given country, state, and city. The get_property_details endpoint returns full property-level data including amenities, monthly historical metrics, ratings, bedroom/bath/guest capacity, fees, and booking info.
curl -X GET 'https://api.parse.bot/scraper/70d75792-6c3b-437c-90b6-7bf2ffa0da02/list_properties?city=Tulum&state=Quintana+Roo&sort_order=revenue_desc&country_code=MX' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace airroi-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: AirROI STR Properties — discover listings, then drill into details."""
from parse_apis.airroi_com_api import AirROI, PropertyNotFound
client = AirROI()
# List top-revenue properties in Tulum, Mexico (capped to 5 items).
for prop in client.properties.list(country_code="MX", state="Quintana Roo", city="Tulum", limit=5):
print(prop.listing_name, f"| ADR: {prop.average_daily_rate} | Revenue: {prop.revenue}")
# Drill into the first result for full details (amenities, monthly metrics).
summary = client.properties.list(country_code="MX", state="Quintana Roo", city="Tulum", limit=1).first()
if summary is not None:
try:
detail = client.properties.get(property_id=summary.id, limit=1).first()
except PropertyNotFound:
print("Property no longer available")
detail = None
if detail is not None:
print(f"\n{detail.listing_name}")
print(f" Beds: {detail.beds} | Baths: {detail.baths} | Guests: {detail.guests}")
print(f" Occupancy: {detail.occupancy_rate} | Min nights: {detail.min_nights}")
if detail.amenities:
print(f" Amenities ({len(detail.amenities)}): {', '.join(detail.amenities[:5])}")
if detail.monthly_metrics:
latest = detail.monthly_metrics[0]
print(f" Latest month: {latest.date} — rev {latest.revenue}, occ {latest.occupancy}")
print("\nexercised: properties.list / properties.get / PropertyNotFound")
List short-term rental properties for a given location (country, state, city). Returns summary metrics for each listing including coordinates, occupancy rate, ADR, estimated revenue, and property details. Fetches full detail for every listing via batch lookups, so response includes bedrooms, baths, guests, star rating, reviews, listing name, type, and cover photo. Results are not paginated — all matching properties for the location are returned in a single response (typically hundreds to thousands). Larger markets require more internal round-trips and may take 10–30 seconds.
| Param | Type | Description |
|---|---|---|
| city | string | City name (e.g. 'Tulum', 'Miami'). Hyphens are converted to spaces automatically. |
| state | string | State or province name. Use spaces for multi-word names (e.g. 'Quintana Roo', 'New York'). Hyphens are converted to spaces automatically. |
| sort_order | string | Sort order for results. Omitting defaults to revenue_desc. |
| country_coderequired | string | ISO 2-letter country code (e.g. 'MX', 'US', 'FR'). |
{
"type": "object",
"fields": {
"total": "total count of properties returned",
"properties": "array of property summary objects with id, listing_id, listing_name, coordinates, city, state, country_code, bedrooms, beds, baths, guests, listing_type, occupancy_rate, average_daily_rate, revenue, star_rating, num_reviews, cover_photo_url"
},
"sample": {
"data": {
"total": 9074,
"properties": [
{
"id": "BHOV258BugQE9_p7EpKP",
"beds": 0,
"city": null,
"baths": 0,
"state": null,
"guests": 0,
"revenue": 6268975,
"bedrooms": 0,
"latitude": 20.37192857,
"longitude": -87.32906689,
"listing_id": null,
"num_reviews": 0,
"star_rating": 0,
"country_code": null,
"listing_name": null,
"listing_type": null,
"occupancy_rate": 0.438,
"average_daily_rate": 39028.5
}
]
},
"status": "success"
}
}About the AirROI API
Endpoints and Coverage
The API provides two endpoints covering short-term rental markets globally. list_properties accepts a required country_code (ISO 2-letter code, e.g. MX, US) and optional state and city parameters to scope results to a market. Multi-word names can use either spaces or hyphens — the API normalizes them. An optional sort_order parameter controls result ordering; omitting it defaults to revenue_desc. Each property object in the response includes an id, geographic coordinates, occupancy_rate, average_daily_rate, and revenue.
Property Detail Data
get_property_details takes the property_id from a list_properties result and returns a detailed object. The response includes a full amenities array, monthly_metrics covering occupancy, ADR, and revenue broken down by month, guest ratings, bedroom/bath/guest capacity figures, coordinates, fee structures, and booking information. This is the appropriate endpoint when building property-level investment analysis or comparing seasonal performance.
Response Shape Notes
The list_properties response wraps results in a properties array alongside a total count. The get_property_details response similarly uses a properties array containing the matched object. The monthly_metrics field makes it possible to assess seasonality for any individual listing — useful for markets like Tulum or Miami where revenue varies significantly across the year. The list endpoint intentionally omits amenities and monthly breakdowns; those fields are only populated via the detail endpoint.
The AirROI API is a managed, monitored endpoint for airroi.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when airroi.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official airroi.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Rank STR markets by median revenue or occupancy using
list_propertiesresults across multiple cities - Build a seasonal revenue model for a specific property using
monthly_metricsfromget_property_details - Screen listings by ADR and occupancy rate to identify high-performing properties in a target city
- Compare amenity sets across top-revenue listings to inform new STR property fit-out decisions
- Estimate annual gross revenue for a potential acquisition using occupancy rate and ADR from the API
- Aggregate rating data from
get_property_detailsto benchmark guest satisfaction across a market - Track fee structures across listings in a region to understand competitive pricing norms
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 200 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
| Team | $300/mo | 20,000 | 300 req/min |
| Company | $1,000/mo | 100,000 | 500 req/min |
Each endpoint has a fixed posted price per successful call — most fall between 1 and 10 credits — shown on this API's page before you run it. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does AirROI offer an official developer API?+
What does `list_properties` return versus `get_property_details`?+
list_properties returns a summary array — property id, coordinates, occupancy_rate, average_daily_rate, and revenue — for all listings matching your location filters. get_property_details returns the full object for a single property: amenities, monthly_metrics (occupancy, ADR, revenue per month), ratings, bedroom/bath/guest capacity, fees, and booking info. You need the id from list_properties to call get_property_details.Can I filter `list_properties` results by minimum occupancy rate or ADR threshold?+
list_properties endpoint does not accept min/max filters on occupancy or ADR — it returns all listings for the given location, sorted by sort_order. Client-side filtering on the returned occupancy_rate and average_daily_rate fields is the current approach. You can fork this API on Parse and revise it to add server-side filter parameters.Does the API expose historical data beyond monthly metrics for the current year?+
get_property_details endpoint returns monthly_metrics covering occupancy, ADR, and revenue per month for the data AirROI surfaces in its Atlas. Multi-year historical time series are not currently exposed. You can fork the API on Parse and revise it to add additional historical range endpoints if the underlying data becomes available.Is there a limit on how many properties `list_properties` returns for a large city?+
total field indicating the count of properties returned. The endpoint does not currently expose pagination parameters such as page or offset. For large markets this means results are returned in a single response. You can fork this API on Parse and revise it to add pagination support.