Stop losing track of properties. Stop manually comparing listings. Let AI help you find the best deal.
A self-hosted tool that automatically imports your Idealista saved search emails, ranks properties by investment potential and lifestyle fit, and provides AI-powered analysis to help you make smarter decisions.
Not affiliated with Idealista. Works with your existing Idealista email alerts.
The Problem: You're searching for property on Idealista. You set up email alerts, but:
- Emails pile up and you lose track of what you've seen
- Comparing properties manually is tedious
- You miss price drops or status changes
- You can't easily see all listings on a map
- Making a decision feels overwhelming
The Solution: This tool automatically:
- Imports all your Idealista email alerts into one dashboard
- Scores each property (investment potential + lifestyle fit)
- Shows everything on a map with filters
- Uses AI (Claude/ChatGPT) to analyze properties and compare options
- Tracks which listings are still active vs. sold/removed
| Feature | Description |
|---|---|
| Auto-import | Reads your Gmail/IMAP folder and extracts all Idealista listings |
| Smart scoring | Configurable scoring for Investment, Lifestyle, and Combined ranking |
| Multiple views | List, cards, or interactive map with clustering |
| AI analysis | Get detailed property analysis from Claude and/or ChatGPT |
| Side-by-side comparison | Compare AI recommendations from both models |
| Enrichment | Add travel times, nearby places via Google APIs |
| Favorites & filters | Mark favorites, filter by price/size/score/status |
| CSV export | Export your data anytime |
| Bilingual | English and Spanish UI |
| Dark mode | Light and dark themes |
- Docker Desktop installed and running
- Gmail account with Idealista email alerts
Primary app URL:
http://localhost:5001/
# 1. Clone the repository
git clone https://github.com/sergi039/idealista-tracker-ai.git
cd idealista-tracker-ai
# 2. Create your config file
cp .env.example .env
# 3. Edit .env with your settings (see Configuration below)
# 4. Start the app
docker compose up -d --build
# Optional local dev mode (bind mount + --reload)
# docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d --build
# 5. Open in browser
open http://localhost:5001This repository is the current mainline universal tracker (all property categories). The old land-only flow is kept only for migration/troubleshooting and is no longer the primary workflow.
Current state/backlog: PROJECT_STATUS.md, MIGRATION_RUNBOOK.md.
Edit the .env file. Here's what you need:
| Setting | What it is | How to get it |
|---|---|---|
SESSION_SECRET |
Random string for security | Run: python -c "import secrets; print(secrets.token_hex(32))" |
DB_PASSWORD |
Database password | Choose any password (e.g., mypassword123) |
IMAP_USER |
Your Gmail address | e.g., yourname@gmail.com |
IMAP_PASSWORD |
Gmail App Password | Create App Password (NOT your regular password) |
- Go to Google App Passwords
- Select "Mail" and your device
- Click "Generate"
- Copy the 16-character password (no spaces)
- Paste it as
IMAP_PASSWORDin your.env
Note: You need 2-Factor Authentication enabled on your Google account to create App Passwords.
| Setting | What it enables |
|---|---|
GOOGLE_MAPS_API_KEY |
Interactive maps, travel time calculations |
GOOGLE_PLACES_API_KEY |
Nearby places (train stations, supermarkets, etc.) |
Use the *_KEY names above in your .env (legacy aliases like GOOGLE_MAPS_API / GOOGLE_PLACES_API are still accepted).
How to get: Google Cloud Console → Create credentials → API Key → Enable Maps JavaScript API, Places API, Distance Matrix API.
| Setting | What it enables |
|---|---|
ANTHROPIC_API_KEY |
Claude AI property analysis |
OPENAI_API_KEY |
ChatGPT property analysis |
How to get:
- Anthropic: console.anthropic.com → API Keys
- OpenAI: platform.openai.com → API Keys
Tip: You can use one or both AI providers. Having both enables side-by-side comparison.
| Setting | What it enables |
|---|---|
ADMIN_API_TOKEN |
Access to admin-only endpoints and settings UI (send as Authorization: Bearer <token>) |
# Required
SESSION_SECRET=a1b2c3d4e5f6...your-random-string...
DB_PASSWORD=mypassword123
IMAP_USER=yourname@gmail.com
IMAP_PASSWORD=abcd efgh ijkl mnop
# Optional - Google (for maps)
GOOGLE_MAPS_API_KEY=AIza...
GOOGLE_PLACES_API_KEY=AIza...
# Optional - AI (for analysis)
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
# Optional - Admin
ADMIN_API_TOKEN=your-random-admin-token
# Email folder containing Idealista alerts
IMAP_FOLDER=Idealista- Create one Gmail label/folder (e.g.
Idealista) and route Idealista alerts into it. - First sync may take a few minutes if you have many emails
- Scoring weights can be customized in Settings
- AI analysis costs money per API call — use it on shortlisted properties
Your data is stored locally in a Docker volume (idealista-universal-pgdata). Nothing is sent to external servers except:
- Google APIs (if configured) — for maps/places
- AI APIs (if configured) — for property analysis
This tool is designed for personal use (localhost, home network, VPN).
If you want to expose it publicly, additional security hardening is needed — see CONTRIBUTING.md for details.
| Problem | Solution |
|---|---|
| Can't connect to Gmail | Make sure you're using an App Password, not your regular password |
| No emails importing | Check IMAP_FOLDER matches your Gmail label exactly |
| Maps not showing | Verify Google API keys and enable required APIs in Google Console |
| AI analysis not working | Check API key is valid and has credits |
View logs:
docker compose logs -f appIssues and PRs welcome! See CONTRIBUTING.md.
MIT — see LICENSE.