Smart Search & Magic Search

Smart Search automatically ensures data freshness, while Magic Search enables one-click company analysis.

🔍 Smart Search

When you search for a company, Smart Search automatically:

1. Checks database for existing data
2. Verifies freshness (< 7 days = fresh)
3. Triggers scraping if data is stale or missing
4. Returns status with real-time progress

API Endpoint

GET /api/search/smart?q=COMPANY&country=COUNTRY&auto_scrape=true

Parameters:

Parameter	Type	Default	Description
q	string	required	Company name to search
country	string	"de"	Country code (de, at, ch)
auto_scrape	bool	true	Auto-trigger scraping if stale

Response

{
  "status": "found",
  "company_name": "BMW",
  "company_slug": "bmw",
  "data_status": "fresh",
  "review_count": 5621,
  "last_updated": "2025-12-27",
  "scraping_jobs": [],
  "message": "Data is up to date"
}

Status Values

Status	Meaning
found	Company exists with fresh data
refreshing	Data stale, scraping in progress
scraping	New company, first scrape started
not_found	Company not on Kununu
error	Something went wrong

🚀 Magic Search

Magic Search is a one-click analysis trigger. Enter a company name and the system:

1. Discovers Kununu slug via intelligent slug finder
2. Creates 4 scraping jobs (Kununu, Google, Reddit, Vacancies)
3. Returns job IDs for progress tracking
4. Runs sentiment analysis after scraping completes

API Endpoint

POST /api/scraping/magic-search

Request:

{
  "company_name": "Spotify",
  "country": "de",
  "months_back": 24
}

Response (Success):

{
  "status": "scraping_started",
  "company_slug": "spotify-ab1",
  "company_name": "Spotify",
  "jobs_started": 4,
  "job_ids": ["uuid1", "uuid2", "uuid3", "uuid4"],
  "message": "🚀 Analysis started! Check back in 5-10 minutes."
}

Response (Not Found):

{
  "status": "error",
  "error": "company_not_found",
  "message": "Company 'XYZ' was not found on Kununu."
}

Job Types

Source	Data Collected
Kununu	Employee reviews (primary)
Google	Google Maps reviews
Reddit	Company discussions
Vacancies	Indeed job postings

🧭 Slug Finder

The intelligent slug finder discovers Kununu company URLs:

Strategy Priority

1. Database cache - Check existing company_profiles
2. Direct URL - Try simple slug (e.g., klingelnberg)
3. Kununu search - Parse search results with smart matching
4. URL variants - Try suffixes (-ag, -gmbh, -suisse)
5. Google fallback - Last resort search

Smart Matching

• Compares search results using similarity scoring
• Filters generic pages (beste-arbeitgeber, top-companies)
• Minimum threshold of 0.3 required for match

Examples:

Query	Found Slug	Method
Klingelnberg	klingelnberg	Direct URL
ALDI	aldi-suisse	Cached
UBS	ubs-deutschland	Direct URL
Swiss Re	null	Not on Kununu ✅

🍕 Pizza Tracker Integration

During Magic Search, the Pizza Tracker shows real-time progress:

⏳ Finding company profile...
🔍 Discovering Kununu slug...
🚀 Starting 4 scraping jobs...
📊 Kununu: 0/200 reviews...
📊 Kununu: 50/200 reviews...
📊 Kununu: 150/200 reviews...
✅ Scraping complete! Running AI analysis...
✅ Analysis complete! View report →

⚙️ Freshness Thresholds

Metric	Threshold	Action
Max age	7 days	Trigger refresh if older
Min reviews	50	Trigger if fewer
Sentiment coverage	80%	Run analysis if below

🌍 Region Filtering

Magic Search supports region-specific scraping:

{
  "company_name": "Lidl",
  "country": "ch"  // Switzerland only
}

Supported regions:

• de - Germany
• at - Austria
• ch - Switzerland
• global - All regions (default)

---

Smart Search and Magic Search are powered by the AI Agent's search_company and run_analysis tools.