# Airbnb Availability Calendar (`lergassy/airbnb-availability-calendar`) Actor

Read the booking calendar of any Airbnb listing: which nights are free, which are booked, the host's minimum stay for each date, the first bookable date and occupancy per month. Up to 12 months ahead, by listing URL or by destination. No browser, no login, no API key.

- **URL**: https://apify.com/lergassy/airbnb-availability-calendar.md
- **Developed by:** [Matvey](https://apify.com/lergassy) (community)
- **Categories:** Travel, Real estate, Automation
- **Stats:** 4 total users, 3 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: 5.00 out of 5 stars

## Pricing

from $1.75 / 1,000 listing calendars

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

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

**Airbnb Availability Calendar** reads the booking calendar of any Airbnb listing: which nights are free, which are taken, the host's minimum stay for each date, the first bookable date, and occupancy per month — up to twelve months ahead. Paste listing URLs, or give a destination and let the Actor read the calendars of everything Airbnb shows there. It calls the same request the listing page itself makes, so one property is one small JSON request: no browser, no login, and twelve months cost exactly what one month costs.

### Tested head-to-head — 24 September 2026

![One row per listing with occupancy for every month, and a 12-month calendar for $0.0025 instead of $0.01–$1.11](https://raw.githubusercontent.com/lergassy/apify-actor-assets/main/benchmarks/airbnb-calendar-tested-2026-09-24.png)

We ran this Actor and four of the most-used Airbnb availability-calendar Actors on the Apify Store on the same request: the calendar of one Paris listing (a studio in Gennevilliers) for November 2026, on a Free-plan account. All five read the same answer — 2 of 30 November nights free, the 5th and the 15th. The differences are in what you pay and what you get on top.

| | This Actor | The 4 others |
|---|---|---|
| Price of a 12-month calendar for one listing, incl. start fees | **$0.0025** | $0.01 – $1.11 |
| Occupancy for each calendar month | **Yes** | No (per-day rows, one total, or 30/90/365-day windows) |

### What you get

| Field | Example |
|---|---|
| `minNights` / `maxNights` | `3` / `28` |
| `occupancyPercent` | `61.4` — share of scanned nights already taken |
| `availableDays` / `bookedDays` | `71` / `113` |
| `firstAvailableDate` | `2026-11-04` |
| `availabilityByMonth` | per month: nights, free, booked, occupancy % |
| `calendar` | every date with `available`, `bookable`, `checkIn`, `checkOut`, `minNights` |
| `listingId` / `url` / `name` | identifier, link, title (the title comes with destination searches; pasted URLs leave it empty) |

### How much it costs

**$0.0025 per listing calendar**, whatever the number of months. Reading a year for one property costs a quarter of a cent; a hundred properties cost $0.25. Error rows are never charged. The Actor runs without a browser, so platform usage stays near zero.

### Input

Give it listing URLs:

```json
{
  "startUrls": [
    "https://www.airbnb.com/rooms/12345678",
    "https://www.airbnb.com/rooms/87654321"
  ],
  "calendarMonths": 12
}
```

…or a destination, to measure a market rather than named properties:

```json
{
  "locationQueries": ["Seminyak, Bali, Indonesia"],
  "maxListings": 50,
  "calendarMonths": 6
}
```

A pasted Airbnb search URL works the same way as a destination.

### Output

One row per listing:

```json
{
  "type": "listing-calendar",
  "listingId": "12345678",
  "name": "One Bedroom with Private Pool",
  "url": "https://www.airbnb.com/rooms/12345678",
  "minNights": 3,
  "maxNights": 28,
  "monthsScanned": 6,
  "daysScanned": 184,
  "availableDays": 71,
  "bookedDays": 113,
  "occupancyPercent": 61.4,
  "firstAvailableDate": "2026-11-04",
  "availabilityByMonth": [
    { "month": "2026-11", "days": 30, "available": 9, "booked": 21, "occupancyPercent": 70 }
  ],
  "calendar": [
    { "date": "2026-11-04", "available": true, "bookable": true, "checkIn": true, "checkOut": false, "minNights": 3, "maxNights": 28 }
  ]
}
```

Switch off **Include the day-by-day array** for one compact row per listing with monthly occupancy only. Pages that fail after the retries arrive as `type: "error"` rows carrying the URL and the reason, and are not billed.

### What people use it for

- **Occupancy tracking** — how full a building, a street or a whole destination is, month by month.
- **Revenue estimates** — booked nights over a window are the input every rental-income model needs.
- **Competitive pricing** — see which minimum-stay rules the hosts around you actually enforce.
- **Availability alerts** — re-run daily and watch `firstAvailableDate` move.
- **Feeding a channel manager or a spreadsheet** — the day-by-day array maps straight onto a booking grid.

### Integrations

Results land in a standard Apify dataset: export to JSON, CSV, Excel or XML, or pull them over the API. Connect the run to Make, Zapier, n8n, Google Sheets, Slack or a webhook, or schedule it and compare snapshots day over day.

### Use via API

Run this Actor from your own code or pipeline. Get your token in Apify Console → Settings → API & Integrations. Every input field below has the same name as in the JSON tab of the input form.

**Python**

```python
from apify_client import ApifyClient

client = ApifyClient("<YOUR_API_TOKEN>")
run = client.actor("lergassy/airbnb-availability-calendar").call(run_input={
    "locationQueries": [
        "Seminyak, Bali, Indonesia"
    ],
    "maxListings": 5,
    "calendarMonths": 6
})
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)
```

**JavaScript**

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

const client = new ApifyClient({ token: '<YOUR_API_TOKEN>' });
const run = await client.actor('lergassy/airbnb-availability-calendar').call({
    "locationQueries": [
        "Seminyak, Bali, Indonesia"
    ],
    "maxListings": 5,
    "calendarMonths": 6
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);
```

**cURL** (runs the Actor and returns the results in one call)

```bash
curl -X POST "https://api.apify.com/v2/acts/lergassy~airbnb-availability-calendar/run-sync-get-dataset-items?token=<YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"locationQueries": ["Seminyak, Bali, Indonesia"], "maxListings": 5, "calendarMonths": 6}'
```

### FAQ

**Is scraping Airbnb legal?** This Actor reads only what Airbnb serves to any visitor without logging in — public listing information. It collects no personal data about guests or hosts beyond the listing title Airbnb itself publishes. Check your own jurisdiction and Airbnb's terms before large-scale use.

**Why does a listing come back with an empty calendar?** Airbnb removes the calendar for listings that are unlisted, paused or deleted. Those arrive as an `error` row rather than as a silently empty result.

**Do I need a proxy?** Apify Proxy is on by default because Airbnb rate-limits repeat callers by IP. If it starts refusing pages, the run moves itself to residential addresses and carries on.

### You might also like

- **Airbnb Scraper — Vacation Rental Prices & Availability** — prices, ratings, amenities and hosts for a whole destination.
- **Booking Hotels Scraper** — the same market from Booking.com.
- **Agoda Reviews Scraper** — guest reviews for hotels across Agoda and Booking.

# Actor input Schema

## `startUrls` (type: `array`):

Listing pages to read, like <code>https://www.airbnb.com/rooms/12345678</code>. A search URL works too — every listing on it is read. Leave empty to use the destination below.

## `locationQueries` (type: `array`):

Read the calendars of the first listings Airbnb shows for a place, for example <code>Seminyak, Bali, Indonesia</code>. Use this to measure a whole market instead of named properties.

## `calendarMonths` (type: `integer`):

How far into the future to read, 1 to 12. Airbnb answers the whole range in one request, so twelve months costs the same as one.

## `maxListings` (type: `integer`):

Upper limit when a destination is given. Ignored when you paste listing URLs — those are all read.

## `includeDays` (type: `boolean`):

Every date with available / bookable / check-in / check-out flags and the minimum stay for that night. Switch off for one compact row per listing with monthly occupancy only.

## `onlyAvailableListings` (type: `boolean`):

Return only properties that still have at least one free night in the scanned window.

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

Used only to search a destination — the calendar itself does not depend on it.

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

Currency Airbnb answers in while searching a destination.

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

Apify Proxy is on by default — Airbnb rate-limits repeat callers by IP address. If Airbnb starts refusing pages, the run switches itself to residential addresses.

## Actor input object example

```json
{
  "startUrls": [],
  "locationQueries": [
    "Seminyak, Bali, Indonesia"
  ],
  "calendarMonths": 6,
  "maxListings": 5,
  "includeDays": true,
  "onlyAvailableListings": false,
  "adults": 2,
  "currency": "USD",
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

## `calendars` (type: `string`):

One row per listing: the day-by-day calendar with available, bookable, check-in and check-out flags and the minimum stay for each night, plus minimum nights, first bookable date, free and booked day counts and occupancy per month.

# 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 = {
    "startUrls": [],
    "locationQueries": [
        "Seminyak, Bali, Indonesia"
    ],
    "calendarMonths": 6,
    "maxListings": 5
};

// Run the Actor and wait for it to finish
const run = await client.actor("lergassy/airbnb-availability-calendar").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 = {
    "startUrls": [],
    "locationQueries": ["Seminyak, Bali, Indonesia"],
    "calendarMonths": 6,
    "maxListings": 5,
}

# Run the Actor and wait for it to finish
run = client.actor("lergassy/airbnb-availability-calendar").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 '{
  "startUrls": [],
  "locationQueries": [
    "Seminyak, Bali, Indonesia"
  ],
  "calendarMonths": 6,
  "maxListings": 5
}' |
apify call lergassy/airbnb-availability-calendar --silent --output-dataset

```

## MCP server setup

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

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/rLCKNUQFxwqyyS38m/builds/fpQyovj1Pgnw43P9X/openapi.json