Airbnb Plugin for OpenCode

A comprehensive OpenCode plugin for searching and retrieving Airbnb listings. This plugin provides tools to search for accommodations, get detailed listing information, and filter results based on various criteria like dates, guests, and price ranges.

Table of Contents

1. Features
2. Quick Start
3. Configuration
4. Available Tools
5. Usage Examples
6. Error Handling
7. Testing

Features

• Search Airbnb Listings: Search for accommodations by location with various filters
• Detailed Listing Information: Get comprehensive details about specific properties
• Flexible Filtering: Filter by dates, number of guests, price range, and more
• Pagination Support: Navigate through search results using cursor-based pagination
• Robots.txt Compliance: Respects Airbnb's robots.txt rules with configurable override
• Error Handling: Comprehensive error handling with detailed error messages

Quick Start

1. Install Dependencies

# From the root directory
pnpm install

# Or from the plugin directory
cd pets/airbnb
pnpm install

2. Configure Environment

# Copy environment template
cp .env.example .env

# Edit configuration (optional)
nano .env

3. Test the Plugin

# Quick test search
opencode run "search airbnbs in 'New York'"

# Test with specific dates
opencode run "search airbnbs in 'Paris' with checkin '2024-12-20' and checkout '2024-12-25'"

Provider Selection Logic

1. Configuration Loading: Parse PROVIDER_PREFERENCES JSON
2. Provider Initialization: Load available providers based on API keys
3. Fallback Handling: Graceful degradation when providers fail
4. Dynamic Loading: Import providers only when needed

Quick Start

1. Copy This Template

# Navigate to pets directory
cd /Users/andrewmaguire/LOCAL/Github/raggle-code/raggle-repo/core/pets/

# Copy template
cp -r _TEMPLATE_ my-workflow-manager
cd my-workflow-manager

2. Install Dependencies

npm install

3. Configure Environment

# Copy environment template
cp .env.example .env

# Edit with your API keys
nano .env

Example .env:

# Primary providers
GITHUB_TOKEN=ghp_your_github_token
GOOGLE_MAPS_API_KEY=your_google_maps_key
FAL_KEY=your_fal_api_key

# Provider preferences
PROVIDER_PREFERENCES={"maps":"googlemaps","ai":"fal"}

# Workflow settings
DEFAULT_TIMEOUT=30000
MAX_RETRIES=3
LOG_LEVEL=info

4. Test the Template

# Check provider status
opencode run "check provider status"

# Demo workflow
opencode run "demo workflow with geocode and enhance for 'New York'"

Configuration

Environment Variables

| Variable | Description | Default | Required | |----------|-------------|---------|-----------| | IGNORE_ROBOTS_TXT | Ignore robots.txt rules for requests | false | No | | DEFAULT_TIMEOUT | Request timeout in milliseconds | 30000 | No | | LOG_LEVEL | Logging level (debug/info/warn/error) | info | No |

Example .env File

# Airbnb Plugin Configuration
IGNORE_ROBOTS_TXT=false
DEFAULT_TIMEOUT=30000
LOG_LEVEL=info

Available Tools

1. search-airbnbs

Search for Airbnb listings with various filters and pagination.

Parameters:

• location (required): Location to search for (city, state, etc.)
• placeId (optional): Google Maps Place ID (overrides location parameter)
• checkin (optional): Check-in date (YYYY-MM-DD)
• checkout (optional): Check-out date (YYYY-MM-DD)
• adults (optional, default: 1): Number of adults
• children (optional, default: 0): Number of children
• infants (optional, default: 0): Number of infants
• pets (optional, default: 0): Number of pets
• minPrice (optional): Minimum price for the stay
• maxPrice (optional): Maximum price for the stay
• cursor (optional): Base64-encoded string for pagination
• ignoreRobotsText (optional, default: false): Ignore robots.txt rules

2. get-airbnb-listing-details

Get detailed information about a specific Airbnb listing.

Parameters:

• id (required): The Airbnb listing ID
• checkin (optional): Check-in date (YYYY-MM-DD)
• checkout (optional): Check-out date (YYYY-MM-DD)
• adults (optional, default: 1): Number of adults
• children (optional, default: 0): Number of children
• infants (optional, default: 0): Number of infants
• pets (optional, default: 0): Number of pets
• ignoreRobotsText (optional, default: false): Ignore robots.txt rules

Usage Examples

Basic Search

# Search for listings in New York
opencode run "search airbnbs in 'New York'"

# Search with specific dates
opencode run "search airbnbs in 'Paris' with checkin '2024-12-20' and checkout '2024-12-25'"

# Search with guest count and price range
opencode run "search airbnbs in 'London' with adults 2 and maxPrice 200"

Get Listing Details

# Get details for a specific listing
opencode run "get-airbnb-listing-details with id '12345678'"

# Get details with dates for pricing
opencode run "get-airbnb-listing-details with id '12345678' and checkin '2024-12-20' and checkout '2024-12-25'"

Advanced Search

# Search with multiple filters
opencode run "search-airbnbs with location 'Tokyo' and adults 3 and children 1 and minPrice 100 and maxPrice 500"

# Search with pets
opencode run "search-airbnbs with location 'San Diego' and adults 2 and pets 1"

Error Handling

The plugin provides comprehensive error handling for common scenarios:

Common Errors and Solutions

1. Robots.txt Blocked

   Error: This path is disallowed by Airbnb's robots.txt

   Solution: Set IGNORE_ROBOTS_TXT=true in your .env file for testing

2. Request Timeout

   Error: Request timeout after 30000ms

   Solution: Increase DEFAULT_TIMEOUT in your .env file

3. Page Structure Changed

   Error: Could not find data script element - page structure may have changed

   Solution: This indicates Airbnb has updated their website structure. The plugin may need updates.

4. Invalid Date Format

   Error: Invalid date format

   Solution: Use YYYY-MM-DD format for all dates

Testing

Run Test Scenarios

# Test search functionality
npm run test:scenarios

# Test individual queries
npm run test:queries

# Test all functionality
npm run test:all

Manual Testing

# Test basic search
opencode run "search airbnbs in 'New York'"

# Test listing details
opencode run "get-airbnb-listing-details with id '12345678'"

# Test error handling
opencode run "search airbnbs in ''"

Technical Details

Data Extraction

The plugin extracts data from Airbnb's web pages by:

1. Fetching the HTML content of search or listing pages
2. Parsing embedded JSON data from script tags
3. Cleaning and structuring the data according to defined schemas
4. Returning formatted results with direct URLs

Rate Limiting

To avoid being blocked by Airbnb:

• The plugin respects robots.txt rules by default
• Uses appropriate user-agent headers
• Implements reasonable timeouts
• Provides option to override robots.txt for testing

Data Schema

The plugin uses predefined schemas to extract relevant information:

• Search Results: Listing ID, title, description, location, pricing, ratings
• Listing Details: Location data, policies, amenities, descriptions, highlights

Directory Structure

pets/airbnb/
├── index.ts              # Main plugin implementation
├── package.json          # Dependencies and metadata
├── README.md             # This documentation
├── .env.example          # Environment variable template
├── .env                  # Your actual configuration (gitignored)
├── .gitignore           # Git ignore file
├── opencode.json        # OpenCode configuration
└── reference/           # Reference implementation (MCP server)
    └── mcp-server-airbnb/

License

MIT License - see LICENSE file for details.

Happy searching! 🏠✈️