# 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 for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/credits/airroi/`
**Auth:** `Authorization: Bearer <LOCUS_CREDITS_SECRET_KEY>` (an `lcr_` secret key or a scoped `lcac_` agent credential)
**Required header:** `Idempotency-Key: <fresh UUID per call>`. A retry with the same key replays the stored result without a new charge.
**Response:** the provider response after any endpoint-specific normalization. `X-Locus-Credits-Charged` carries the charge and `X-Locus-Credits-Balance` the remaining balance. Insufficient credits return `402` before the provider is called.
**Pricing:** estimated costs below are USD. Locus debits the credit equivalent at your workspace rate.

Full call contract: https://docs.paywithlocus.com/api-reference/introduction

> Using a Pay With Locus wallet key (`claw_` prefix)? Wallet routes are documented separately: https://docs.paywithlocus.com/wrapped-apis/for-agents

## 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/credits/airroi/get-city-details \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/airroi/get-listings-monthly-metrics \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/airroi/get-market-metrics \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/airroi/get-property-details \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/airroi/list-properties \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"city":"<string>","country_code":"<string>","sort_order":"<string>","state":"<string>"}'
```

## Next steps

- [All wrapped API providers](https://paywithlocus.com/wapi/index.md): pick another provider.
- [Find and call tools](https://paywithlocus.com/agent/tools.md): price ceilings, async results, and errors.
- [Credits and billing](https://paywithlocus.com/agent/billing.md): what a call costs and how to add credits.
- [Agent docs index](https://paywithlocus.com/agent/index.md): every Locus agent page.