# Airbnb Realtime API — Live Listing, Reviews & Search Lookups (`blackfalcondata/airbnb-realtime`) Actor Real-time Airbnb lookups via a persistent standby server — fetch a single listing, its reviews, or a location search in one HTTP call. No batch run, no polling. - **URL**: https://apify.com/blackfalcondata/airbnb-realtime.md - **Developed by:** [Black Falcon Data](https://apify.com/blackfalcondata) (community) - **Categories:** Real estate, Lead generation, Automation - **Stats:** 2 total users, 2 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $5.00 / 1,000 listing details This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. 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. Actors are written with capital "A". ## 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. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ### What does Airbnb Realtime API do? Airbnb Realtime API is a live HTTP service for Airbnb data — send one request and get a structured JSON record back in the **same response**, with no batch run to start and no dataset to poll. It exposes three GET routes: `/listing` returns one stay's full detail record (name, room type, price, rating, host description, amenities, GPS, photos), `/reviews` returns a listing's reviews as flat rows (text, rating, date, reviewer, host reply), and `/search` returns the listing cards matching a location query. Pass an Airbnb listing id or paste a room URL — both are accepted. Built for live enrichment inside your own app, workflow, or AI agent; you are billed per record returned, not per run. For bulk one-shot exports of an entire city, use the companion batch actors — [Airbnb Scraper](https://apify.com/blackfalcondata/airbnb-scraper?fpr=1h3gvi), [Airbnb Reviews Scraper](https://apify.com/blackfalcondata/airbnb-reviews-scraper?fpr=1h3gvi), and [Airbnb URL Scraper](https://apify.com/blackfalcondata/airbnb-url-scraper?fpr=1h3gvi) — instead. ### How to use this actor - 👉 **Register for a free Apify account** — no credit card required. - 🎉 Just click **[Sign up free on Apify →](https://console.apify.com/sign-up?fpr=1h3gvi&fp_sid=ctarich)** and complete a quick signup. - 💰 A free Apify account includes $5 in monthly credits — enough to test this actor. - ⏳ Call the API during the free trial, with no commitment or upfront payment required. ### Key features - **⚡ Real-time, single-call lookups** — a persistent server answers each request synchronously. Send one HTTP call, get the record back in the same response — no run to start, no dataset to poll, no waiting for a batch job to finish. Built for live enrichment inside your own app or agent. - **🔗 Listing, reviews & search routes** — three GET routes cover the common lookups: `/listing` for one stay's full record, `/reviews` for a listing's reviews as flat rows, and `/search` for the stays matching a location query. Pass an Airbnb listing id or paste a room URL — both are accepted. - **🏠 Detail-rich listing record** — each `/listing` response returns the structured stay record — name, room type, coordinates, average rating and review count, plus the host description and amenity list — in one call, ready to store or rank. - **💵 Price & ratings** — listing records include structured nightly price with currency alongside the average rating and review count, so you can rank and compare stays as they come back. - **📑 Live OpenAPI definition** — the actor ships an OpenAPI spec, so every route is documented and runnable straight from the Apify Console **Endpoints** tab — try a lookup with your token auto-attached, then copy the request into your own code. - **📤 Structured JSON responses** — every lookup returns a typed JSON record, ready to store or pipe into your app — no HTML parsing, no scraping glue on your side. - **📦 For bulk exports, use the batch trio** — this actor is built for live, per-request lookups. To export an entire city, every review, or a full URL list in one run, use the companion batch actors — Airbnb Scraper, Airbnb Reviews Scraper, and Airbnb URL Scraper — which are priced for volume. ### What data can you get from Airbnb? **Listing** (`/listing`, `/search`) — `listingId`, `listingUrl`, `name`, `title`, `roomType`, `price` (`amount`, `originalAmount`, `label`, `qualifier`, `currency`), `avgRating`, `reviewCount`, `coordinate` (`lat`, `lng`), `images`, `badges`, plus `description` and `amenities` on `/listing` (detail fields, absent on `/search` cards), and `scrapedAt`, `contentHash`. **Review** (`/reviews`) — `listingId`, `reviewId`, `text`, `rating`, `language`, `createdAt`, `localizedDate`, `reviewerName`, `reviewerId`, `reviewerLocation`, `hostResponse`, `highlight`. ### How to call the API This is an Apify **Standby Actor**: a long-running server you call over HTTP. The first request after an idle period boots the server (a brief cold start); subsequent requests are answered immediately. The base URL is shown on the actor's **Standby** / **Endpoints** tab in the Apify Console, in the form: ```` https://blackfalcondata--airbnb-realtime.apify.actor ```` Every request must be authenticated with your Apify API token, either as a query parameter (`?token=YOUR_TOKEN`) or an `Authorization: Bearer YOUR_TOKEN` header. The **Endpoints** tab renders this actor's full OpenAPI definition — you can try any lookup there with your token auto-attached, then copy the request straight into your code. #### `GET /listing` — one detail-rich listing Resolve a single stay by numeric ID **or** room URL. | Query param | Required | Description | |-------------|----------|-------------| | `id` | one of `id`/`url` | Numeric Airbnb listing ID (e.g. `12345678`) | | `url` | one of `id`/`url` | Full Airbnb room URL (e.g. `https://www.airbnb.com/rooms/12345678`) | | `currency` | no | ISO 4217 currency for the price (default `USD`) | #### `GET /reviews` — a listing's reviews | Query param | Required | Description | |-------------|----------|-------------| | `id` / `url`| one of them | Listing identifier, same as `/listing` | | `limit` | no | Max reviews to return, `1`–`100` (default `20`) | | `sort` | no | `recent` (newest first) or `best` (most relevant, default) | #### `GET /search` — listing cards by location | Query param | Required | Description | |-------------|----------|-------------| | `location` | yes | Free-text location (e.g. `New York, NY`, `Paris, France`) | | `limit` | no | Max listings, `1`–`50` (default `20`) | | `roomTypes` | no | Comma-separated filter: `Entire home/apt`, `Private room`, `Shared room`, `Hotel room` | #### `GET /health` Returns `{"ok":true}` when the server is up. Not charged. ### Request examples **One listing by id** — full detail-rich record. ```bash curl "https://blackfalcondata--airbnb-realtime.apify.actor/listing?id=12345678¤cy=USD&token=YOUR_TOKEN" ```` **Reviews for a listing** — newest first. ```bash curl "https://blackfalcondata--airbnb-realtime.apify.actor/reviews?id=12345678&limit=20&sort=recent&token=YOUR_TOKEN" ``` **Search a location** — entire homes in New York. ```bash curl "https://blackfalcondata--airbnb-realtime.apify.actor/search?location=New%20York%2C%20NY&limit=20&roomTypes=Entire%20home%2Fapt&token=YOUR_TOKEN" ``` ### Response Each request returns a structured JSON record (or an array of records) in the response body. `/listing` returns a single `ListingRecord` with `description` and `amenities` populated; `/search` returns an array of card-level `ListingRecord` (no `description`/`amenities`); `/reviews` returns an array of `ReviewRecord`. ### Example `/listing` response ```json { "listingId": "12345678", "listingUrl": "https://www.airbnb.com/rooms/12345678", "name": "Sunny loft near the park", "title": "Entire loft in Brooklyn", "roomType": "Entire home/apt", "price": { "amount": 123, "originalAmount": 150, "label": "$123 / night", "qualifier": "/ night", "currency": "USD" }, "avgRating": 4.87, "reviewCount": 142, "coordinate": { "lat": 40.7128, "lng": -74.006 }, "images": ["https://a0.muscache.com/..."], "badges": ["Guest favourite"], "description": "Bright, quiet loft a short walk from...", "amenities": ["Wifi", "Kitchen", "Free parking"], "scrapedAt": "2026-06-26T14:00:00.000Z", "contentHash": "a1b2c3..." } ``` ### Errors Errors return a stable JSON shape and an HTTP status: ```json { "error": { "code": "BAD_INPUT", "message": "Provide a valid Airbnb listing id or room url." } } ``` - `400 BAD_INPUT` — missing or invalid parameters (no charge). - `404 NOT_FOUND` — listing could not be retrieved (no charge). - `503 TEMPORARILY_UNAVAILABLE` — the lookup could not be completed in time; retry (no charge). ### Use cases - Enrich an Airbnb listing live the moment a user pastes a room URL into your app. - Pull a stay's latest reviews on demand for a property-comparison or analytics view. - Look up listing cards for a location inside an automation or AI-agent workflow. - Validate or refresh a single listing's price and rating without running a full batch job. - Power a chatbot or MCP tool that answers Airbnb questions with live, structured data. ### How much does it cost to use Airbnb Realtime API? Airbnb Realtime API uses [pay-per-event](https://docs.apify.com/platform/actors/paid-actors/pay-per-event) pricing. There is **no per-run start fee** — the server handles many requests per run, and you pay only for records actually returned. | Event | Price | Charged when | |---|---|---| | Listing Detail (primary) | $0.005 | Per `/listing` response — a full detail-rich record. | | Listing Card | $0.0015 | Per card returned by `/search`. | | Review | $0.0008 | Per review returned by `/reviews`. | Example costs: - 100 listing details: **$0.50** - 1,000 listing details: **$5.00** - 1,000 search cards: **$1.50** - 1,000 reviews: **$0.80** Apify platform usage (compute) for your requests is billed separately by Apify, based on actual consumption, to the account that calls the API. ### FAQ #### How much data can I get per request? `/listing` returns one stay. `/reviews` returns up to 100 reviews per call (`limit` param), and `/search` returns up to 50 listing cards per call. Make multiple calls to page through more. #### Is this real-time? Yes. Each request is answered synchronously against Airbnb at request time — there is no batch run, no queue, and no dataset to poll. The first request after an idle period briefly boots the server; subsequent requests return immediately. #### Can I integrate Airbnb Realtime API with other apps? Yes. Because it's a plain HTTP API, you can call it from any language, backend, or no-code tool that can make an HTTP request — including Make, Zapier, n8n, and your own services. #### Can I use it with the Apify API? It **is** an HTTP API. Authenticate every request with your Apify API token (as `?token=` or an `Authorization: Bearer` header). You can also manage the actor itself through the [Apify API](https://docs.apify.com/api/v2). #### Can I use Airbnb Realtime API through an MCP Server? Yes. Apify provides an [MCP Server](https://apify.com/apify/actors-mcp-server?fpr=1h3gvi) that lets AI assistants and agents call Apify actors directly, so your agent can fetch live Airbnb records as a tool. #### Is it legal to scrape Airbnb? This actor returns publicly available data from Airbnb. Web scraping of public information is generally considered legal, but you should always review the target site's terms of service and ensure your use case complies with applicable laws and regulations, including GDPR where relevant. #### Your feedback If you have questions, need a feature, or found a bug, please [open an issue](https://apify.com/blackfalcondata/airbnb-realtime/issues?fpr=1h3gvi) on the actor's page in Apify Console. Your feedback helps us improve. ### You might also like - [Airbnb Scraper — Stays, Reviews & URLs](https://apify.com/blackfalcondata/airbnb-scraper?fpr=1h3gvi) — Bulk-export full Airbnb listings for a whole city in one run — price, ratings, room type, amenities, photos & GPS. - [Airbnb Reviews Scraper — Text, Rating, Date & Host Reply](https://apify.com/blackfalcondata/airbnb-reviews-scraper?fpr=1h3gvi) — Scrape Airbnb reviews as flat rows — review text, star rating, date, reviewer name & location. - [Airbnb URL Scraper — Fast, Cheap Listing URL Discovery](https://apify.com/blackfalcondata/airbnb-url-scraper?fpr=1h3gvi) — Discover every Airbnb listing URL for a city, neighborhood or search — the cheapest way to build a target list. - [Idealista Scraper — Spain, Portugal & Italy](https://apify.com/blackfalcondata/idealista-scraper?fpr=1h3gvi) — Scrape idealista.com / .pt / .it property listings with prices, photos, GPS, agent phone numbers. - [Realtor Scraper — US Real Estate Listings & Property Data](https://apify.com/blackfalcondata/realtor-scraper?fpr=1h3gvi) — Scrape US real estate from realtor.com — for-sale, for-rent & recently-sold listings with price & detail. ### Getting started with Apify New to Apify? [Create a free account with $5 credit](https://console.apify.com/sign-up?fpr=1h3gvi\&fp_sid=ctarich) — no credit card required. 1. Sign up — $5 platform credit included 2. Open this actor's **Endpoints** tab and try a lookup with your token auto-attached 3. Copy the request into your code and call the API live Need more later? [See Apify pricing](https://apify.com/pricing?fpr=1h3gvi). # Actor input Schema ## `proxyConfiguration` (type: `object`): Proxy settings for Airbnb requests. Uses Apify Proxy by default. ## Actor input object example ```json {} ``` # Actor output Schema ## `results` (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 '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = {}; // Run the Actor and wait for it to finish const run = await client.actor("blackfalcondata/airbnb-realtime").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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = {} # Run the Actor and wait for it to finish run = client.actor("blackfalcondata/airbnb-realtime").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{}' | apify call blackfalcondata/airbnb-realtime --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=blackfalcondata/airbnb-realtime", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Airbnb Realtime API — Live Listing, Reviews & Search Lookups", "description": "Real-time Airbnb lookups via a persistent standby server — fetch a single listing, its reviews, or a location search in one HTTP call. No batch run, no polling.", "version": "0.1", "x-build-id": "LKGBjNVpwJa5CL0Ty" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/blackfalcondata~airbnb-realtime/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-blackfalcondata-airbnb-realtime", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/blackfalcondata~airbnb-realtime/runs": { "post": { "operationId": "runs-sync-blackfalcondata-airbnb-realtime", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/blackfalcondata~airbnb-realtime/run-sync": { "post": { "operationId": "run-sync-blackfalcondata-airbnb-realtime", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "proxyConfiguration": { "title": "🌐 Proxy Configuration", "type": "object", "description": "Proxy settings for Airbnb requests. Uses Apify Proxy by default." } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```