# Airbnb (Portugal) — Wrapped API

> **You are on:** `https://api.beta.paywithlocus.com/api` | [llms.txt](https://beta.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.

> Search for rental listings in any location, view detailed information about properties including availability and guest reviews. Browse hundreds of accommodations to find the perfect place that fits your travel needs and budget.

**Category:** Travel | **Website:** [airbnb.pt/](https://airbnb.pt/) | **Docs:** [parse.bot/marketplace/6daa269f-dff5-48a4-8517-cdb8b030287e/airbnb-pt-api](https://parse.bot/marketplace/6daa269f-dff5-48a4-8517-cdb8b030287e/airbnb-pt-api)

Pay-per-use API proxy for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.beta.paywithlocus.com/api/wrapped/credits/airbnb-portugal/`
**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 listing availability

Fetch the availability calendar for a listing starting from a given month and year. Returns up to 12 months of daily availability data with date, available flag, and formatted price when available. The month/year must not be in the past; past months return stale_input. Delisted or private listings return a permission error.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `listing_id` | string | Yes | The Airbnb listing ID (numeric string, obtainable from search_rentals results) |
| `month` | integer | Yes | Start month (1-12). Must be current or future month. |
| `year` | integer | Yes | Start year (YYYY) |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/airbnb-portugal/get-listing-availability \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"listing_id":"<string>","month":"<integer>","year":"<integer>"}'
```

### Get listing details

Fetch the full property detail page for one listing. Returns title, HTML description, amenities list, house rules, cancellation policy, max guest capacity, and structured price display. Some sections may be null if the host has not configured them or if no dates are selected.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `listing_id` | string | Yes | The Airbnb listing ID (numeric string, obtainable from search_rentals results) |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/airbnb-portugal/get-listing-details \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"listing_id":"<string>"}'
```

### Get listing reviews

Fetch guest reviews for a listing sorted by quality. Returns review text, numeric rating, author first name (when available), and the total review count for the listing. Pagination is offset-based: advance offset by limit for the next page.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `limit` | integer | No | Number of reviews to return per page |
| `listing_id` | string | Yes | The Airbnb listing ID (numeric string, obtainable from search_rentals results) |
| `offset` | integer | No | Pagination offset for reviews |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/airbnb-portugal/get-listing-reviews \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"limit":"<integer>","listing_id":"<string>","offset":"<integer>"}'
```

### Search rentals

Full-text location search over Airbnb rental listings. Accepts optional date range, guest count, price bounds, and property type filters. Returns a page of listing summaries with pricing, ratings, photos, and coordinates. Pagination is offset-based: advance by incrementing offset by limit. Each ListingSummary exposes a .details() method for the full property page (a separate fetch).

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `adults` | integer | No | Number of adults |
| `check_in` | string | No | Check-in date in ISO format YYYY-MM-DD |
| `check_out` | string | No | Check-out date in ISO format YYYY-MM-DD |
| `limit` | integer | No | Number of results per page |
| `location` | string | No | Search location query (e.g. 'Paris, France', 'New York', 'Almada, Portugal') |
| `offset` | integer | No | Pagination offset (advance by limit to get next page) |
| `price_max` | integer | No | Maximum nightly price in EUR |
| `price_min` | integer | No | Minimum nightly price in EUR |
| `property_type_ids` | string | No | Comma-separated property type IDs: 1=House, 2=Guesthouse, 3=Apartment, 4=Hotel |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/airbnb-portugal/search-rentals \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"adults":"<integer>","check_in":"<string>","check_out":"<string>","limit":"<integer>","location":"<string>","offset":"<integer>","price_max":"<integer>","price_min":"<integer>","property_type_ids":"<string>"}'
```

## Next steps

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