Using Docker (Recommended)#

# Clone the repository
git clone https://github.com/VincenzoImp/job-search-tool.git
cd job-search-tool

# Copy example config and customize
cp config/settings.example.yaml config/settings.yaml
# Edit config/settings.yaml with your preferences

# Run once
docker-compose up --build

# Or run continuously with scheduler + notifications
docker-compose --profile scheduler up scheduler -d

# Launch interactive dashboard
docker-compose --profile dashboard up dashboard
# Open http://localhost:8501

Using Local Python (3.10+)#

pip install -r requirements.txt
cp config/settings.example.yaml config/settings.yaml
cd scripts && python main.py

Search Settings#

search:
  results_wanted: 30        # Results per query per site (max ~1000)
  hours_old: 168            # 168 = 7 days, 720 = 30 days
  job_types:
    - "fulltime"
    - "contract"
  sites:
    - "indeed"              # Best coverage, minimal rate limiting
    - "linkedin"            # Global coverage, aggressive rate limiting
    - "glassdoor"           # Good company insights
  locations:
    - "Zurich, Switzerland"
    - "Remote"
  distance: 50              # Search radius in miles (~80 km)
  is_remote: false          # true = remote only
  linkedin_fetch_description: true  # Get full descriptions (slower)

Search Queries#

queries:
  software_engineering:
    - "software engineer"
    - "backend developer"
    - "full-stack developer"
  data:
    - "data engineer"
    - "data scientist"
  # Add your own categories

Query Syntax Tips (especially for Indeed):

• Use "" for exact match: "software engineer"
• Use - to exclude: software -marketing -sales
• Use OR for alternatives: (python OR java OR c++)
• Use () for grouping: (senior OR lead) engineer

Relevance Scoring#

scoring:
  threshold: 10             # Minimum score to be "relevant"
  weights:
    primary_skills: 20      # Your main expertise
    technologies: 12        # Tech stack matches
    seniority_match: 10     # Level matching
  keywords:
    primary_skills:
      - "software engineer"
      - "backend"
    technologies:
      - "python"
      - "javascript"
      - "react"

Parallelism & Retry#

parallel:
  max_workers: 5            # Concurrent searches (3-5 recommended)

retry:
  max_attempts: 3           # Retry failed requests
  base_delay: 2             # Initial delay (seconds)
  backoff_factor: 2         # Exponential multiplier

Scheduler & Notifications#

scheduler:
  enabled: true             # Enable scheduled mode
  interval_hours: 24        # Run every 24 hours
  run_on_startup: true      # Run immediately when starting

notifications:
  enabled: true
  telegram:
    enabled: true
    bot_token: "YOUR_BOT_TOKEN"      # From @BotFather
    chat_ids: ["YOUR_CHAT_ID"]
    min_score_for_notification: 15   # Only notify high-score jobs
    max_jobs_in_message: 10          # Top 10 jobs in notification

Notification Example#

When new jobs are found, you’ll receive a Telegram message like:

🔔 Job Search Tool - New Jobs Found
━━━━━━━━━━━━━━━━━━━━━

📊 Run Summary
• Date: 2025-12-23 09:00
• Total found: 150
• New: 12
• Avg score: 24.5

━━━━━━━━━━━━━━━━━━━━━

🏆 Top 5 New Jobs

1️⃣ Backend Engineer
   🏢 TechCorp Inc.
   📍 Berlin, Germany
   ⭐ Score: 48
   View Job →

2️⃣ Full Stack Developer
   🏢 Startup AG
   📍 Remote
   ⭐ Score: 42
   View Job →
...

Database (data/jobs.db) - PRIMARY STORAGE#

The SQLite database is the core storage used by the system for:

• Tracking all jobs seen across runs
• Identifying new vs already-seen jobs
• Determining which jobs to notify about
• Marking jobs as “applied”

Results Directory (results/) - OPTIONAL#

CSV/Excel files are optional exports for human review. Disable with:

output:
  save_csv: false
  save_excel: false

When enabled (default), generates:

Database Schema#

Features#

• Multiple data sources: Load from CSV files or SQLite database
• Comprehensive filtering: Text search, job level, sites, companies, locations, job types, remote status, salary range, relevance score, date posted
• Statistics view: Total jobs, average score, top sources, remote jobs count
• Interactive charts: Jobs by source, score distribution
• Sortable table: Customize columns, sort by any field, clickable job links
• Job details view: Full description and metadata
• Export: Download filtered results as CSV or Excel

Launch Dashboard#

# Using Docker
docker-compose --profile dashboard up dashboard
# Open http://localhost:8501

# Using Local Python
cd scripts && streamlit run dashboard.py

Supported Countries#

Indeed Filter Exclusivity#

Indeed can only use ONE of these filters at a time:

• hours_old (date filtering)
• job_type + is_remote
• easy_apply

We prioritize hours_old for fresh results. If you need job type filtering, set hours_old: null.

LinkedIn Rate Limiting#

• Built-in delays: 3-7 seconds between requests
• Hard limit at ~1000 results
• Heavy rate limiting around 10th page
• linkedin_fetch_description=True doubles request count

Glassdoor Issues#

• “Location not parsed” errors for locations not in database
• 400/429 errors indicate rate limiting

Rate Limiting / Empty Results#

1. Reduce parallel.max_workers to 3
2. Reduce search.results_wanted to 20
3. Increase retry.base_delay to 5
4. Run at different times of day
5. Consider using proxies for heavy usage

Docker Issues#

docker-compose down
docker system prune -f
docker-compose up --build

Python Version#

This tool requires Python 3.10+ (JobSpy library requirement). Check your version:

python3 --version

If below 3.10, use Docker instead.