# Airroi — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Discover short-term rental investment opportunities by accessing comprehensive Airbnb property data including occupancy rates, daily rates, estimated revenue, amenities, and guest ratings across worldwide markets. Analyze individual property performance metrics and browse listings to identify the most profitable rental properties for your portfolio.

**Category:** Real Estate | **Website:** [www.airroi.com/atlas/str-properties?country-code=MX&state=Quintana-Roo&city=Tulum](https://www.airroi.com/atlas/str-properties?country-code=MX&state=Quintana-Roo&city=Tulum) | **Docs:** [parse.bot/marketplace/e94a995b-f538-461d-9b24-ac3b422e4c6e/airroi-com-api](https://parse.bot/marketplace/e94a995b-f538-461d-9b24-ac3b422e4c6e/airroi-com-api)

Pay-per-use API proxy. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-airroi-com-api-e94a995b/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_city_details

Get full property details for every listing in a given location (country, state, city). Internally fetches all property IDs from the listing results and retrieves full details for each one in batches. Returns the same structured detail objects as get_property_details (listing_info, host_info, location_info, property_details, booking_settings, pricing_info, ratings, performance_metrics, monthly_metrics) for every property in the market. Not paginated — returns all properties in one response. Includes a time-budget mechanism: for very large markets (thousands of listings), the endpoint returns as many fully-detailed properties as it can retrieve within its execution window rather than failing entirely. Larger markets (thousands of listings) require many internal batch round-trips and may take 30–55 seconds.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `city` | string | No | City name (e.g. 'Tulum', 'Miami'). Hyphens are converted to spaces automatically. |
| `country_code` | string | Yes | ISO 2-letter country code (e.g. 'MX', 'US', 'FR'). |
| `state` | string | No | State or province name. Use spaces for multi-word names (e.g. 'Quintana Roo', 'New York'). Hyphens are converted to spaces automatically. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-airroi-com-api-e94a995b/get_city_details \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"city":"<string>","country_code":"<string>","state":"<string>"}'
```

### get_listings_monthly_metrics

Get per-listing monthly performance metrics for every active listing in a given location (country, state, city). Returns up to 12 months of monthly history per listing sourced from AirROI detail data. Each listing entry contains the property ID and an array of monthly metric rows with date (YYYY-MM), occupancy rate, ADR, RevPAR, and revenue. Internally fetches all listing IDs from the market then retrieves detail data in batches, so larger markets require many internal round-trips and may take 30–120 seconds. Not paginated — returns all listings in one response.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `city` | string | No | City name (e.g. 'Tulum', 'Miami'). Hyphens are converted to spaces automatically. |
| `country_code` | string | Yes | ISO 2-letter country code (e.g. 'MX', 'US', 'FR'). |
| `state` | string | No | State or province name. Use spaces for multi-word names (e.g. 'Quintana Roo', 'New York'). Hyphens are converted to spaces automatically. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-airroi-com-api-e94a995b/get_listings_monthly_metrics \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"city":"<string>","country_code":"<string>","state":"<string>"}'
```

### get_market_metrics

Get historical monthly market-level metrics for a given location (country, state, city). Returns aggregated market data over time in a flat tabular format where each month is a row with location fields, date (MM/DD/YYYY), metric averages and percentiles (p25/p50/p75/p90) for occupancy, ADR, RevPAR, revenue, plus booking lead time, length of stay, and min nights averages. Also includes active_listings_count and currency per row. Always returns exactly 60 monthly rows (5 years of history). One round-trip per call.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `city` | string | No | City name (e.g. 'Tulum', 'Miami'). Hyphens are converted to spaces automatically. |
| `country_code` | string | Yes | ISO 2-letter country code (e.g. 'MX', 'US', 'FR'). |
| `state` | string | No | State or province name. Use spaces for multi-word names (e.g. 'Quintana Roo', 'New York'). Hyphens are converted to spaces automatically. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-airroi-com-api-e94a995b/get_market_metrics \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"city":"<string>","country_code":"<string>","state":"<string>"}'
```

### get_property_details

Get full details for a specific property by its internal AirROI ID (from list_properties results). Returns comprehensive data including amenities list, monthly historical metrics (occupancy, ADR, revenue per month), ratings, bedrooms/baths/guests capacity, coordinates, fees, and booking policies. One request per property.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `property_id` | string | Yes | Internal AirROI property ID from list_properties results (id field). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-airroi-com-api-e94a995b/get_property_details \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"property_id":"<string>"}'
```

### list_properties

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). Includes a time-budget mechanism: for very large markets (tens of thousands of listings), detail enrichment proceeds as far as possible within the execution window; all listings are always returned but some may have sparse detail fields in extremely large markets. Larger markets require more internal round-trips and may take 10–50 seconds.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `city` | string | No | City name (e.g. 'Tulum', 'Miami'). Hyphens are converted to spaces automatically. |
| `country_code` | string | Yes | ISO 2-letter country code (e.g. 'MX', 'US', 'FR'). |
| `sort_order` | string | No | Sort order for results. Omitting defaults to revenue_desc. |
| `state` | string | No | State or province name. Use spaces for multi-word names (e.g. 'Quintana Roo', 'New York'). Hyphens are converted to spaces automatically. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-airroi-com-api-e94a995b/list_properties \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"city":"<string>","country_code":"<string>","sort_order":"<string>","state":"<string>"}'
```