# Airbnb Calendar Availability Scraper (`khadinakbar/airbnb-calendar-availability-scraper`) Actor Read an authorized Airbnb iCalendar export to return date-level blocked and inferred-open availability. Use for host operations and STR workflows, not public listing scraping. Returns one row per date with availability and block count. $0.002/day plus a $0.00005 start fee; platform usage extra. - **URL**: https://apify.com/khadinakbar/airbnb-calendar-availability-scraper.md - **Developed by:** [Khadin Akbar](https://apify.com/khadinakbar) (community) - **Categories:** Travel, Real estate, Automation - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $2.00 / 1,000 calendar day returneds 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 web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows. 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/docs.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.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/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 ## Airbnb Calendar Availability Scraper Parse an Airbnb calendar that you are authorized to access and return one clean availability row per date. Built for hosts, co-hosts, property managers, and STR operations teams that need a machine-readable view of blocked dates without collecting guest details. ### What it does The Actor reads an Airbnb iCalendar (`.ics`) export URL supplied by the listing owner or an authorized co-host, or it accepts the iCalendar text directly. Airbnb supports calendar export for host calendar syncing. This Actor translates the event ranges in that feed into date-level records for dashboards, cleaner scheduling, channel-management checks, and occupancy analysis. It does not access Airbnb accounts, does not accept account credentials, and does not scrape public listing pages. An iCalendar export URL contains a token, so the Actor treats it as secret input and never writes that URL to the dataset, key-value store, or logs. ### When to use it Use it when you own, manage, or have been expressly granted access to an Airbnb listing calendar and want a safe automation step after the calendar export. Typical workflows include: - Feeding blocked and inferred-open dates to a cleaner or turnover workflow. - Checking calendar coverage across several authorized listings. - Producing an occupancy input for a spreadsheet or BI dashboard. - Comparing the date blocks in a host-provided Airbnb feed with another authorized channel feed. Do not use it to discover, probe, or monitor public Airbnb listings you do not manage. It does not confirm that an apparently open date can be booked: Airbnb may apply minimum stays, advance notice, check-in restrictions, price rules, or other conditions that an iCalendar feed does not represent. ### Input | Field | Purpose | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `calendarUrls` | Up to 20 authorized Airbnb calendar-export URLs in the form `https://www.airbnb.com/calendar/ical/.ics?s=`. This secret field is the preferred input. | | `icalText` | An authorized, complete `BEGIN:VCALENDAR` document. Use this only when sending a calendar URL is unsuitable. | | `startDate` / `endDate` | Optional inclusive ISO date window. Leaving both blank starts today and spans `maxDaysPerCalendar`. | | `maxDaysPerCalendar` | Inclusive date cap per source, 1–731; default 366. | At least one of `calendarUrls` or `icalText` is required by the runtime. The Actor rejects public room URLs, non-Airbnb hosts, non-HTTPS URLs, and calendar URLs without an export token. It also validates every redirect so a supplied calendar URL cannot turn this Actor into a general-purpose network fetcher. #### Find an authorized Airbnb calendar export In Airbnb hosting tools, open **Calendar**, select the listing, choose **Availability**, then use **Connect to another website** to copy the exported calendar URL. Share that URL only with systems and people permitted to see the listing's booking pattern; anyone with the token can read the calendar feed. You can regenerate the export URL in Airbnb if it is exposed. #### Example input ```json { "calendarUrls": ["https://www.airbnb.com/calendar/ical/12345678.ics?s=REDACTED"], "startDate": "2026-08-01", "endDate": "2026-08-31", "maxDaysPerCalendar": 366 } ```` ### Output The default dataset contains one record per requested calendar date per source. It deliberately omits event summaries, descriptions, guest names, guest counts, and all calendar URLs. | Field | Meaning | | -------------------- | ------------------------------------------------------------------------------------------------------ | | `sourceId` | Listing ID parsed from an export URL, or a generated ID for pasted calendar text. | | `date` | ISO calendar day. | | `available` | `true` when no supplied iCalendar event covers the day. This is an inference, not a booking guarantee. | | `blocked` | `true` when at least one supplied event covers the day. | | `bookingStatus` | `blocked` or `open_inferred`. | | `blockedByEvents` | Number of source events covering the day, without revealing the events themselves. | | `availabilitySource` | Always `authorized_ical`. | | `availabilityNote` | Explains the availability inference boundary. | | `scrapedAt` | ISO timestamp for the parsed row. | ```json { "sourceId": "12345678", "sourceLabel": "Authorized Airbnb calendar 1", "date": "2026-08-06", "available": false, "blocked": true, "bookingStatus": "blocked", "blockedByEvents": 1, "availabilitySource": "authorized_ical", "availabilityNote": "A supplied iCalendar event covers this date.", "scrapedAt": "2026-07-15T12:00:00.000Z" } ``` The Actor writes an `OUTPUT` record and a detailed `RUN_SUMMARY` record to the default key-value store on every terminal path. Successful parse runs use `COMPLETE` or `PARTIAL`; input problems use `INVALID_INPUT`; a valid authorized input that yields no usable source fails honestly as `UPSTREAM_FAILED`. ### Pricing This Actor uses **Pay per event + usage**: | Event | Price | | --------------------- | -------------------------------: | | Actor start | $0.00005 per run | | Calendar day returned | $0.002 per validated dataset row | For example, one 90-day calendar window costs at most $0.18005 in event charges; Apify platform usage is billed separately. Apify charges the Actor start event automatically. Before fetching a source, the Actor logs and sets a status message with the maximum event-charge estimate for the requested range. A row is charged only when its full validated record is persisted. ### API and automation examples #### Apify API ```bash curl -X POST "https://api.apify.com/v2/acts/khadinakbar~airbnb-calendar-availability-scraper/runs?token=$APIFY_TOKEN" \ -H 'content-type: application/json' \ -d '{ "calendarUrls": ["https://www.airbnb.com/calendar/ical/12345678.ics?s=REDACTED"], "startDate": "2026-08-01", "endDate": "2026-08-31" }' ``` #### JavaScript ```js import { ApifyClient } from 'apify-client'; const client = new ApifyClient({ token: process.env.APIFY_TOKEN }); const run = await client.actor('khadinakbar/airbnb-calendar-availability-scraper').call({ calendarUrls: [process.env.AIRBNB_ICAL_URL], maxDaysPerCalendar: 90, }); const { items } = await client.dataset(run.defaultDatasetId).listItems(); ``` #### Python ```python import os from apify_client import ApifyClient client = ApifyClient(os.environ["APIFY_TOKEN"]) run = client.actor("khadinakbar/airbnb-calendar-availability-scraper").call( run_input={"calendarUrls": [os.environ["AIRBNB_ICAL_URL"]], "maxDaysPerCalendar": 90} ) for row in client.dataset(run["defaultDatasetId"]).iterate_items(): print(row["date"], row["bookingStatus"]) ``` ### Reliability and limits - Event start/end dates are parsed from RFC 5545 iCalendar events. All-day `DTEND` is treated as exclusive, as defined by the format. - Cancelled events are ignored. Recurring events are reported as a warning and treated as one occurrence; Airbnb export feeds normally use individual reservation/block events. - The Actor allows at most 20 sources, 731 dates per source, 2 MB per feed, three validated redirects, and 20 seconds per source request. - If some sources work and others fail, persisted rows are retained and the run ends as `PARTIAL`. If no source yields usable data, it ends as `UPSTREAM_FAILED` with diagnostics. - The source feed may lag Airbnb's current state. Treat it as operational calendar data, not a real-time booking engine. ### Legal and privacy scope Use this Actor only with calendars you own or are authorized to process. It processes only the date ranges necessary to derive availability and intentionally does not persist personal information from calendar events. Airbnb's terms restrict automated access to its public platform; this Actor avoids public-listing scraping and relies on Airbnb's host calendar-export mechanism. ### FAQ **Why does an open date say `open_inferred` rather than bookable?** The absence of an event means the supplied feed does not mark the date blocked. It cannot prove that Airbnb would permit a specific stay after minimum-night, availability-window, pricing, and other booking rules. **Can I paste a public `airbnb.com/rooms/...` URL?** No. The Actor accepts only an authorized `calendar/ical/.ics?s=` export URL or the calendar text itself. **Does it expose guest names or reservation notes?** No. The parser discards event summaries, descriptions, and attendee data before constructing output rows. **Can it combine multiple listings?** Yes. Supply up to 20 authorized export URLs. The output remains one row per source and date so downstream systems can group by `sourceId`. # Actor input Schema ## `calendarUrls` (type: `array`): Use this when you have permission to read one or more Airbnb calendar exports. Enter HTTPS Airbnb iCalendar links such as https://www.airbnb.com/calendar/ical/12345678.ics?s=REDACTED. Up to 20 feeds are accepted and their tokenized URLs are treated as secret. This is not a public listing URL or an Airbnb account-login field. ## `icalText` (type: `string`): Use this when you can paste an authorized Airbnb iCalendar document instead of exposing its export URL. Paste the complete text beginning with BEGIN:VCALENDAR, for example a feed copied from your host tooling. It is optional when calendarUrls is supplied and is treated as secret. This is not a booking confirmation, guest message, or public listing HTML. ## `startDate` (type: `string`): Use this when you need a calendar window that starts on a particular day. Enter an ISO date such as 2026-08-01; an empty value starts on the day the Actor runs. The selected range is inclusive and cannot exceed maxDaysPerCalendar. This is not a check-in request sent to Airbnb. ## `endDate` (type: `string`): Use this when you need a calendar window that ends on a particular day. Enter an ISO date such as 2026-10-31; an empty value uses startDate plus maxDaysPerCalendar minus one. The selected range is inclusive and must end on or after startDate. This is not the departure date of an Airbnb booking flow. ## `maxDaysPerCalendar` (type: `integer`): Use this when you want to bound returned date-level availability and the associated per-day charge. Enter an integer from 1 to 731, for example 366; the default is 366. If explicit dates span more days than this limit, the Actor returns an actionable invalid-input result. This is not a network-request or listing-count limit. ## Actor input object example ```json { "startDate": "2026-08-01", "endDate": "2026-10-31", "maxDaysPerCalendar": 366 } ``` # Actor output Schema ## `calendarDays` (type: `string`): No description ## `runSummary` (type: `string`): No description ## `output` (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("khadinakbar/airbnb-calendar-availability-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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = {} # Run the Actor and wait for it to finish run = client.actor("khadinakbar/airbnb-calendar-availability-scraper").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 khadinakbar/airbnb-calendar-availability-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=khadinakbar/airbnb-calendar-availability-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Airbnb Calendar Availability Scraper", "description": "Read an authorized Airbnb iCalendar export to return date-level blocked and inferred-open availability. Use for host operations and STR workflows, not public listing scraping. Returns one row per date with availability and block count. $0.002/day plus a $0.00005 start fee; platform usage extra.", "version": "0.2", "x-build-id": "DDMbH22yNO84lzvNc" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/khadinakbar~airbnb-calendar-availability-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-khadinakbar-airbnb-calendar-availability-scraper", "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/khadinakbar~airbnb-calendar-availability-scraper/runs": { "post": { "operationId": "runs-sync-khadinakbar-airbnb-calendar-availability-scraper", "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/khadinakbar~airbnb-calendar-availability-scraper/run-sync": { "post": { "operationId": "run-sync-khadinakbar-airbnb-calendar-availability-scraper", "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": { "calendarUrls": { "title": "Authorized Airbnb iCalendar URLs", "maxItems": 20, "type": "array", "description": "Use this when you have permission to read one or more Airbnb calendar exports. Enter HTTPS Airbnb iCalendar links such as https://www.airbnb.com/calendar/ical/12345678.ics?s=REDACTED. Up to 20 feeds are accepted and their tokenized URLs are treated as secret. This is not a public listing URL or an Airbnb account-login field.", "items": { "type": "string" } }, "icalText": { "title": "Authorized iCalendar text", "type": "string", "description": "Use this when you can paste an authorized Airbnb iCalendar document instead of exposing its export URL. Paste the complete text beginning with BEGIN:VCALENDAR, for example a feed copied from your host tooling. It is optional when calendarUrls is supplied and is treated as secret. This is not a booking confirmation, guest message, or public listing HTML." }, "startDate": { "title": "First date", "type": "string", "description": "Use this when you need a calendar window that starts on a particular day. Enter an ISO date such as 2026-08-01; an empty value starts on the day the Actor runs. The selected range is inclusive and cannot exceed maxDaysPerCalendar. This is not a check-in request sent to Airbnb.", "default": "" }, "endDate": { "title": "Last date", "type": "string", "description": "Use this when you need a calendar window that ends on a particular day. Enter an ISO date such as 2026-10-31; an empty value uses startDate plus maxDaysPerCalendar minus one. The selected range is inclusive and must end on or after startDate. This is not the departure date of an Airbnb booking flow.", "default": "" }, "maxDaysPerCalendar": { "title": "Maximum days per calendar", "minimum": 1, "maximum": 731, "type": "integer", "description": "Use this when you want to bound returned date-level availability and the associated per-day charge. Enter an integer from 1 to 731, for example 366; the default is 366. If explicit dates span more days than this limit, the Actor returns an actionable invalid-input result. This is not a network-request or listing-count limit.", "default": 366 } } }, "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 } } } } } } } } } } ```