n8n-nodes-immometrica-v2

A comprehensive n8n node for extracting real estate data from ImmoMetrica, Switzerland's leading property market platform. This node provides CSV-based data extraction with detailed property scraping capabilities and full AI agent tool compatibility.

🚀 Features

• CSV-Based Data Extraction: Download property data directly from ImmoMetrica saved searches
• Detailed Property Scraping: Extract comprehensive property details including KPIs, amenities, and platform links
• AI Agent Tool Compatible: Fully compatible with GPT-4, Claude, and other AI agents (usableAsTool: true)
• Robust Error Handling: Comprehensive retry logic and graceful error recovery
• Performance Optimized: Parallel processing with intelligent session management
• Quota Management: Built-in quota management to respect ImmoMetrica API limits

📦 Installation

Via NPM (Recommended)

npm install n8n-nodes-immometrica-v2

Via n8n Community Nodes

1. Open your n8n instance
2. Go to Settings → Community Nodes
3. Install n8n-nodes-immometrica-v2
4. Restart n8n

Manual Installation

# Clone the repository
git clone https://github.com/julez4125/n8n-nodes-immometrica-v2.git
cd n8n-nodes-immometrica-v2

# Install dependencies
npm install

# Build the node
npm run build

# Link to your n8n installation
npm link
cd ~/.n8n/nodes
npm link n8n-nodes-immometrica-v2

🔧 Configuration

ImmoMetrica Credentials

Before using this node, you need to configure your ImmoMetrica credentials:

1. Create Credentials:
   • In n8n, go to Credentials → Create New
   • Select ImmoMetrica API
   • Fill in your credentials:

{
  "email": "[email protected]",
  "password": "your-password",
  "baseUrl": "https://www.immometrica.com"
}

2. Test Connection:
   • Use the "Test" button to verify your credentials
   • Ensure you can successfully log in to ImmoMetrica

Required Setup

• Chrome/Chromium: The node requires Chrome or Chromium browser for web scraping
• ChromeDriver: Automatically managed by the node
• Memory: Minimum 2GB RAM recommended for large datasets

📖 Usage Examples

Basic Property Data Extraction

{
  "operation": "extractPropertyData",
  "savedSearchId": "your-search-id-123",
  "maxResults": 100,
  "enableDetailScraping": true
}

Get Available Saved Searches

{
  "operation": "getSavedSearches"
}

Advanced Filtering

{
  "operation": "extractPropertyData",
  "savedSearchId": "search-456",
  "maxResults": 200,
  "enableDetailScraping": true,
  "filterOptions": {
    "minPrice": 1000,
    "maxPrice": 3000,
    "minRooms": 2,
    "maxRooms": 4,
    "propertyType": "apartment",
    "location": "Zurich"
  }
}

🤖 AI Agent Tool Integration

This node is fully compatible with AI agents like GPT-4 and Claude. Here are example prompts:

GPT-4 Integration

// GPT-4 can use this node directly
{
  "operation": "extractPropertyData",
  "savedSearchId": "search-789",
  "searchName": "Basel Apartments",
  "maxResults": 50,
  "enableDetailScraping": true,
  "filterOptions": {
    "minPrice": 1500,
    "maxPrice": 2500,
    "propertyType": "apartment"
  }
}

Claude Integration

// Claude can use minimal parameters
{
  "operation": "getSavedSearches"
}

// Or with specific extraction
{
  "operation": "extractPropertyData",
  "savedSearchId": "my-search-id"
}

Tool Input Validation

The node provides comprehensive input validation with AI-friendly error messages:

• Operation Validation: Ensures valid operation types
• Parameter Validation: Validates all input parameters with type checking
• Range Validation: Ensures values are within acceptable ranges
• Input Sanitization: Cleans and normalizes input data

📊 Output Format

Property Data Structure

{
  "id": "property-123",
  "address": "Musterstrasse 1, 8001 Zürich",
  "price": 2500,
  "rooms": 3.5,
  "area": 85,
  "propertyType": "apartment",
  "availableFrom": "2024-01-01",
  "details": {
    "floor": "2. OG",
    "yearBuilt": 1995,
    "energyLabel": "C",
    "parkingSpaces": 1,
    "balcony": true,
    "elevator": true,
    "petsAllowed": false
  },
  "amenities": [
    "Balkon",
    "Lift",
    "Parkplatz"
  ],
  "platformLinks": {
    "homegate": "https://homegate.ch/...",
    "immoscout24": "https://immoscout24.ch/..."
  },
  "coordinates": {
    "lat": 47.3769,
    "lng": 8.5417
  },
  "scrapedAt": "2024-01-15T10:30:00Z"
}

Metadata Structure

{
  "searchId": "search-123",
  "searchName": "Zurich Apartments",
  "totalResults": 150,
  "scrapedResults": 100,
  "timestamp": "2024-01-15T10:30:00Z",
  "processingTime": "00:02:45",
  "quotaUsed": {
    "csvDownloads": 1,
    "detailPages": 100
  }
}

⚡ Performance Guidelines

Performance Targets

• 50 properties: < 2 minutes
• 100 properties: < 5 minutes
• 500 properties: < 15 minutes
• Memory usage: < 500MB for 1000 objects

Optimization Tips

1. Batch Processing: Process properties in chunks of 50-100
2. Selective Detail Scraping: Only enable when needed
3. Filter Early: Use filterOptions to reduce dataset size
4. Monitor Quotas: Respect ImmoMetrica API limits

Parallel Processing

The node automatically optimizes performance with:

• Parallel Detail Scraping: Max 3 concurrent requests
• Session Caching: Intelligent cookie management
• Memory Management: Efficient handling of large datasets

🚨 Limitations & Quotas

Critical Limitations

• CSV Download Limit: Max 1000 objects per search
• Daily API Limits: Use sparingly to avoid rate limiting
• Session Duration: Cookies valid for 30 minutes
• Rate Limiting: Max 3 parallel detail requests

Quota Management

The node includes built-in quota management:

// Environment variables for quota control
IMMOMETRICA_MAX_TEST_OBJECTS=5
IMMOMETRICA_MAX_DETAIL_PAGES=2
IMMOMETRICA_RETRY_ATTEMPTS=3

Best Practices

1. Start Small: Test with maxResults=10 first
2. Monitor Usage: Track your daily quota consumption
3. Use Filters: Reduce dataset size with filterOptions
4. Cache Results: Store extracted data to avoid re-scraping

🔍 Troubleshooting

Common Issues

Authentication Errors

Error: Login failed - Invalid credentials

Solution: Verify your ImmoMetrica email and password in credentials

Session Timeout

Error: Session expired during CSV download

Solution: The node automatically retries with fresh session

Chrome/ChromeDriver Issues

Error: ChromeDriver not found

Solution: Install Chrome/Chromium browser on your system

Memory Issues

Error: JavaScript heap out of memory

Solution: Reduce maxResults or increase Node.js memory limit

Debug Mode

Enable debug logging:

# Set environment variable
DEBUG=immometrica:*

# Or in n8n settings
LOG_LEVEL=debug

Support

• GitHub Issues: Report bugs and feature requests
• Documentation: Full API documentation
• Community: n8n Community Forum

🧪 Testing

Run Tests

# Unit tests
npm test

# Integration tests
npm run test:integration

# E2E tests (requires credentials)
npm run test:e2e

# Coverage report
npm run test:coverage

Test Configuration

# Set test quotas
export IMMOMETRICA_MAX_TEST_OBJECTS=5
export IMMOMETRICA_MAX_DETAIL_PAGES=2

# Skip E2E tests in CI
export CI=true
export RUN_E2E_TESTS=false

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass: npm test
6. Commit your changes: git commit -m 'Add amazing feature'
7. Push to the branch: git push origin feature/amazing-feature
8. Open a Pull Request

Development Setup

# Clone and setup
git clone https://github.com/julez4125/n8n-nodes-immometrica-v2.git
cd n8n-nodes-immometrica-v2
npm install

# Install Chrome for testing
npm install -g chromedriver

# Run in development mode
npm run dev

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• ImmoMetrica: For providing comprehensive Swiss real estate data
• n8n Community: For the excellent automation platform
• Contributors: Thanks to all contributors who help improve this node

📈 Changelog

See CHANGELOG.md for a detailed history of changes and improvements.

Made with ❤️ for the n8n community