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
FieldTypeMeaning
typestringRow type.
idstring / nullNumeric Airbnb listing id.
urlstring / nullListing URL.
namestring / nullListing name as Airbnb shows it.
titlestring / nullSearch title, e.g. 'Apartment in Lisbon', or the listing page title.
property_typestring / nullApartment, House, Condo … (search rows).
room_typestring / nullEntire home/apt, Private room, Shared room, Hotel room (listing page).
locationstring / nullArea from search or location text from the listing page.
latnumber / null
lngnumber / null
ratingnumber / null
reviews_countinteger / null
bedroomsinteger / null
bedsinteger / null
bathroomsnumber / null
person_capacityinteger / null
is_superhostboolean / null
is_guest_favoriteboolean / null
querystring / nullThe place search that produced the row; null for listing ids.
monthstring / nullCalendar month, YYYY-MM.
days_in_monthinteger / nullCalendar days in the month (28–31).
days_totalinteger / nullDays of the month counted: today onward. Past days are never counted, so the current month is partial.
days_availableinteger / nullDays of the month a guest could still book.
days_unavailableinteger / nullDays not available — booked by a guest or blocked by the host; the calendar does not distinguish.
occupancy_pctnumber / nulldays_unavailable / days_total × 100, one decimal. An occupancy proxy: blocked nights count as occupied.
checkin_daysinteger / nullAvailable days on which a stay may also start.
nights_mininteger / nullThe most common minimum stay across the month's days.
next_availablestring / nullFirst available day of the month, null when fully unavailable.
first_daystring / nullFirst day counted for the month.
last_daystring / nullLast day counted for the month.
currencystring / nullCurrency of the sampled rate.
rate_statusstring / nullok = 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_instring / nullCheck-in of the sampled stay (first bookable stay of the month).
rate_check_outstring / nullCheck-out of the sampled stay.
rate_nightsinteger / nullNights in the sampled stay — the listing's minimum stay, capped at 7.
rate_totalnumber / nullTotal price of the sampled stay for `adults` guests, as Airbnb displays it.
rate_nightlynumber / nullrate_total ÷ rate_nights — the month's nightly rate sample, an ADR proxy.
listing_idstring / nullStatus rows: the listing id the job was for.
statusstring / nullStatus rows.
resolved_placestring / nullStatus rows: the place Airbnb actually searched (from its canonical URL).
canonical_urlstring / null
pagesinteger / nullStatus rows: search pages read.
listingsinteger / nullStatus rows: listings whose calendar was read.
monthsinteger / nullStatus rows: occupancy rows delivered (and billed).
filteredinteger / nullStatus rows: months dropped by minOccupancyPct — never billed.
ratesinteger / nullStatus rows: months whose rate sample was priced.
duplicatesinteger / nullStatus rows: listings already handled by another job in this run.
calendar_errorsinteger / null
rate_errorsinteger / null
detail_errorsinteger / null
errorstring / nullStatus rows: the failure message, null when the job succeeded.
fetched_atstringUTC 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.

EventUSD eachWhat is charged
occupancy$0.003One 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

Public contract checked 2026-11-11. Active build: 1.0.8. Refresh live details before a large or recurring run.