Add overnight stay detection and location summary tools

[fiddur]

Background

When analyzing location data to answer questions like "how many nights did I spend at Location X in 2025?", the current API requires fetching raw location data and manually implementing overnight detection logic. This is the most common use case for location tracking analysis.

Proposed New MCP/API Tools

1. query_overnight_stays

Detect overnight stays at a named location.

Parameters:

• location_name (string) - Name of a named location (e.g., "Lönnåsen")
• start (ISO8601DateTime)
• end (ISO8601DateTime)

Returns:

{
  "data": [
    {
      "arrival": "2025-12-19T18:12:03Z",
      "departure": "2025-12-20T06:04:31Z",
      "overnight_date": "2025-12-19",
      "duration_hours": 11.9
    }
  ],
  "total_nights": 9
}

Implementation notes:

• An overnight stay = presence at location with last_seen >= 17:00 on day N AND first_seen <= 10:00 on day N+1
• These thresholds could be configurable parameters with sensible defaults
• Should handle multi-night stays (arrival Friday, departure Sunday = 2 nights)
• Could also support coordinate-based queries instead of named location

2. get_location_summary

Aggregated statistics for time spent at a location.

Parameters:

• location_name (string)
• start (ISO8601DateTime)
• end (ISO8601DateTime)
• group_by (optional): day | week | month | year

Returns:

{
  "total_visits": 102,
  "total_nights": 103,
  "total_hours": 847,
  "breakdown": [
    { "period": "2025-01", "visits": 15, "nights": 10, "hours": 82 },
    { "period": "2025-02", "visits": 14, "nights": 10, "hours": 79 }
  ]
}

3. compare_calendar_locations (after calendar integration)

Cross-reference calendar events with actual location data to find discrepancies.

Parameters:

• calendar_pattern (string) - Regex/glob to match event summaries (e.g., "^Th")
• location_name (string)
• start (ISO8601DateTime)
• end (ISO8601DateTime)

Returns:

{
  "calendar_events": 103,
  "location_confirmed": 95,
  "missing_from_location": ["2025-04-15", "2025-04-17"],
  "extra_in_location": ["2025-03-30"],
  "confirmation_rate": 0.92
}

Use case: Identify GPS tracking gaps or calendar events that didn't happen.

4. detect_routine_patterns

Automatically detect regular location patterns.

Parameters:

• start (ISO8601DateTime)
• end (ISO8601DateTime)
• min_occurrences (optional, default: 4)

Returns:

{
  "patterns": [
    {
      "location": "Lönnåsen",
      "pattern": "weekly",
      "typical_days": ["Tuesday", "Friday"],
      "avg_nights_per_week": 2.0,
      "confidence": 0.85
    }
  ]
}

Priority

I'd suggest implementing in this order:

1. query_overnight_stays - Biggest pain point, most common use case
2. get_location_summary - Natural companion to overnight stays
3. compare_calendar_locations - After calendar integration is done
4. detect_routine_patterns - Nice to have for insights

Technical Notes

The overnight detection algorithm used in manual analysis:

# Group location pings by date
# For each consecutive day pair (today, tomorrow):
if today.last_hour >= 17 and tomorrow.first_hour <= 10:
    # This is an overnight stay on 'today'

The 17:00/10:00 thresholds worked well empirically but edge cases exist (late arrivals, early departures). Consider making these configurable or using a more sophisticated approach based on actual sleep detection from other metrics.