MCP + API · kestrel/airbnb-occupancy-scraper
Airbnb Occupancy Rate Scraper — Availability & Nightly Rates
Estimate Airbnb occupancy from listing availability calendars by place or listing ID. One row per listing and month: available and blocked-or-booked days, occupancy %, minimum stay and sampled nightly rate. For rental market research and comps; blocked nights cannot be separated from bookings.
Open Actor Download MCP config
Connect this tool
Add this URL as a remote MCP server in your client, then sign in to Apify. For a client-specific setup, use Apify's configurator.
https://mcp.apify.com?tools=call-actor,fetch-actor-details,kestrel/airbnb-occupancy-scraper
Generic MCP client configuration
{
"mcpServers": {
"kestrel-airbnb-occupancy-scraper": {
"url": "https://mcp.apify.com?tools=call-actor,fetch-actor-details,kestrel/airbnb-occupancy-scraper"
}
}
}
Understand the output before you run
Row types in one dataset: occupancy (one per listing and calendar month — days available vs blocked or booked, occupancy %, minimum stay, a sampled nightly rate), listing (optional, free), status (per place, URL or listing id; never charged).
Declared dataset fields and row types · Output locations and dataset links
Use the declared dataset schema for item fields; the output schema describes where results are stored. Optional fields may be null or absent. If an integration shows a sampled schema without an optional field, check this declaration, the Actor instructions and actual returned rows before concluding that the field is unsupported.
Inspect 52 declared output fields
| Field | Type | Meaning |
|---|---|---|
type | string | Row type. |
id | string / null | Numeric Airbnb listing id. |
url | string / null | Listing URL. |
name | string / null | Listing name as Airbnb shows it. |
title | string / null | Search title, e.g. 'Apartment in Lisbon', or the listing page title. |
property_type | string / null | Apartment, House, Condo … (search rows). |
room_type | string / null | Entire home/apt, Private room, Shared room, Hotel room (listing page). |
location | string / null | Area from search or location text from the listing page. |
lat | number / null | |
lng | number / null | |
rating | number / null | |
reviews_count | integer / null | |
bedrooms | integer / null | |
beds | integer / null | |
bathrooms | number / null | |
person_capacity | integer / null | |
is_superhost | boolean / null | |
is_guest_favorite | boolean / null | |
query | string / null | The place search that produced the row; null for listing ids. |
month | string / null | Calendar month, YYYY-MM. |
days_in_month | integer / null | Calendar days in the month (28–31). |
days_total | integer / null | Days of the month counted: today onward. Past days are never counted, so the current month is partial. |
days_available | integer / null | Days of the month a guest could still book. |
days_unavailable | integer / null | Days not available — booked by a guest or blocked by the host; the calendar does not distinguish. |
occupancy_pct | number / null | days_unavailable / days_total × 100, one decimal. An occupancy proxy: blocked nights count as occupied. |
checkin_days | integer / null | Available days on which a stay may also start. |
nights_min | integer / null | The most common minimum stay across the month's days. |
next_available | string / null | First available day of the month, null when fully unavailable. |
first_day | string / null | First day counted for the month. |
last_day | string / null | Last day counted for the month. |
currency | string / null | Currency of the sampled rate. |
rate_status | string / null | ok = priced; no_stay = no bookable stay in the month; unavailable = the page refused the stay (usually `adults` exceeds the listing's capacity); unpriced = no price came back; error = the request failed; skipped = includeRates off. |
rate_check_in | string / null | Check-in of the sampled stay (first bookable stay of the month). |
rate_check_out | string / null | Check-out of the sampled stay. |
rate_nights | integer / null | Nights in the sampled stay — the listing's minimum stay, capped at 7. |
rate_total | number / null | Total price of the sampled stay for `adults` guests, as Airbnb displays it. |
rate_nightly | number / null | rate_total ÷ rate_nights — the month's nightly rate sample, an ADR proxy. |
listing_id | string / null | Status rows: the listing id the job was for. |
status | string / null | Status rows. |
resolved_place | string / null | Status rows: the place Airbnb actually searched (from its canonical URL). |
canonical_url | string / null | |
pages | integer / null | Status rows: search pages read. |
listings | integer / null | Status rows: listings whose calendar was read. |
months | integer / null | Status rows: occupancy rows delivered (and billed). |
filtered | integer / null | Status rows: months dropped by minOccupancyPct — never billed. |
rates | integer / null | Status rows: months whose rate sample was priced. |
duplicates | integer / null | Status rows: listings already handled by another job in this run. |
calendar_errors | integer / null | |
rate_errors | integer / null | |
detail_errors | integer / null | |
error | string / null | Status rows: the failure message, null when the job succeeded. |
fetched_at | string | UTC timestamp when the row was fetched. |
Start with a small sample
Use call-actor with the JSON below. The $0.25 run ceiling is separate from the Actor input and may stop the sample early. Change the target to match your request. This input validates against build 1.0.8; it is not a promise that the source has matching rows today.
{
"actor": "kestrel/airbnb-occupancy-scraper",
"input": {
"locationQueries": [
"Lisbon, Portugal"
],
"maxListingsPerQuery": 3,
"months": 1
},
"callOptions": {
"maxTotalChargeUsd": 0.25,
"timeout": 300
},
"waitSecs": 30
}
After completion, use get-dataset-items with storages.datasets.default.id. If still running, poll get-actor-run using the returned runId. Check status rows and errors before treating an empty dataset as no matches.
Call from Python, JavaScript or REST
Python SDK 3 example · JavaScript SDK 2 example · curl + jq example. Each uses this same small input, reads APIFY_TOKEN from your environment, sets a five-minute run timeout and exports all dataset row types as JSON Lines. The $0.25 run ceiling is separate from the Actor input and may stop the sample early. Inspect the run and source status before treating results as complete. Installation and usage.
Pricing and limits
Current listed event prices in USD. Some Actors charge for successful source checks even when no output rows match. The event descriptions below define those differences.
| Event | USD each | What is charged |
|---|---|---|
occupancy | $0.003 | One calendar month of one listing: days available, days blocked or booked, occupancy %, minimum stay, next free night and a sampled nightly rate (row keys id, url, name, month, days_available, days_unavailable, occupancy_pct, checkin_days, nights_min, next_available, rate_nightly, rate_total, rate_check_in, rate_status, currency, rating, reviews_count): $3 per 1,000 rows (12 months of one listing $0.036; 100 listings for 6 months $1.80). Not charged: months under minOccupancyPct (filtered before billing), listing rows, status rows, unknown places, failed calendars. No start fee; proxy and compute are included in the event price. The run stops at the maximum cost per run you set when starting it (Apify run option maxTotalChargeUsd). |
Contracts for agents
- Input schema and sample input
- Prepared MCP call and pricing events
- Full Actor instructions and limits
- REST API
Public contract checked 2026-11-11. Active build: 1.0.8. Refresh live details before a large or recurring run.