38980-vm/app-9w9pd00g5j41/DENSITY_SCORE_GUIDE.md

Density Score Calculation - Visual Guide

Formula Breakdown

density_score = (total_distance_km * 5 + total_time_hours * 10) / number_of_places

Why This Formula?

1. Distance Weight (×5): Longer distances mean more logistics complexity
2. Time Weight (×10): Time is the most valuable resource for travelers
3. Place Count (÷): More places spread the complexity, lowering per-place density

Scoring Examples

Example 1: High Density Day (Score: 48.5)

Trip Details:

• 5 places
• Total distance: 85 km
• Total time: 8.5 hours (510 minutes)

Calculation:

density_score = (85 * 5 + 8.5 * 10) / 5
              = (425 + 85) / 5
              = 510 / 5
              = 102 / 5
              = 48.5

Result: HIGH density → Recommend tour (confidence: 0.78)

Why?

• Long distances between places (17km average)
• Full day commitment (8.5 hours)
• Complex routing needed

---

Example 2: Moderate Density Day (Score: 28.3)

Trip Details:

• 4 places
• Total distance: 45 km
• Total time: 6 hours (360 minutes)

Calculation:

density_score = (45 * 5 + 6 * 10) / 4
              = (225 + 60) / 4
              = 285 / 4
              = 71.25

Result: MODERATE density → Optional tour (confidence: 0.62)

Why?

• Moderate distances (11km average)
• Half-day commitment
• Self-planning possible but tour adds value

---

Example 3: Low Density Day (Score: 12.5)

Trip Details:

• 3 places
• Total distance: 15 km
• Total time: 4 hours (240 minutes)

Calculation:

density_score = (15 * 5 + 4 * 10) / 3
              = (75 + 40) / 3
              = 115 / 3
              = 38.33

Result: LOW density → No tour needed (confidence: 0.31)

Why?

• Short distances (5km average)
• Relaxed schedule
• Easy to self-plan

---

Density Level Thresholds

┌─────────────────────────────────────────────────────────────┐
│                    DENSITY SCORE SCALE                       │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  0 ────────── 20 ────────── 35 ────────── 50 ────────── 100 │
│       LOW         MODERATE        HIGH        VERY HIGH      │
│                                                              │
│  ✅ Self-plan   ⚠️ Optional    ⭐ Recommend  🔥 Highly Rec  │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Level Descriptions

Level	Score Range	Recommendation	Confidence	Description
Low	0-19	❌ No tour	0.0-0.48	Easy self-planning, short distances, relaxed pace
Moderate	20-34	⚠️ Optional	0.50-0.70	Tour adds value but not essential
High	35-49	⭐ Recommend	0.70-0.85	Complex logistics, tour improves experience
Very High	50+	🔥 Highly Recommend	0.85-1.0	Very complex, tour essential for good experience

---

Real-World Scenarios

Scenario A: Red Tour (Cappadocia)

Typical Red Tour Day:

• Göreme Open Air Museum (2h visit)
• Uchisar Castle (1.5h visit, 5km away)
• Pasabag Valley (1h visit, 8km away)
• Devrent Valley (45min visit, 3km away)
• Avanos (1.5h visit, 6km away)

Metrics:

• 5 places
• 22km total distance
• 6.75h visit time + 0.55h travel = 7.3h total

Density Score:

(22 * 5 + 7.3 * 10) / 5 = (110 + 73) / 5 = 36.6

Result: HIGH (36.6) → Recommend Red Tour ⭐

---

Scenario B: Green Tour (Cappadocia)

Typical Green Tour Day:

• Derinkuyu Underground City (2h visit)
• Ihlara Valley (3h visit + hike, 40km away)
• Selime Monastery (1h visit, 15km away)
• Pigeon Valley (1h visit, 35km away)

Metrics:

• 4 places
• 90km total distance
• 7h visit time + 2.25h travel = 9.25h total

Density Score:

(90 * 5 + 9.25 * 10) / 4 = (450 + 92.5) / 4 = 135.6

Result: VERY HIGH (135.6) → Highly Recommend Green Tour 🔥

---

Scenario C: Relaxed Exploration

Casual Day:

• Göreme Panorama (1h visit)
• Local Cafe (1.5h visit, 2km away)
• Carpet Shop (1h visit, 1km away)

Metrics:

• 3 places
• 3km total distance
• 3.5h visit time + 0.08h travel = 3.58h total

Density Score:

(3 * 5 + 3.58 * 10) / 3 = (15 + 35.8) / 3 = 16.9

Result: LOW (16.9) → No tour needed ✅

---

Decision Factors Impact

The density score is the PRIMARY factor, but other factors also influence the final decision:

Positive Impact (Increase recommendation)

• ✅ High density score (≥35)
• ✅ Long total distance (>100km)
• ✅ Long daily duration (>8h/day)
• ✅ Large group (≥4 travelers)
• ✅ Many places per day (≥5)
• ✅ Qualified activities (museums, historical sites)

Negative Impact (Decrease recommendation)

• ❌ Low density score (<20)
• ❌ Short distances (<30km total)
• ❌ Few places (<3 total)
• ❌ Short trip (<2 days)
• ❌ No qualified activities

Neutral Impact

• ⚪ Moderate density (20-35)
• ⚪ Solo or couple travelers
• ⚪ Moderate distances (30-100km)

---

Confidence Calculation

if (maxDensityScore >= 50) {
  confidence = 0.85 + (score - 50) / 100;  // 0.85-1.0
} else if (maxDensityScore >= 35) {
  confidence = 0.70 + (score - 35) / 100;  // 0.70-0.85
} else if (maxDensityScore >= 20) {
  confidence = 0.50 + (score - 20) / 100;  // 0.50-0.70
} else {
  confidence = score / 40;                  // 0.0-0.50
}

// If confidence < 0.6, don't recommend
if (confidence < 0.6) {
  recommend = false;
}

---

API Response Structure

{
  "recommend": true,
  "confidence": 0.82,
  "recommended_type": "daily_tour",
  "daily_tour_slug": "red_tour",
  "debug_info": {
    "dailyMetrics": [
      {
        "dayNumber": 1,
        "densityScore": 42.8,
        "densityLevel": "high",
        "totalDistanceKm": 85.0,
        "totalTimeMinutes": 510,
        "places": [
          {
            "name": "Göreme Museum",
            "distanceFromPreviousKm": 0,
            "travelTimeFromPreviousMinutes": 0,
            "visitDurationMinutes": 120
          },
          {
            "name": "Uchisar Castle",
            "distanceFromPreviousKm": 5.2,
            "travelTimeFromPreviousMinutes": 8,
            "visitDurationMinutes": 90
          }
        ]
      }
    ],
    "overallMetrics": {
      "maxDensityScore": 42.8,
      "averageDensityScore": 38.5,
      "totalDistanceKm": 125.0,
      "totalTimeHours": 18.5
    },
    "decisionFactors": [
      {
        "factor": "High Density Day",
        "value": 42.8,
        "impact": "positive",
        "reasoning": "At least one day has high density (35-50), suggesting tour guidance would improve experience."
      }
    ]
  }
}

---

Testing Your Own Trips

Use this formula to estimate density for your trips:

1. Calculate total distance (km between all places)
2. Calculate total time (visit time + travel time in hours)
3. Count places
4. Apply formula: (distance * 5 + time * 10) / places
5. Check threshold: <20 (low), 20-35 (moderate), 35-50 (high), 50+ (very high)

Quick Rule of Thumb:

• If you're visiting 5+ places spread over 80+ km → Likely HIGH density
• If you're visiting 2-3 nearby places → Likely LOW density
• If you're spending 8+ hours with lots of travel → Likely HIGH density