# Airbnb Occupancy Scraper (`scrapebase/airbnb-occupancy-scraper`) Actor

- **URL**: https://apify.com/scrapebase/airbnb-occupancy-scraper.md
- **Developed by:** [ScrapeBase](https://apify.com/scrapebase) (community)
- **Categories:** Automation, Lead generation, Social media
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, NaN bookmarks
- **User rating**: No ratings yet

## Pricing

$19.99/month + usage

To use this Actor, you pay a monthly rental fee to the developer. The rent is subtracted from your prepaid usage every month after the free trial period.You also pay for the Apify platform usage, which gets cheaper the higher Apify subscription plan you have.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#rental-actors

## 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

## Airbnb Occupancy Calendar Scraper

Extract availability calendar data from Airbnb listings with intelligent proxy fallback and comprehensive error handling.

### Why Choose This Actor?

This actor provides reliable extraction of Airbnb occupancy data with:
- **Smart Proxy Fallback**: Automatically switches from no proxy → datacenter → residential proxy on failures
- **Bulk Processing**: Handle multiple room IDs in a single run
- **Structured Output**: Clean JSON format matching Airbnb's calendar data structure
- **Error Resilience**: Continues processing even if some rooms fail
- **Apify Integration**: Full Apify platform support with dataset storage

### Key Features

- 🚀 **Fast & Reliable**: Optimized requests with retry logic
- 🔄 **Proxy Intelligence**: Automatic fallback to residential proxies on blocks
- 📊 **Structured Data**: Clean calendar format with date/availability pairs
- 🔧 **Easy Configuration**: Simple input parameters
- 📈 **Bulk Support**: Process multiple rooms simultaneously
- 🛡️ **Error Handling**: Graceful failure recovery

### Input

#### JSON Schema
```json
{
  "roomIds": ["35329051", "769824007018240779"],
  "month": 12,
  "year": 2026,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
````

#### Field Descriptions

- **roomIds** (required): Array of Airbnb room IDs as strings
- **month** (optional): Month number (1-12), defaults to 12
- **year** (optional): Year number, defaults to 2026
- **proxyConfiguration** (optional): Apify proxy settings, defaults to no proxy

### Output

#### Apify Dataset Format

Each record represents one date for one room with availability status:

```json
{
  "room_id": "35329051",
  "date": "2026-12-01",
  "available": false
}
```

#### Exported JSON Example

When exported from Apify dataset, the data appears as a flat array:

```json
[
  {"room_id": "35329051", "date": "2026-12-01", "available": false},
  {"room_id": "35329051", "date": "2026-12-02", "available": true},
  {"room_id": "769824007018240779", "date": "2026-12-01", "available": false}
]
```

#### Note on Output Format

The Apify dataset stores individual records for optimal querying and filtering. This is different from the original script's grouped JSON format, but provides better flexibility for data analysis and integration with other tools.

### 🚀 How to Use the Actor (via Apify Console)

1. **Log in** at <https://console.apify.com> and go to **Actors**
2. **Find your actor** (search for "airbnb-occupancy-scraper")
3. **Configure inputs**:
   - Add Airbnb room IDs (comma-separated or array)
   - Set month/year for calendar data
   - Configure proxy settings if needed
4. **Run the actor** and monitor progress in real-time logs
5. **Access results** in the OUTPUT tab
6. **Export results** to JSON, CSV, or download directly

### Proxy Configuration

This actor implements intelligent proxy management:

- **Default**: Starts with direct connection (no proxy)
- **On Block**: Automatically falls back to datacenter proxy
- **On Failure**: Falls back to residential proxy with 3 retries
- **Persistence**: Sticks with residential proxy for remaining requests once successful

### Best Use Cases

- **Market Analysis**: Track occupancy rates across multiple listings
- **Price Optimization**: Identify high/low occupancy periods
- **Competitor Research**: Compare availability patterns
- **Investment Analysis**: Historical occupancy trends
- **Booking Platforms**: Sync availability data

### Technical Details

#### Request Flow

1. **API Key Extraction**: Fetches Airbnb API key from room page
2. **Operation ID Discovery**: Dynamically finds GraphQL operation ID
3. **Calendar Data Fetch**: Retrieves 12 months of availability data
4. **Data Extraction**: Parses calendar months and days
5. **Dataset Storage**: Saves structured data to Apify dataset

#### Error Handling

- **Network Errors**: Automatic retry with exponential backoff
- **Proxy Blocks**: Intelligent fallback to higher-tier proxies
- **Data Errors**: Continues processing other rooms on individual failures
- **Rate Limits**: Built-in delays and proxy rotation

#### Performance

- **Concurrent Processing**: Handles multiple rooms efficiently
- **Memory Efficient**: Processes data in-memory without file storage
- **Smart Caching**: Reuses API keys across rooms

### Frequently Asked Questions

**Q: How do I find Airbnb room IDs?**
A: Room IDs are in the URL: `https://www.airbnb.com/rooms/{ROOM_ID}`

**Q: What date range does it cover?**
A: Returns 12 months of data starting from the specified month/year.

**Q: Can I scrape historical data?**
A: Yes, set past months/years to get historical availability.

**Q: What if some rooms fail?**
A: The actor continues processing other rooms and logs errors.

**Q: How does proxy fallback work?**
A: Starts direct → datacenter proxy → residential proxy with retries.

### Support and Feedback

For issues or feature requests:

- Check the logs for detailed error information
- Ensure room IDs are valid and accessible
- Verify proxy configuration if using proxies

### ⚠️ Important Notes

- **Legal Compliance**: Ensure your usage complies with Airbnb's Terms of Service
- **Rate Limiting**: Built-in delays prevent overwhelming Airbnb servers
- **Data Privacy**: Only extracts publicly available calendar information
- **Fair Use**: Respect Airbnb's robots.txt and rate limits

***

*Built with ❤️ using Apify platform*

# Actor input Schema

## `roomIds` (type: `array`):

List one or more Airbnb room IDs to scrape occupancy data for (e.g., 35329051, 769824007018240779).

## `month` (type: `integer`):

Month to fetch occupancy data for (1-12).

## `year` (type: `integer`):

Year to fetch occupancy data for.

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

Choose which proxies to use. If Airbnb rejects the proxy, fallback to residential proxy will be used automatically.

## Actor input object example

```json
{
  "roomIds": [
    "35329051",
    "769824007018240779"
  ],
  "month": 12,
  "year": 2026,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# 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 = {
    "roomIds": [
        "35329051",
        "769824007018240779"
    ],
    "proxyConfiguration": {
        "useApifyProxy": false
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("scrapebase/airbnb-occupancy-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 '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "roomIds": [
        "35329051",
        "769824007018240779",
    ],
    "proxyConfiguration": { "useApifyProxy": False },
}

# Run the Actor and wait for it to finish
run = client.actor("scrapebase/airbnb-occupancy-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 '{
  "roomIds": [
    "35329051",
    "769824007018240779"
  ],
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}' |
apify call scrapebase/airbnb-occupancy-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=scrapebase/airbnb-occupancy-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Airbnb Occupancy Scraper",
        "version": "0.1",
        "x-build-id": "491emyPEVSLMspm16"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/scrapebase~airbnb-occupancy-scraper/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-scrapebase-airbnb-occupancy-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/scrapebase~airbnb-occupancy-scraper/runs": {
            "post": {
                "operationId": "runs-sync-scrapebase-airbnb-occupancy-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/scrapebase~airbnb-occupancy-scraper/run-sync": {
            "post": {
                "operationId": "run-sync-scrapebase-airbnb-occupancy-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",
                "required": [
                    "roomIds"
                ],
                "properties": {
                    "roomIds": {
                        "title": "Airbnb Room IDs",
                        "type": "array",
                        "description": "List one or more Airbnb room IDs to scrape occupancy data for (e.g., 35329051, 769824007018240779).",
                        "items": {
                            "type": "string"
                        }
                    },
                    "month": {
                        "title": "Month",
                        "minimum": 1,
                        "maximum": 12,
                        "type": "integer",
                        "description": "Month to fetch occupancy data for (1-12).",
                        "default": 12
                    },
                    "year": {
                        "title": "Year",
                        "type": "integer",
                        "description": "Year to fetch occupancy data for.",
                        "default": 2026
                    },
                    "proxyConfiguration": {
                        "title": "Proxy Configuration",
                        "type": "object",
                        "description": "Choose which proxies to use. If Airbnb rejects the proxy, fallback to residential proxy will be used automatically."
                    }
                }
            },
            "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
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```