# Airbnb Scraper — Stays, Total Price, Host, Amenities & Reviews (`foxlabs/airbnb-scraper`) Actor

Scrape Airbnb listings and guest reviews by city/location or room URL. Extracts true total & nightly price breakdown, GPS coordinates, 6 rating subcategories, Superhost & commercial host B2B details, amenities, and reviews. No login required.

- **URL**: https://apify.com/foxlabs/airbnb-scraper.md
- **Developed by:** [Berkan Kaplan](https://apify.com/foxlabs) (community)
- **Categories:** Travel, Lead generation
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.50 / 1,000 airbnb listings

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

<p align="center">
  <img src="https://img.shields.io/badge/Pay--Per--Event-Listings_%2B_Reviews-00C853?style=for-the-badge" alt="Pay-Per-Event" />&nbsp;
  <img src="https://img.shields.io/badge/Total_Price_Breakdown-B2B_Host_Contacts-2962FF?style=for-the-badge" alt="Total Price & Host Contacts" />&nbsp;
  <img src="https://img.shields.io/badge/AI_Agent_Ready-MCP_%26_x402-7C4DFF?style=for-the-badge" alt="MCP & x402 Ready" />&nbsp;
  <img src="https://img.shields.io/badge/Dual_Runtime-Batch_%2B_Standby_API-FF6D00?style=for-the-badge" alt="Batch + Standby API" />
</p>

## Airbnb Scraper — Stays, Total Price, Host, Amenities & Reviews 🚀

**foXLabs Hospitality, Travel & Real Estate Series:** [Booking.com Hotels Scraper](https://apify.com/foxlabs/booking-hotels-scraper) · [Tripadvisor Reviews Scraper](https://apify.com/foxlabs/tripadvisor-reviews-scraper) · [Zillow Scraper](https://apify.com/foxlabs/zillow-scraper) · [Redfin Real Estate Scraper](https://apify.com/foxlabs/redfin-scraper) · [Yelp Business Leads Scraper](https://apify.com/foxlabs/yelp-business-scraper) · [Google Maps Leads](https://apify.com/foxlabs/google-maps-scraper)

🎉 Extract complete **Airbnb short-term rental listings, regulated total & nightly price breakdowns, exact GPS coordinates, all 6 guest rating subcategories, Superhost metrics, commercial host B2B registration contacts, municipal STR license numbers, amenities and paginated guest reviews** across any city, neighborhood or room URL — with **no Airbnb account, no cookies and no user API keys**.

Built for short-term rental (STR) revenue managers, property-management B2B sales teams, real-estate yield analysts, municipal compliance researchers and autonomous AI agents.

### 🔍 What is the Airbnb Scraper — and when should you use it?

Most Airbnb scrapers split search and reviews into two separate paid tools, capture only headline teaser nightly prices (hiding cleaning fees, taxes and multi-night discounts), and overlook commercial trader contact details published by professional property managers.

This Actor unifies discovery, full room/host enrichment and guest review pagination in a single lightweight run:

- **City, neighborhood & date search** (`locations`) — searches any city, region or district (`"Paris, France"`, `"Miami Beach, FL"`, `"Tokyo, Japan"`) with check-in/check-out dates, guest composition (`adults`, `children`, `pets`), currency (`USD`, `EUR`, `GBP`, `CAD`, `AUD`, `JPY`, etc.), room type (`entire_home`, `private_room`, `shared_room`) and price filters.
- **Direct room URLs & IDs** (`listingUrls`) — accepts specific `https://www.airbnb.com/rooms/<id>` URLs across any international Airbnb domain (`airbnb.fr`, `airbnb.co.uk`, `airbnb.de`) or bare numeric room IDs.
- **Transparent total & nightly price breakdown** — captures `totalPrice`, `originalTotalPrice` (pre-discount price), `nightlyPrice`, `nightsCount`, `accommodationSubtotal`, `taxesAndFees`, `discountNote`, `freeCancellation` and `payZeroUpfront`.
- **Commercial host B2B lead enrichment** (`enrichDetails: true`) — extracts Superhost status, `hostYearsHosting`, host review totals, municipal STR `registrationNumber`, and — where hosts operate as registered businesses (`isBusinessHost: true`) — **`businessName`, `businessRegistry`, `businessRegistryNumber`, `businessEmail`, `businessPhone` and `businessAddress`**.
- **Paginated verified guest reviews** (`mode: "listingsAndReviews"` or `"reviewsOnly"`) — collects guest reviews with star rating, UTC ISO-8601 `createdAt`, reviewer name & location, stay highlight (`"Stayed with kids"`), localized + original-language comments and host replies.

**Use it when you need:** date-specific ADR & total-price benchmarking against competing vacation rentals; B2B lead generation targeting professional Airbnb property-management companies in EU/UK/APAC markets (`businessEmail`, `businessPhone`); municipal STR license & geospatial supply mapping; or guest review sentiment audits.

**Use something else when:** you need **future 365-day calendar occupancy estimations** or **private host payout analytics** (Airbnb does not distinguish owner-blocked calendar dates from guest bookings on public pages). For traditional hotels and OTAs in the same destination, pair this Actor with [Booking.com Hotels Scraper](https://apify.com/foxlabs/booking-hotels-scraper) and [Tripadvisor Reviews Scraper](https://apify.com/foxlabs/tripadvisor-reviews-scraper).

### 🤖 Use with AI agents (MCP, Claude, Cursor & x402)

**Already connected to the Apify MCP server?** Ask your AI assistant to call `foxlabs/airbnb-scraper`.

- **Hosted MCP URL (zero install):** `https://mcp.apify.com?tools=foxlabs/airbnb-scraper`
- **Local stdio config (Claude Desktop, Cursor, Cline, Windsurf):**

```json
{
  "mcpServers": {
    "airbnb-scraper": {
      "command": "npx",
      "args": ["-y", "@apify/actors-mcp-server", "--tools", "foxlabs/airbnb-scraper"],
      "env": { "APIFY_TOKEN": "YOUR_APIFY_TOKEN" }
    }
  }
}
```

**Your agent can pay for its own runs.** This Actor uses pay-per-event pricing and supports agentic micropayments, allowing autonomous agents to run queries and settle usage over **x402 (USDC on Base)** or **Skyfire** as well as standard Apify tokens. Billing is strictly per delivered `listing` or `review` row; diagnostic `status` rows are `$0.00`.

Copy-paste prompt for Claude, ChatGPT, Cursor or any MCP-enabled assistant:

```text
Use the Apify Actor `foxlabs/airbnb-scraper` to collect public Airbnb stays, total/nightly pricing, commercial host details, amenities and guest reviews.

Input fields:
- `locations`: array of cities, regions or neighborhoods (e.g. ["Paris, France", "Montmartre, Paris"])
- `listingUrls`: optional array of Airbnb /rooms/<id> URLs or numeric room IDs
- `mode`: "listingsAndReviews" (default) | "listingsOnly" | "reviewsOnly"
- `maxListingsPerLocation`: integer 1..270 (default 10)
- `enrichDetails`: boolean (default true) — fetches 6 rating subcategories, host tenure, B2B trader contacts & full amenities
- `maxReviewsPerListing`: integer 0..500 (default 5)
- `checkin` / `checkout`: YYYY-MM-DD dates for exact total & nightly pricing
- `adults` / `children` / `pets`: guest party counts
- `currency`: ISO 4217 currency code (default "USD", e.g. "EUR", "GBP")
- `roomTypeFilter`: "any" | "entire_home" | "private_room" | "shared_room"
- `minPrice` / `maxPrice`: optional integer price bounds

Start with:
{"locations":["Paris, France"],"mode":"listingsAndReviews","maxListingsPerLocation":10,"enrichDetails":true,"maxReviewsPerListing":5,"checkin":"2027-02-10","checkout":"2027-02-14","currency":"EUR"}
```

**Things you can ask your AI agent:**

- *"Find 20 entire-home Airbnbs in Paris for 2027-03-10 to 2027-03-14 in EUR, rank them by cleanlinessRating and totalPrice, and flag commercial hosts with business emails."*
- *"Pull the latest 50 guest reviews on these 3 competitor Airbnb room URLs and summarize recurring complaints about noise, Wi-Fi or check-in."*
- *"Compare average 4-night total prices for 2-bedroom stays across Miami Beach, Brickell and Wynwood."*

The machine-readable Actor summary, MCP metadata and OpenAPI schema live at `https://apify.com/foxlabs/airbnb-scraper.md`.

### 📋 Overview

Everything needed to extract complete short-term rental pricing, property specs, commercial host disclosures and verified guest reviews in one unified 63-column dataset.

| Property | Details |
|---|---|
| **Public data source** | Public Airbnb search results, room detail pages & verified guest review feeds (`airbnb.com`) |
| **Authentication required** | None — zero Airbnb account, session cookies or user proxies |
| **Container footprint** | Lightweight `256 MB` HTTP runtime (no Chromium browser overhead) |
| **Output row types (`rowType`)** | `listing` (`$0.0025`), `review` (`$0.0012`), `status` (`$0.00` diagnostic rows) |
| **Deduplication & restart safety** | Deterministic `rowKey` (`listing:<roomId>`, `review:<reviewId>`) — zero duplicate rows or double charges |
| **Execution modes** | Standard Batch Dataset runs + synchronous Standby HTTP API (`GET /`, `GET /health`, `POST /scrape`) |

**Why teams pick this Actor:**

- 💵 **Regulated total price + itemized subtotal/taxes** — captures `totalPrice`, `nightlyPrice`, `originalTotalPrice`, `accommodationSubtotal` and `taxesAndFees` for real apples-to-apples ADR analysis.
- 🏢 **Commercial host B2B contact leads** — extracts `businessName`, `businessRegistryNumber`, `businessEmail`, `businessPhone`, `businessAddress` and municipal `registrationNumber` wherever disclosed.
- ⭐ **All 6 Airbnb rating subcategories** — `accuracyRating`, `checkinRating`, `cleanlinessRating`, `communicationRating`, `locationRating` and `valueRating`.
- 🔀 **Listings + Reviews in one Actor** — choose `listingsOnly`, `listingsAndReviews`, or `reviewsOnly` without stitching two separate Actors together.
- 🛡️ **Strict `null` discipline** — brand-new unrated listings and private individual hosts emit `null` (never fake `0`s) so SQL averages remain clean.

### ✨ Key Features

- 🗺️ **Location, Neighborhood & Direct Room URL Modes** — Search any global city/district via `locations` or monitor specific `/rooms/<id>` URLs and raw room IDs via `listingUrls`.
- 📅 **Date, Party & Currency Precision** — Customize `checkin`, `checkout`, `adults`, `children`, `pets`, `roomTypeFilter` (`entire_home`, `private_room`, `shared_room`), `minPrice`/`maxPrice`, and `currency` (`USD`, `EUR`, `GBP`, `CAD`, `AUD`, `JPY`, etc.).
- 🧑‍💼 **Host & Trader Disclosure Intelligence (`enrichDetails: true`)** — Pulls `isSuperhost`, `isGuestFavorite`, `isBusinessHost`, `hostId`, `hostName`, `hostYearsHosting`, `hostRating`, `hostReviewsCount`, municipal STR `registrationNumber`, and commercial trader contact fields.
- 🛋️ **Full Property Specs, GPS & Media** — Extracts `latitude`, `longitude`, `personCapacity`, `bedrooms`, `beds`, `baths`, `amenities[]` (`amenitiesCount`), `description`, `spaceDescription`, `guestAccessDescription`, `houseRulesNote`, `petsAllowed` and high-res `photos[]`.
- 💬 **Paginated Guest Reviews with Host Responses** — Collects up to `500` verified guest reviews per room (`createdAt`, `rating`, `language`, `comments`, `originalComments`, `reviewHighlight`, `reviewerName`, `reviewerLocation`, `hostResponse`).
- ⚡ **Fast Search-Only Toggle (`enrichDetails: false`)** — Skip individual room detail fetches when you only need high-speed search pricing, ratings, badges and GPS coordinates across hundreds of stays.

### 🎬 Quick Start (API & Standby HTTP)

**1. Synchronous Batch API call (returns clean JSON records directly):**

```bash
curl -X POST "https://api.apify.com/v2/acts/foxlabs~airbnb-scraper/run-sync-get-dataset-items?token=YOUR_APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"locations":["Paris, France"],"mode":"listingsAndReviews","maxListingsPerLocation":10,"enrichDetails":true,"maxReviewsPerListing":5,"checkin":"2027-02-10","checkout":"2027-02-14","currency":"USD"}'
```

**2. Real-time Standby HTTP API (`POST /scrape`):**

```bash
curl -X POST "https://foxlabs--airbnb-scraper.apify.actor/scrape?token=YOUR_APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"locations":["Paris, France"],"mode":"listingsOnly","maxListingsPerLocation":5,"enrichDetails":false,"checkin":"2027-02-10","checkout":"2027-02-14"}'
```

### 🚀 Getting Started (3 steps)

1. **Enter destinations or room URLs** — Add cities or neighborhoods in **Locations** (`"Paris, France"`, `"Montmartre, Paris"`), or paste room links/IDs in **Listing URLs**.
2. **Set travel dates, mode & enrichment** — Pick `checkin` & `checkout` (`YYYY-MM-DD`), `currency`, `mode` (`listingsAndReviews`, `listingsOnly`, `reviewsOnly`), and toggle `enrichDetails` (`true` for host B2B contacts & 6 rating subcategories).
3. **Run & export** — Click **Start** and download your dataset as JSON, CSV, Excel, Parquet or XML.

### 📥 Input & Filters

```json
{
  "locations": ["Paris, France", "Lyon, France"],
  "listingUrls": [],
  "mode": "listingsAndReviews",
  "maxListingsPerLocation": 20,
  "enrichDetails": true,
  "maxReviewsPerListing": 10,
  "checkin": "2027-03-15",
  "checkout": "2027-03-19",
  "adults": 2,
  "children": 0,
  "pets": 0,
  "currency": "EUR",
  "roomTypeFilter": "entire_home",
  "minPrice": 80,
  "maxPrice": 500
}
```

| Field | Type | Default | Description |
|---|---|---|---|
| `locations` | `array<string>` | `["Paris, France"]` | Cities, regions or neighborhoods to search on Airbnb. |
| `listingUrls` | `array<string>` | `[]` | Direct Airbnb `/rooms/<id>` URLs (any regional domain) or bare numeric room IDs. |
| `mode` | `string` | `"listingsAndReviews"` | Output mode: `"listingsOnly"`, `"listingsAndReviews"`, or `"reviewsOnly"`. |
| `maxListingsPerLocation` | `integer` | `10` | Maximum listings collected per location (`1`–`270`). |
| `enrichDetails` | `boolean` | `true` | Open room detail page for 6 rating subcategories, host tenure, B2B trader contacts, STR license & full amenities. |
| `maxReviewsPerListing` | `integer` | `5` | Maximum verified guest reviews collected per listing (`0`–`500`). |
| `checkin` / `checkout` | `string` | `"2027-02-10"` / `"2027-02-14"` | `YYYY-MM-DD` stay dates used to calculate exact `totalPrice`, `nightlyPrice` and `taxesAndFees`. |
| `adults` / `children` / `pets` | `integer` | `2` / `0` / `0` | Guest party counts. |
| `currency` | `string` | `"USD"` | Three-letter ISO 4217 currency code (`USD`, `EUR`, `GBP`, `CAD`, `AUD`, `JPY`, `CHF`, etc.). |
| `roomTypeFilter` | `string` | `"any"` | Filter by space type: `"any"`, `"entire_home"`, `"private_room"`, or `"shared_room"`. |
| `minPrice` / `maxPrice` | `integer` | — | Optional price filter bounds in selected `currency`. |
| `proxyConfiguration` | `object` | `{"useApifyProxy": true}` | Managed automatically via Apify Proxy. |

**Copy-paste input recipes:**

- **EU/UK commercial property-manager B2B lead harvest (`listingsOnly` + `enrichDetails: true`):**
  `{"locations":["Paris, France","Nice, France","Bordeaux, France"],"mode":"listingsOnly","maxListingsPerLocation":40,"enrichDetails":true,"checkin":"2027-03-10","checkout":"2027-03-14","currency":"EUR","roomTypeFilter":"entire_home"}`
- **Fast search-level ADR & GPS comp sweep (`enrichDetails: false`):**
  `{"locations":["Miami Beach, FL"],"mode":"listingsOnly","maxListingsPerLocation":80,"enrichDetails":false,"checkin":"2027-04-01","checkout":"2027-04-05","adults":4,"currency":"USD"}`
- **Deep competitor review audit (`reviewsOnly`):**
  `{"locations":[],"listingUrls":["https://www.airbnb.com/rooms/1160831669077274383"],"mode":"reviewsOnly","maxReviewsPerListing":100,"currency":"USD"}`

### 📤 Output Schema & Real Sample Record

Every Dataset row carries `rowType` (`"listing"`, `"review"`, or free diagnostic `"status"`) and a deterministic `rowKey` (`listing:<roomId>` or `review:<reviewId>`).

#### Listing rows (`rowType: "listing"` — 63 columns)

| Group | Fields |
|---|---|
| **Identity & Specs** | `rowKey`, `roomId`, `listingUrl`, `searchLocation`, `title`, `subtitle`, `locationName`, `roomType`, `personCapacity`, `bedrooms`, `beds`, `baths`, `roomSummary` |
| **Pricing & Policies** | `checkin`, `checkout`, `currency`, `totalPrice`, `originalTotalPrice`, `nightlyPrice`, `nightsCount`, `accommodationSubtotal`, `taxesAndFees`, `discountNote`, `freeCancellation`, `payZeroUpfront` |
| **Ratings & Badges** | `rating`, `reviewsCount`, `accuracyRating`, `checkinRating`, `cleanlinessRating`, `communicationRating`, `locationRating`, `valueRating`, `isGuestFavorite`, `isSuperhost`, `isBusinessHost`, `badges[]` |
| **Coordinates & Host** | `latitude`, `longitude`, `hostId`, `hostName`, `hostIsVerified`, `hostRating`, `hostReviewsCount`, `hostYearsHosting`, `hostProfilePictureUrl` |
| **B2B Trader & License** | `businessName`, `businessRegistry`, `businessRegistryNumber`, `businessEmail`, `businessPhone`, `businessAddress`, `registrationNumber` |
| **Content & Media** | `description`, `spaceDescription`, `guestAccessDescription`, `houseRulesNote`, `petsAllowed`, `amenitiesCount`, `amenities[]`, `thumbnailUrl`, `photos[]`, `scrapedAt` |

#### Review rows (`rowType: "review"`)

| Field | Type | Description |
|---|---|---|
| `rowKey` / `reviewId` / `roomId` | `string` | Unique key `review:<reviewId>`, review ID and parent room ID |
| `rating` / `reviewRating` | `integer` | `1`–`5` star guest rating |
| `createdAt` / `localizedDate` | `string` | UTC ISO-8601 timestamp (`"2026-10-29T09:06:25Z"`) and relative date string |
| `language` / `comments` / `originalComments` | `string` | ISO language code, localized review text and original-language text |
| `reviewHighlight` | `string \| null` | Stay context tag (`"Stayed a few nights"`, `"Stayed with kids"`) |
| `reviewerId` / `reviewerName` / `reviewerLocation` | `string \| null` | Guest ID, first name and hometown/country |
| `hostName` / `hostResponse` / `hostRespondedDate` | `string \| null` | Host reply text and response date |

#### Real sample records (from verified platform QA & D+0 runs `3GRSSdD3J7v0bdDNw` / `4rr5ZgLiyUzuPpQ4U`)

```json
{
  "rowType": "listing",
  "rowKey": "listing:1160831669077274383",
  "roomId": "1160831669077274383",
  "listingUrl": "https://www.airbnb.com/rooms/1160831669077274383",
  "searchLocation": "Paris, France",
  "title": "Apartment in Paris",
  "subtitle": "Studio Montmartre",
  "roomType": "Entire home/apt",
  "personCapacity": 2,
  "bedrooms": 1,
  "beds": 1,
  "baths": 1,
  "checkin": "2027-02-10",
  "checkout": "2027-02-14",
  "currency": "USD",
  "totalPrice": 572.69,
  "originalTotalPrice": 622.99,
  "nightlyPrice": 124.32,
  "nightsCount": 4,
  "accommodationSubtotal": 497.27,
  "taxesAndFees": 75.42,
  "freeCancellation": true,
  "payZeroUpfront": true,
  "rating": 4.83,
  "reviewsCount": 133,
  "accuracyRating": 4.81,
  "checkinRating": 4.92,
  "cleanlinessRating": 4.8,
  "communicationRating": 4.9,
  "locationRating": 4.8,
  "valueRating": 4.74,
  "isGuestFavorite": true,
  "isSuperhost": true,
  "isBusinessHost": true,
  "latitude": 48.8807,
  "longitude": 2.3465,
  "hostId": "393560093",
  "hostName": "Sun",
  "hostIsVerified": true,
  "hostRating": 4.79,
  "hostReviewsCount": 387,
  "hostYearsHosting": 2.4,
  "businessName": "Sci sun",
  "businessRegistryNumber": "984094276",
  "businessEmail": "shisun65@gmail.com",
  "businessPhone": "+33 6 58 60 16 14",
  "registrationNumber": "7510915368596",
  "amenitiesCount": 34,
  "amenities": ["Kitchen", "Wifi", "TV", "Washer", "Hair dryer"]
}
```

```json
{
  "rowType": "review",
  "rowKey": "review:1807140920826986749",
  "reviewId": "1807140920826986749",
  "roomId": "1160831669077274383",
  "listingUrl": "https://www.airbnb.com/rooms/1160831669077274383",
  "title": "Studio Montmartre",
  "reviewRating": 5,
  "rating": 5,
  "createdAt": "2026-10-29T09:06:25Z",
  "localizedDate": "2 weeks ago",
  "language": "en",
  "comments": "It was a very good place, located very close to the metro. The accommodation was very clean and equipped with everything necessary.",
  "reviewHighlight": "Stayed a few nights",
  "reviewerId": "271212247",
  "reviewerName": "Vako",
  "reviewerLocation": "Tbilisi, Georgia",
  "hostName": "Sun",
  "hostResponse": null
}
```

Every completed run also writes a `SOURCE_REPORT` telemetry summary to the default Key-Value Store.

### 🧪 Data Quality — Measured

Verified on the Apify platform across QA runs (`3GRSSdD3J7v0bdDNw`, `MHhd62skLzLWQwdEW`, `AU5RWUo4l2T4OPmvQ`) and live D+0 billing verification (`4rr5ZgLiyUzuPpQ4U`, `GSJ1Mjr4wTMk8J2bi` on 2026-11-14):

- **100% row uniqueness:** Deduplicated by `listing:<roomId>` and `review:<reviewId>` across overlapping neighborhood searches (`0` duplicates).
- **Complete pricing & coordinate fill:** `roomId`, `listingUrl`, `title`, `totalPrice`, `nightlyPrice`, `latitude` and `longitude` populated on `100%` of dated active listings; commercial EU/UK trader fields (`businessName`, `businessEmail`, `businessPhone`, `registrationNumber`) populated wherever disclosed by professional hosts (`isBusinessHost: true`).
- **Exact billing alignment:** Live D+0 run `4rr5ZgLiyUzuPpQ4U` (`4` listings) settled at `{listing: 4, review: 0}`, and empty-input run `GSJ1Mjr4wTMk8J2bi` (`1` diagnostic `status` row) settled at `{listing: 0, review: 0}`.

### ⏱️ Performance — Measured

Measured on the Apify platform at the default **`256 MB`** memory tier:

- **High-efficiency `256 MB` execution:** Unlike 2 GB – 4 GB Playwright Airbnb scrapers, all search, detail and review requests run over lightweight HTTP inside `256 MB` RAM.
- **Fast search-card mode:** Setting `enrichDetails: false` with `mode: "listingsOnly"` fetches ~18 priced listings per search page in seconds without opening individual room pages.
- **Migration idempotency:** Container restarts automatically read delivered `rowKey` values from the Dataset and resume cleanly without duplicating rows or charges.

### 💼 Use Cases

1. **Dynamic STR Pricing & Comp-Set Revenue Management**
   - *Input:* `{"locations":["Miami Beach, FL"],"mode":"listingsOnly","maxListingsPerLocation":60,"enrichDetails":false,"checkin":"2027-04-01","checkout":"2027-04-05","adults":4,"currency":"USD"}`
   - *Output:* Exact `totalPrice`, `nightlyPrice`, `originalTotalPrice` discounts, `taxesAndFees`, `freeCancellation` and GPS coordinates across competing nearby properties.
   - *Business action:* Adjust nightly ADR and cleaning-fee structures dynamically against neighborhood comp sets across peak and off-peak check-in windows.

2. **Property-Management B2B Lead Generation (`isBusinessHost` Contacts)**
   - *Input:* `{"locations":["Paris, France","Lyon, France","Barcelona, Spain"],"mode":"listingsOnly","maxListingsPerLocation":50,"enrichDetails":true,"currency":"EUR"}`
   - *Output:* Enriched commercial host profiles carrying `businessName`, `businessRegistryNumber`, `businessEmail`, `businessPhone`, `businessAddress` and `hostReviewsCount`.
   - *Business action:* Sell PMS software, smart locks, linen/cleaning services or STR insurance directly to multi-property commercial operators.

3. **Hospitality Defect & Guest Sentiment Auditing (`reviewsOnly`)**
   - *Input:* `{"locations":[],"listingUrls":["https://www.airbnb.com/rooms/1160831669077274383"],"mode":"reviewsOnly","maxReviewsPerListing":100}`
   - *Output:* Chronological guest reviews with star score, stay highlight, original/translated comments and `hostResponse`.
   - *Business action:* Audit cleanliness, check-in friction or maintenance issues across managed portfolios or acquisition targets.

4. **Municipal STR Compliance & Supply Density Mapping**
   - *Input:* `{"locations":["Montmartre, Paris","Le Marais, Paris","Latin Quarter, Paris"],"mode":"listingsOnly","maxListingsPerLocation":100,"enrichDetails":true}`
   - *Output:* Deduplicated neighborhood listings with `latitude`, `longitude`, `roomType`, `personCapacity` and `registrationNumber`.
   - *Business action:* Analyze licensed vs. unlicensed STR density and commercial vs. individual host share by district.

### 🔗 Integrations (Node.js, Python, n8n, Make & Clay)

#### JavaScript / Node.js (`apify-client`)

```javascript
import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('foxlabs/airbnb-scraper').call({
    locations: ['Paris, France'],
    mode: 'listingsAndReviews',
    maxListingsPerLocation: 15,
    maxReviewsPerListing: 5,
    checkin: '2027-02-10',
    checkout: '2027-02-14',
    currency: 'EUR',
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(`Extracted ${items.length} Airbnb rows`, items[0]);
```

#### Python (`apify-client` v3)

```python
import os
from apify_client import ApifyClient

client = ApifyClient(os.environ["APIFY_TOKEN"])
run = client.actor("foxlabs/airbnb-scraper").call(
    run_input={
        "locations": ["Paris, France"],
        "mode": "listingsAndReviews",
        "maxListingsPerLocation": 15,
        "maxReviewsPerListing": 5,
        "checkin": "2027-02-10",
        "checkout": "2027-02-14",
        "currency": "EUR",
    }
)

for item in client.dataset(run.default_dataset_id).iterate_items():
    if item["rowType"] == "listing":
        print(item["roomId"], item["subtitle"], item["totalPrice"], item["currency"])
```

*(Written for `apify-client` v3 where `call()` returns a `Run` object exposing `run.default_dataset_id`; on `apify-client` v1/v2 use `run["defaultDatasetId"]`.)*

#### n8n, Make, Zapier & Clay

- **Weekly ADR comp tracker (n8n / Make / Zapier):** Schedule weekly runs across your target check-in dates → push `roomId`, `totalPrice`, `nightlyPrice` and `rating` to BigQuery, Snowflake or Google Sheets.
- **Clay real-time room lookup:** POST `{"locations":[],"listingUrls":["{{airbnb_url}}"],"mode":"listingsOnly","enrichDetails":true}` to `https://foxlabs--airbnb-scraper.apify.actor/scrape` to enrich STR leads inline.

### 📊 Pricing (Pay-Per-Event)

Transparent **Pay-Per-Event (PPE)** pricing — pay only for unique listings and reviews delivered:

| Event Name | Trigger | Price per Item | Price per 1,000 |
|---|---|---|---|
| `listing` | Once per unique `rowType: "listing"` property record delivered | **$0.0025** | **$2.50 / 1,000** |
| `review` | Once per unique `rowType: "review"` guest review record delivered | **$0.0012** | **$1.20 / 1,000** |
| `status` *(diagnostic)* | Empty input, unfound room ID, or zero-match filter note | **$0.00 (Free)** | **$0.00** |

**Worked cost examples:**

- **100 Paris listings with commercial host B2B enrichment (`listingsOnly`):** `100 × $0.0025` = **$0.25**
- **25 listings + 10 latest reviews per listing (`listingsAndReviews`):** `25 × $0.0025 + 250 × $0.0012` = **$0.3625**
- **500 guest reviews on competitor room URLs (`reviewsOnly`):** `500 × $0.0012` = **$0.60**

**Billing guarantees:**

- **Enrichment costs `$0.00` extra per listing:** Whether `enrichDetails` is `true` or `false`, each unique listing row triggers only one `$0.0025` `listing` event.
- **Proxy traffic is included:** Apify Proxy rotation is included inside the per-event price above.
- **Exact spend cap support:** Configure **Maximum cost per run** in Apify options; `ChargingManager` enforces your cap cleanly before emitting each batch. *(Note: if Apify applies its platform `apify-actor-start` fee on your plan, that start event applies when a run starts, including runs that return zero billable rows.)*

### ❓ Frequently Asked Questions (FAQ)

#### Do I need an Airbnb account, cookies, API key, or custom residential proxies?

No. The Actor collects public Airbnb search listings, room details and guest reviews completely keylessly on our infrastructure. You never supply Airbnb login credentials, session cookies or third-party proxy keys, so you can start extracting structured data in Console or via API immediately.

#### Why should I always specify `checkin` and `checkout` dates when benchmarking prices?

Airbnb calculates regulated total trip pricing, cleaning fees, multi-night length-of-stay discounts, local occupancy taxes and real room availability only when specific travel dates are provided. Passing `checkin` and `checkout` (`YYYY-MM-DD`) ensures `totalPrice`, `nightlyPrice`, `originalTotalPrice`, `accommodationSubtotal` and `taxesAndFees` reflect exact bookable rates for that window.

#### How many listings can Airbnb return for a single city search, and how do I scale to 5,000+ stays?

Airbnb caps individual search result cursors at roughly 15 pages (~18 listings per page, or **~270 listings** per search query). To collect thousands of listings across a major metropolis like Paris, London or New York, pass neighborhood-level queries in `locations` (for example `["Montmartre, Paris", "Le Marais, Paris", "Saint-Germain-des-Prés, Paris", "Bastille, Paris"]`) or segment runs by `minPrice` / `maxPrice` brackets; deterministic `rowKey` deduplication automatically prevents any overlapping room from being written or billed twice.

#### When are `businessEmail`, `businessPhone`, and `businessRegistryNumber` populated?

Under EU Digital Services Act (DSA), UK consumer transparency rules and Japanese hospitality regulations, hosts who declare that they host as a registered business (`isBusinessHost: true`) publish their legal trader details on Airbnb. Whenever a host publishes that disclosure, the Actor extracts `businessName`, `businessRegistry`, `businessRegistryNumber`, `businessEmail`, `businessPhone` and `businessAddress`; for private individual hosts, those fields cleanly return `null`.

#### When should I set `enrichDetails: false` vs. keeping `enrichDetails: true`?

Keep `enrichDetails: true` (default) when you want all 6 rating subcategories (`cleanlinessRating`, `locationRating`, etc.), `hostYearsHosting`, commercial `businessEmail` / `businessPhone` contacts, municipal `registrationNumber`, full `description` and the complete `amenities[]` list. Set `enrichDetails: false` with `mode: "listingsOnly"` when you want maximum speed for large ADR, rating and GPS comp sweeps straight from search cards.

#### Can I pass regional Airbnb URLs such as `airbnb.fr`, `airbnb.co.uk`, or `airbnb.de`?

Yes. `listingUrls` accepts room links from any regional Airbnb country domain (as well as bare numeric room IDs like `"1160831669077274383"`), normalizes canonical room URLs, and converts monetary figures into whichever ISO 4217 `currency` (`EUR`, `GBP`, `USD`, `CAD`, `AUD`, `JPY`) you specify in your input.

#### How do I scrape only specific `listingUrls` without running the default Paris search?

In the Apify Console Input tab, clear the prefilled `"Paris, France"` entry in **Locations** before starting. When calling via the API, Python/Node.js SDK, n8n or MCP, pass `"locations": []` explicitly alongside your `"listingUrls"` array so only your target room URLs are processed.

#### Why are some rating or tax fields `null` instead of `0`?

Brand-new listings with fewer than 3 stays do not display public star ratings on Airbnb yet, and certain jurisdictions include all taxes directly inside `totalPrice` without displaying a separate tax line. Following strict data-hygiene standards, unknown or unexposed numbers are always emitted as `null` — never fake `0` values that would distort downstream averages.

#### What happens if one room URL in my list was unlisted or deactivated by the host?

Deactivated or invalid room IDs never crash your batch. The Actor writes one free `rowType: "status"` diagnostic record identifying the exact room ID that returned not-found, bills `$0.00` for that row, and continues scraping all remaining active rooms and locations.

#### Does guest review extraction preserve both original-language comments and translations?

Yes. Every `rowType: "review"` record includes `language` (ISO code), `comments` (the localized/English review text served by Airbnb), `originalComments` (when the review was originally written in another language), `createdAt` (exact UTC ISO-8601 timestamp), `reviewHighlight`, reviewer location and any `hostResponse`.

#### Can I call this Actor synchronously from an AI agent or Clay table?

Yes. You can invoke it as a tool via the Apify MCP server (`foxlabs/airbnb-scraper`), call the synchronous `run-sync-get-dataset-items` REST endpoint, or send a JSON payload to `POST /scrape` in Apify Standby mode for low-latency real-time responses.

#### What happens if Apify restarts or migrates my container mid-batch?

On startup, the Actor scans the run's default Dataset for existing `rowKey` identifiers (`listing:<roomId>` and `review:<reviewId>`) and skips any listing or review already delivered, ensuring zero duplicate rows and zero duplicate event charges.

### 🐛 Troubleshooting

- **Dataset contains only a `rowType: "status"` row with `"EMPTY_INPUT"`:** Both `locations` and `listingUrls` were empty. Provide at least one search destination or room URL/ID.
- **Listing rows have `hostName: null` and `amenities: []`:** You ran with `enrichDetails: false` (fast search-card mode), which intentionally skips opening individual `/rooms/<id>` detail pages. Set `enrichDetails: true` to populate host, B2B trader, subcategory rating and amenity fields.
- **`checkin` / `checkout` returned zero available rooms:** Dates in the past or sold-out holiday dates return zero available stays on Airbnb. Use future `YYYY-MM-DD` dates with open inventory.
- **Fewer listings than `maxListingsPerLocation`:** Narrow `minPrice` / `maxPrice` or `roomTypeFilter` bounds may leave fewer matching stays in that neighborhood; check `SOURCE_REPORT` in the Key-Value Store.

### 🚧 What It Does Not Do

- Does **not** infer private occupancy rates or host revenue from blocked calendar dates (Airbnb calendars do not distinguish owner blocks from guest reservations).
- Does **not** reveal exact street house numbers hidden by Airbnb prior to confirmed booking (`latitude` and `longitude` reflect the public map pin Airbnb publishes on the listing).
- Does **not** log into guest or host accounts or submit booking inquiries.

### ⚠️ Trademark Notice

This Actor is an independent data-collection tool built by **foXLabs** and is not affiliated with, endorsed by, or sponsored by Airbnb, Inc. "Airbnb" and "Superhost" are trademarks of Airbnb, Inc., referenced solely to describe compatibility with publicly accessible web pages.

### ⚖️ Is It Legal to Scrape Public Airbnb Data?

This Actor accesses only publicly visible Airbnb search results, room listings, trader disclosures and public guest reviews available to any unauthenticated browser visitor. Commercial trader contact fields (`businessEmail`, `businessPhone`, `businessAddress`) and reviewer first names may constitute personal data under GDPR, CCPA and local laws; ensure you have a valid lawful basis before storing or contacting exported leads.

### 🤝 Support, Custom Data & Contact

- 🌐 **Website & full portfolio:** [data.foxlabs.com.tr](https://data.foxlabs.com.tr)
- 📧 **Custom data & enterprise inquiries:** info@foxlabs.com.tr
- 🐛 **Bug reports & feature requests:** open an issue in the Actor's **Issues** tab on Apify Store (include your Run ID)
- 🧰 **Browse all foXLabs Actors:** [apify.com/foxlabs](https://apify.com/foxlabs)

### Changelog

#### 0.1.2 (2026-11-14)

- Upgraded Store README to full SIÁN standard with MCP & x402 AI agent configuration, Standby HTTP `POST /scrape` examples, measured platform QA & D+0 billing benchmarks, worked PPE cost breakdowns, and expanded 12-question FAQ.

#### 0.1.0 (2026-11-13)

- Initial release of `foxlabs/airbnb-scraper` supporting multi-location search pagination, direct `listingUrls`, regulated total/nightly price breakdowns, 6 rating subcategories, commercial host B2B disclosures, paginated guest reviews, and Batch + Standby HTTP modes.

# Changelog

This Actor's version history is a separate document: https://apify.com/foxlabs/airbnb-scraper/changelog.md

# Actor input Schema

## `locations` (type: `array`):

Cities, regions, or neighborhoods to search on Airbnb (e.g. 'Paris, France', 'Tokyo, Japan', 'Miami Beach, FL').

## `listingUrls` (type: `array`):

Optional Airbnb room URLs (https://www.airbnb.com/rooms/1160831669077274383) or numeric room IDs.

## `mode` (type: `string`):

Choose whether to extract listings only, listings plus guest reviews, or guest reviews only (for direct listingUrls).

## `maxListingsPerLocation` (type: `integer`):

Maximum number of search listings to collect per location (Airbnb serves ~18 listings per page up to ~270 per search).

## `enrichDetails` (type: `boolean`):

When enabled, fetches each listing's room page to extract 6 rating subcategories, Superhost stats, commercial host B2B registration/email/phone, full description, house rules, and all amenities.

## `maxReviewsPerListing` (type: `integer`):

Maximum number of guest reviews to extract per listing when mode includes reviews.

## `checkin` (type: `string`):

Optional check-in date in YYYY-MM-DD format for date-specific availability and exact total/nightly pricing.

## `checkout` (type: `string`):

Optional check-out date in YYYY-MM-DD format.

## `adults` (type: `integer`):

Number of adult guests (18+).

## `children` (type: `integer`):

Number of children (ages 2-17).

## `pets` (type: `integer`):

Number of pets.

## `currency` (type: `string`):

ISO 4217 currency code for prices (e.g. USD, EUR, GBP, CAD, AUD, JPY, TRY).

## `roomTypeFilter` (type: `string`):

Optional filter by accommodation type.

## `minPrice` (type: `integer`):

Optional minimum price filter in selected currency.

## `maxPrice` (type: `integer`):

Optional maximum price filter in selected currency.

## `proxyConfiguration` (type: `object`):

Apify Proxy settings. Defaults to automatic proxy selection (no user keys or cookies needed).

## Actor input object example

```json
{
  "locations": [
    "Paris, France"
  ],
  "listingUrls": [],
  "mode": "listingsAndReviews",
  "maxListingsPerLocation": 10,
  "enrichDetails": true,
  "maxReviewsPerListing": 5,
  "checkin": "2027-02-10",
  "checkout": "2027-02-14",
  "adults": 2,
  "children": 0,
  "pets": 0,
  "currency": "USD",
  "roomTypeFilter": "any",
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

## `results` (type: `string`):

No description

## `sourceReport` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "locations": [
        "Paris, France"
    ],
    "maxListingsPerLocation": 10,
    "maxReviewsPerListing": 5,
    "checkin": "2027-02-10",
    "checkout": "2027-02-14"
};

// Run the Actor and wait for it to finish
const run = await client.actor("foxlabs/airbnb-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "locations": ["Paris, France"],
    "maxListingsPerLocation": 10,
    "maxReviewsPerListing": 5,
    "checkin": "2027-02-10",
    "checkout": "2027-02-14",
}

# Run the Actor and wait for it to finish
run = client.actor("foxlabs/airbnb-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "locations": [
    "Paris, France"
  ],
  "maxListingsPerLocation": 10,
  "maxReviewsPerListing": 5,
  "checkin": "2027-02-10",
  "checkout": "2027-02-14"
}' |
apify call foxlabs/airbnb-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,foxlabs/airbnb-scraper"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/m4arFwbAAvsP6HU7J/builds/PXLSuMVe7j9n46Rs2/openapi.json
