🏠 Idealista Apartment Scraper - Apify Actor

A powerful Apify actor that scrapes apartment listings from Idealista.com. Perfect for real estate monitoring, market research, and data collection.

✨ Features

• 🔍 Flexible scraping: Search by locations or provide direct URLs
• 📊 Rich data extraction: Price, bedrooms, area, floor, amenities (elevator, parking)
• 🛡️ Robust handling: Retry logic with exponential backoff for failed requests
• 🌐 Multi-location support: Scrape multiple neighborhoods simultaneously
• 📱 Structured output: Clean JSON data ready for analysis
• 🔧 Easy configuration: Simple input schema with URL validation
• 🚀 Pagination support: Automatically handles multiple pages of listings
• ⚡ Performance optimized: Reduced API calls with intelligent page reuse

📋 Input Configuration

Search Method (Choose One)

You must provide either locations OR targetUrls (not both):

Option 1: Location-Based Search

• locations (array): List of location paths to scrape
  • Format: ["district/neighborhood", "district/neighborhood"]
  • Example: ["sarria-sant-gervasi/sant-gervasi-galvany", "eixample/la-dreta-de-l-eixample"]
• baseCity (string): Base city for location-based searches (default: "barcelona")
  • Used to construct URLs as: https://www.idealista.com/en/{operation}/{baseCity}/{location}

Option 2: Direct URL Search

• targetUrls (array): Direct URLs to scrape (overrides locations if provided)
  • Must be from idealista.com domain
  • Will automatically add /en/ if not present
  • Example: ["https://www.idealista.com/en/venta-viviendas/barcelona/..."]

Optional Filters

• operationType (string): Type of property search (default: "buy")
  • Options: "buy" (venta-viviendas), "rent" (alquiler-viviendas)
• minPrice (integer): Minimum price filter in euros
• maxPrice (integer): Maximum price filter in euros
• minArea (integer): Minimum area filter in square meters
• maxArea (integer): Maximum area filter in square meters
• timeFilter (string): Time filter for listings (default: "publicado_ultimas-48-horas")
  • Options: "publicado_ultimas-24-horas", "publicado_ultimas-48-horas", "publicado_ultima-semana", "publicado_ultimo-mes"
• sortOrder (string): Sort order for listings (default: "fecha-publicacion-desc")
  • Options: "fecha-publicacion-desc", "fecha-publicacion-asc", "precio-desc", "precio-asc", "metros-desc", "metros-asc"

🚀 Usage Examples

Example 1: Location-Based Search (Barcelona)

{
  "locations": [
    "sarria-sant-gervasi/sant-gervasi-galvany",
    "eixample/la-dreta-de-l-eixample"
  ],
  "baseCity": "barcelona",
  "minPrice": 300000,
  "maxPrice": 500000,
  "minArea": 60,
  "maxArea": 120,
  "timeFilter": "publicado_ultimas-48-horas"
}

Example 2: Rental Properties Search

{
  "locations": [
    "sarria-sant-gervasi/sant-gervasi-galvany"
  ],
  "baseCity": "barcelona",
  "operationType": "rent",
  "minPrice": 1200,
  "maxPrice": 2500,
  "minArea": 60,
  "timeFilter": "publicado_ultimas-48-horas"
}

Example 3: Direct URLs (Advanced)

{
  "targetUrls": [
    "https://www.idealista.com/en/venta-viviendas/barcelona/sarria-sant-gervasi/sant-gervasi-galvany/con-precio-hasta_500000,precio-desde_300000,metros-cuadrados-mas-de_60,publicado_ultimas-48-horas/?ordenado-por=fecha-publicacion-desc"
  ]
}

Example 4: Minimal Configuration

{
  "locations": ["gracia/gracia"],
  "baseCity": "barcelona"
}

Example 5: Multiple Filters

{
  "locations": ["eixample/la-dreta-de-l-eixample"],
  "baseCity": "barcelona",
  "operationType": "buy",
  "minPrice": 400000,
  "maxPrice": 600000,
  "minArea": 70,
  "maxArea": 100,
  "timeFilter": "publicado_ultima-semana",
  "sortOrder": "precio-asc"
}

📊 Output Data

Each apartment listing includes these fields:

{
  "title": "Apartment for sale in Carrer de Muntaner, Sant Gervasi Galvany, Barcelona",
  "price": "450000",
  "bedrooms": "2",
  "area": "75 m²",
  "floor": "3",
  "elevator": "Yes",
  "parking": "No",
  "location": "Sant Gervasi Galvany",
  "address": "Carrer de Muntaner",
  "description": "Bright apartment with natural light and modern finishes...",
  "tags": "exterior, renovated, balcony",
  "image_urls": "https://img3.idealista.com/blur/WEB_LISTING-M/0s60:2560x1707/...",
  "listing_url": "https://www.idealista.com/inmueble/98765432/",
  "search_area": "Sarria Sant Gervasi - Sant Gervasi Galvany"
}

Field Descriptions

• title: Full apartment title from listing
• price: Price in euros (numeric string, no formatting)
• bedrooms: Number of bedrooms (string) or "N/A" if not found
• area: Area with unit (e.g., "75 m²")
• floor: Floor number (string) or "N/A" if not found
• elevator: "Yes" or "No" based on listing details
• parking: "Yes" or "No" based on listing details
• location: Neighborhood name extracted from title
• address: Street address extracted from title
• description: Property description text
• tags: Comma-separated property features
• image_urls: Comma-separated list of image URLs
• listing_url: Direct URL to the apartment listing
• search_area: Formatted search area name for grouping

🔧 Setup & Deployment

Deploy to Apify

1. Fork this repository
2. Connect to Apify Console
3. Set up your actor
4. Configure and run with your desired input parameters

Local Development

# Install dependencies
pip install -r requirements.txt

# Run locally
python main.py

🏗️ Architecture

main.py                 # Apify entry point
├── Gets input parameters
├── Validates configuration
├── Initializes scraper
└── Saves results to dataset

idealista_scraper.py    # Core scraping logic
├── URL generation and validation
├── Web scraping integration
├── Data extraction and parsing
├── Pagination handling
└── Error handling with retries

📍 Supported Locations

The actor supports neighborhoods following the format:

• {district}/{neighborhood}
• Example: sarria-sant-gervasi/sant-gervasi-galvany

Common Barcelona Locations

• sarria-sant-gervasi/sant-gervasi-galvany
• eixample/la-dreta-de-l-eixample
• eixample/l-antiga-esquerra-de-l-eixample
• gracia/gracia
• ciutat-vella/el-born
• sants-montjuic/sants
• horta-guinardo/horta
• sant-marti/poblenou

Note: When using locations, you must also specify baseCity (defaults to "barcelona").

🔄 Rate Limits & Costs

• Apify: Compute units based on runtime
• Pagination: Each page requires a separate API call
• Recommendation: Start with small batches to estimate costs

Cost Optimization

• Use specific time filters (publicado_ultimas-24-horas vs publicado_ultimo-mes)
• Apply price and area filters to reduce result volume
• Target specific neighborhoods rather than broad searches

🛠️ Troubleshooting

Common Issues

1. No results found:

   • Check if location paths are correct
   • Verify baseCity matches the location format
   • Try broader search criteria

2. Scraping errors:

   • Check for temporary site issues
   • Verify URLs are properly formatted

3. Timeout issues:

   • Reduce batch size
   • Try fewer concurrent requests

4. Invalid URLs:

   • Ensure targetUrls are from idealista.com
   • URLs will automatically get /en/ added if missing

Debugging

• Check actor logs for detailed error messages
• Verify input parameters match expected format
• Test with a single location first
• Use the Actor's run detail page to inspect logs

📈 Performance Tips

1. Batch processing: Process multiple locations in single run
2. Time filters: Use recent filters to reduce data volume
3. Price ranges: Narrow price ranges for focused results
4. Monitoring: Set up regular runs for continuous monitoring
5. Pagination: The actor automatically handles multiple pages

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

📝 Recent Updates

Version 0.0.7 (Latest)

• Removed scraped_at field: Timestamp field removed from output data
• Renamed apartment_url to listing_url: Field name updated for better clarity
• Removed bathroom data: Bathroom information no longer extracted
• Removed furnished data: Furnished status no longer extracted
• Enhanced bedroom extraction: Improved detection of bedroom count from listings
• Optimized pagination: Reduced API calls by reusing first page response
• URL validation: Added validation for targetUrls to ensure they're from idealista.com
• Auto-add /en/: Automatically adds /en/ to URLs if not present

Previous Versions

• 0.0.6: Fixed page URL generation for correct query parameter handling
• 0.0.5: Pagination optimization for reduced API calls
• 0.0.4: URL validation implementation

📄 License

This project is open source and available under the LICENSE.

🆘 Support

For issues and questions:

• Check the Apify Documentation
• Open an issue in this repository
• Check the Actor's run logs for detailed error information

---

Note: This actor is for educational and research purposes. Please respect Idealista's terms of service and use responsibly.