Skip to main content

Stay Detection

GeoPulse uses a sophisticated algorithm to identify when you've stopped at a location. This document explains the complete process of how stays are detected, from initial clustering to confirmation.

Overview​

Stay detection is the foundation of timeline generation. The system analyzes your GPS data to identify periods when you were stationary at a specific location. A stay is created when:

  1. GPS points cluster together within a defined radius
  2. You remain stationary for a minimum duration
  3. GPS data quality meets accuracy requirements

The algorithm uses a state machine that transitions between states as it processes each GPS point, making decisions based on distance, time, and movement patterns.

The Detection State Machine​

GeoPulse processes GPS points sequentially through a four-state machine:

UNKNOWN → POTENTIAL_STAY → CONFIRMED_STAY
                ↓               ↓
              IN_TRIP ←─────────┘

State Descriptions​

StateDescriptionWhat Triggers Exit
UNKNOWNInitial state before any GPS dataFirst GPS point received
POTENTIAL_STAYClustering in progress, not yet confirmedDuration threshold met OR movement detected
CONFIRMED_STAYValid stay identifiedMovement beyond stay radius
IN_TRIPMoving between locationsSustained stop detected

How a Stay is Detected​

Step 1: Initial Clustering​

When the first GPS point arrives, the system enters POTENTIAL_STAY mode and begins building a cluster:

  1. The first point becomes the seed of the cluster
  2. Each subsequent point is compared to the cluster's centroid (center point)
  3. The centroid is calculated as the mean latitude and longitude of all clustered points

Step 2: Distance Check​

For each new GPS point, the system calculates the distance from the current centroid:

If distance ≤ Stay Detection Radius:

  • Point is added to the cluster
  • Centroid is recalculated
  • Continue clustering

If distance > Stay Detection Radius:

  • Check for Favorite Area containment
  • If not in same area: transition to IN_TRIP
  • Current cluster becomes a trip starting point

Step 3: Duration Confirmation​

While clustering continues (distance checks pass), the system tracks the total duration:

Duration = Last point timestamp - First point timestamp

If duration ≥ Minimum Stay Duration:

  • Transition from POTENTIAL_STAY to CONFIRMED_STAY
  • Stay is now considered valid

If duration < Minimum Stay Duration:

  • Remain in POTENTIAL_STAY
  • Continue collecting points

Step 4: Stay Finalization​

A confirmed stay ends when movement is detected:

  1. New GPS point falls outside the stay radius
  2. Point is not within a shared Favorite Area
  3. System finalizes the stay with:
    • Start time (first clustered point)
    • Duration (last - first timestamp)
    • Location (centroid coordinates)
  4. Transition to IN_TRIP mode

Key Settings Explained​

Stay Detection Radius​

Setting: Stay Detection Radius Default: 50 meters Range: 10-500 meters

This defines the size of the "bubble" used for clustering GPS points.

ValueEffectBest For
10-30mVery sensitive, separate nearby locationsDense urban areas, multiple stores in a mall
50mBalanced detectionMost users, typical accuracy
100-200mMerge nearby locationsPoor GPS areas, large venues
300-500mVery conservativeExtremely poor GPS, general location tracking

Trade-offs:

  • Smaller radius: More precise but may split single visits due to GPS drift
  • Larger radius: More stable but may merge distinct nearby locations
GPS Drift Consideration

If your GPS device has accuracy issues (±30-50m), use a larger radius (75-100m) to prevent artificial stay splits from GPS wandering.

Minimum Stay Duration​

Setting: Minimum Stay Duration Default: 7 minutes Range: 1-60 minutes

The minimum time you must remain stationary for a stay to be confirmed.

ValueEffectBest For
1-3 minDetect very short stopsDelivery drivers, frequent short stops
5-7 minBalanced detectionMost users
10-15 minFilter out traffic delaysCommuters, road trips
20-60 minOnly significant staysBusiness meetings, appointments only

Trade-offs:

  • Shorter duration: More sensitive but may capture traffic stops as stays
  • Longer duration: Cleaner timeline but may miss brief meaningful stops
Traffic Light Problem

Setting duration too low (1-2 minutes) will cause extended traffic stops to appear as stays. The default 7 minutes filters most traffic delays while capturing genuine stops.

GPS Quality Filtering​

GeoPulse uses multiple layers of quality filtering to ensure accurate stay detection.

Accuracy-Based Point Filtering​

Setting: GPS Accuracy Threshold Default: 60 meters Range: 5-200 meters

Points with accuracy worse than this threshold are excluded from processing entirely.

If GPS point accuracy > threshold:
  → Point is ignored (not processed)

Why this matters:

  • Poor GPS accuracy (>60m) indicates the device is uncertain about location
  • Including these points would degrade cluster quality
  • Filtered points don't affect stay detection at all

Cluster Quality Validation​

Setting: Minimum Accuracy Ratio Default: 50% (0.5) Range: 10-100%

After a stay cluster is formed, the system validates overall quality:

Accurate points = count(points with accuracy ≤ threshold)
Ratio = Accurate points / Total points

If ratio < Minimum Accuracy Ratio:
  → Stay is rejected

Example:

  • 10 points in a cluster
  • 4 points have accuracy ≤ 60m (good)
  • 6 points have accuracy > 60m (poor)
  • Ratio = 4/10 = 40%
  • With default 50% threshold: Stay rejected

This ensures that stays are only created when sufficient high-quality GPS data exists.

Enhanced Filtering Toggle​

Setting: Enhanced Filtering Default: Enabled

When enabled, the system uses both accuracy and velocity data for filtering. When disabled:

  • All accuracy-based filtering is bypassed
  • Useful for GPS sources that don't report accuracy
  • May result in lower quality stay detection

Favorite Areas: Special Handling​

Favorite Areas receive special treatment during stay detection to handle large venues where you might walk around but still be "at" the location.

The Problem​

Consider a shopping mall:

  • You enter and walk to different stores
  • Movement between stores might exceed 50m
  • Without special handling, this creates multiple separate stays

The Solution​

When movement exceeds the stay radius, the system checks if both points are within the same Favorite Area:

1. Calculate distance from centroid to new point
2. If distance > stay radius:
   a. Find Favorite Area containing the centroid
   b. Find Favorite Area containing the new point
   c. If same area: Continue stay (point added to cluster)
   d. If different areas: Transition to IN_TRIP

Practical Examples​

University Campus (defined as Favorite Area):

  • You arrive at the library
  • Walk to the cafeteria (500m away)
  • Walk to your classroom (300m from cafeteria)
  • Result: Single continuous stay at "University Campus"

Two Shops in Same Mall (no Favorite Area defined):

  • You visit Store A
  • Walk to Store B (100m away)
  • Result: Two separate stays (Store A, Store B)

Same Scenario with Mall as Favorite Area:

  • You visit Store A
  • Walk to Store B
  • Result: Single stay at "Shopping Mall"
Creating Favorite Areas

Define Favorite Areas for large venues you visit regularly (campuses, malls, office complexes) to get cleaner timeline entries instead of multiple fragmented stays.

Trip Detection and Stay Endings​

How Movement is Detected​

A confirmed stay ends when the system detects you've moved away:

  1. New GPS point is received
  2. Distance to centroid is calculated
  3. If distance > stay radius AND not in same Favorite Area:
    • Stay is finalized
    • Trip begins with the new point

Returning to IN_TRIP Mode​

When movement is detected:

Current State: CONFIRMED_STAY
Action: Receive point 120m from centroid (radius: 50m)
Result:
  1. Finalize stay (startTime, duration, location)
  2. Clear active cluster
  3. Start new trip with this point
  4. Transition to IN_TRIP

Trip Ending Detection​

For details on how trips end and new stays begin, see Trip Detection.

Location Resolution​

After a stay is detected, the system determines where you were:

Resolution Priority​

  1. Favorite Locations - Check if centroid matches a user-defined favorite
  2. Geocoding Results - Look up address/place name from coordinates

Batch Processing​

Location resolution is performed in batches after all stays are detected:

  • Single database query for all stays
  • Matches against favorites and geocoding cache
  • Reduces processing time significantly

What Gets Assigned​

Each stay receives:

  • locationName - Display name (e.g., "Home", "Work", or street address)
  • favoriteId - Link to matching favorite location (if any)
  • geocodingId - Link to geocoding result (if any)

Configuration Recommendations​

For Different Use Cases​

Personal Location Tracking:

Stay Detection Radius: 50m (default)
Minimum Stay Duration: 7 minutes (default)
GPS Accuracy Threshold: 60m (default)

Delivery/Field Service:

Stay Detection Radius: 30m (more precise)
Minimum Stay Duration: 2-3 minutes (catch quick stops)
GPS Accuracy Threshold: 30m (stricter quality)

Road Trip Tracking:

Stay Detection Radius: 75-100m (account for parking lot size)
Minimum Stay Duration: 10-15 minutes (filter rest stops)
GPS Accuracy Threshold: 60m (default)

Urban High-Density:

Stay Detection Radius: 30-40m (separate nearby venues)
Minimum Stay Duration: 5 minutes (default)
GPS Accuracy Threshold: 50m (stricter for cities)

For Different GPS Quality​

High-Quality GPS (modern phone):

Stay Detection Radius: 30-50m
GPS Accuracy Threshold: 30m
Minimum Accuracy Ratio: 70%

Average GPS Quality:

Stay Detection Radius: 50-75m
GPS Accuracy Threshold: 60m
Minimum Accuracy Ratio: 50%

Poor GPS Quality (indoor, urban canyons):

Stay Detection Radius: 100m
GPS Accuracy Threshold: 100m
Minimum Accuracy Ratio: 30%

Troubleshooting​

Problem: GPS points at one location create multiple stays​

Possible Causes:

  • Stay radius too small for GPS accuracy
  • GPS drift exceeding radius threshold

Solutions:

  1. Increase Stay Detection Radius to 75-100m
  2. Check GPS source accuracy settings
  3. Consider defining a Favorite Area for the location

Problem: Nearby distinct locations merge into one stay​

Possible Causes:

  • Stay radius too large
  • Both locations fall within same radius

Solutions:

  1. Decrease Stay Detection Radius to 30-40m
  2. Ensure GPS accuracy is sufficient
  3. Define separate Favorite Locations for each place

Problem: Short stops aren't being detected​

Possible Causes:

  • Minimum stay duration too long
  • Not enough GPS points during the stop

Solutions:

  1. Decrease Minimum Stay Duration to 3-5 minutes
  2. Check GPS tracking frequency (should be every 30-60 seconds)
  3. Verify GPS accuracy isn't filtering out points

Problem: Traffic delays appear as stays​

Possible Causes:

  • Minimum stay duration too short
  • Extended traffic stopped in same location

Solutions:

  1. Increase Minimum Stay Duration to 10-15 minutes
  2. Use default 7-minute threshold for most cases

Problem: Stays have wrong or missing location names​

Possible Causes:

  • No Favorite Location defined for the place
  • Geocoding hasn't processed the coordinates
  • Stay centroid is slightly off from actual location

Solutions:

  1. Create a Favorite Location for frequently visited places
  2. Wait for reverse geocoding to complete
  3. Check if stay radius needs adjustment

Impact on Timeline Rebuild​

Changing stay detection settings triggers a full timeline rebuild:

What Changes:

  • All stays are re-detected with new parameters
  • Stay boundaries and durations may change
  • Some stays may split or merge

What Doesn't Change:

  • Original GPS data remains intact
  • Favorite locations are preserved
Rebuild Time

After changing stay detection settings, the timeline will rebuild from your earliest GPS data. For large datasets, this may take several minutes. You'll see a progress indicator showing the rebuild status.

Stay detection works together with other timeline features:

Summary​

Stay detection identifies when you've stopped at a location using GPS clustering:

  • Clustering algorithm groups nearby GPS points
  • Distance threshold (Stay Detection Radius) defines cluster size
  • Duration threshold (Minimum Stay Duration) confirms valid stays
  • Quality filtering ensures reliable GPS data
  • Favorite Areas handle large venues specially

By understanding these settings and adjusting them for your GPS quality and use case, you can ensure GeoPulse accurately captures all your meaningful stays while filtering out noise and false positives.