tankstopp-app/GEOLOCATION_TROUBLESHOOTING.md

# Geolocation Troubleshooting Guide

## Overview
This guide helps resolve issues with the "Find Nearby" fuel station search feature that uses your device's location to find nearby gas stations.

## Quick Fixes

### 1. Check Browser Permissions
**Firefox:**
1. Click the shield/lock icon in the address bar
2. Make sure "Location" is set to "Allow"
3. If it shows "Blocked", click it and select "Allow"
4. Refresh the page and try again

**Chrome:**
1. Click the lock icon next to the URL
2. Set "Location" to "Allow"
3. Refresh the page

**Safari:**
1. Go to Safari > Preferences > Websites > Location Services
2. Find your site and set it to "Allow"

### 2. Enable Location Services (System Level)

**Windows 10/11:**
1. Settings > Privacy & Security > Location
2. Turn on "Location services"
3. Turn on "Allow apps to access your location"

**macOS:**
1. System Preferences > Security & Privacy > Privacy
2. Select "Location Services"
3. Enable Location Services
4. Check the box for your browser

**Linux:**
1. Settings > Privacy > Location Services
2. Enable Location Services

## Common Issues and Solutions

### Issue: "Location access was denied"

**Cause:** Browser permission blocked
**Solution:**
1. Clear site permissions and try again
2. Check if location services are enabled system-wide
3. Try in incognito/private browsing mode
4. Check if browser has location permission in OS settings

### Issue: "Location information is unavailable"

**Cause:** GPS/location services disabled or poor signal
**Solutions:**
1. Enable GPS on mobile devices
2. Move to an area with better signal (away from buildings)
3. Wait a few moments for GPS to get a fix
4. Try refreshing the page
5. Use Wi-Fi instead of mobile data (often more accurate)

### Issue: "Location request timed out"

**Cause:** Taking too long to get GPS fix
**Solutions:**
1. Wait longer - GPS can take 30+ seconds for first fix
2. Move outside or near a window
3. The app will automatically retry with lower accuracy
4. Use manual entry as backup

### Issue: "This page requires HTTPS"

**Cause:** Modern browsers require secure connection for location access
**Solutions:**
1. Access the site via `https://` instead of `http://`
2. If running locally, use `localhost` instead of IP address
3. Contact administrator to enable HTTPS

## Browser-Specific Issues

### Firefox
- **Private Browsing:** Location might be blocked by default
- **Enhanced Tracking Protection:** May interfere with location
- **Solution:** Temporarily disable tracking protection for the site

### Chrome
- **Incognito Mode:** Location access requires explicit permission
- **Site Settings:** Check chrome://settings/content/location
- **Solution:** Ensure site is not in "Block" list

### Safari
- **Privacy Settings:** May block location by default
- **Website Settings:** Check per-site permissions
- **Solution:** Enable in Safari preferences

### Mobile Browsers
- **App Permissions:** Browser app needs location permission
- **Battery Saving:** May disable GPS
- **Solution:** Check app permissions in device settings

## Debugging Steps

### 1. Check Browser Console
1. Press F12 to open developer tools
2. Go to Console tab
3. Click "Find Nearby" and look for error messages
4. Common errors and meanings:
   - `User denied geolocation` → Permission issue
   - `Position unavailable` → GPS/signal issue
   - `Timeout` → Taking too long to get location

### 2. Test Geolocation Manually
1. Open browser console (F12)
2. Type: `navigator.geolocation.getCurrentPosition(console.log, console.error)`
3. Check if you get coordinates or an error

### 3. Check Permissions API
1. In console, type: `navigator.permissions.query({name: 'geolocation'})`
2. Should return permission state: 'granted', 'denied', or 'prompt'

### 4. Verify HTTPS
1. Check if URL starts with `https://`
2. Look for lock icon in address bar
3. Geolocation requires secure context

## Alternative Solutions

### 1. Manual Entry
- Click "Enter Station Details Manually" in the search modal
- Fill in station name and address yourself
- Useful when location services fail

### 2. Use Map Applications
- Search for "gas stations near me" in Google Maps
- Copy station name and address to TankStopp manually
- More reliable but requires extra steps

### 3. Search by City/Area
- Enter your city name in the location field
- Add station name from memory or other sources
- Good for frequently visited stations

## Technical Details

### Geolocation Requirements
- **HTTPS:** Required for security (except localhost)
- **User Permission:** Must be explicitly granted
- **Active Connection:** Internet required for map data
- **GPS/Network:** Device needs location capability

### How It Works
1. **Request Location:** Browser asks device for coordinates
2. **Get Permission:** User must allow location access
3. **Query Map Data:** Searches OpenStreetMap for fuel stations
4. **Calculate Distance:** Sorts results by proximity
5. **Display Results:** Shows stations with distance

### Accuracy Factors
- **GPS Signal:** Better outdoors with clear sky
- **Wi-Fi Location:** More accurate in urban areas
- **Mobile Network:** Less accurate but faster
- **Device Type:** Phones generally more accurate than laptops

## Advanced Troubleshooting

### Clear Browser Data
1. Clear cookies and site data for the website
2. Reset all permissions
3. Try accessing the site fresh

### Network Issues
- **Firewall:** May block map API requests
- **VPN:** Can affect location accuracy
- **Corporate Network:** May have restrictions

### Device Issues
- **Low Battery:** May disable GPS
- **Airplane Mode:** Disables all location services
- **Location History:** Some devices need this enabled

## Getting Help

### Collect Debug Information
If you're still having issues, collect this information:
1. Browser name and version
2. Operating system
3. Error messages from browser console
4. Whether you're using HTTPS
5. Location permission status

### Contact Support
Include the debug information when reporting issues:
- GitHub Issues: Link to project repository
- Email: Include all debug information
- Forum: Post in relevant community

### Workarounds
While waiting for fixes:
1. Use manual entry for station details
2. Search stations beforehand using map apps
3. Keep a list of frequently visited stations
4. Use desktop version if mobile has issues

## Prevention Tips

### Keep It Working
1. **Don't Block Location:** Always allow when prompted
2. **Use HTTPS:** Bookmark the secure URL
3. **Update Browser:** Keep browser up to date
4. **Enable Location Services:** Keep them on system-wide
5. **Test Regularly:** Verify it works before you need it

### Best Practices
1. **Allow Permission Once:** It will remember for future visits
2. **Be Patient:** GPS can take time for first fix
3. **Have Backup Plan:** Know how to enter manually
4. **Check Signal:** Use near windows or outdoors when possible

## FAQ

**Q: Why does it work sometimes but not others?**
A: GPS accuracy varies by location, weather, and device battery. Indoor locations often have poor GPS signal.

**Q: Can I use it without GPS?**
A: Yes, use the "Enter Manually" option to input station details yourself.

**Q: Is my location data stored?**
A: No, your coordinates are only used for the search and not saved or transmitted to our servers.

**Q: Why does it need HTTPS?**
A: Modern browsers require secure connections for location access as a security measure.

**Q: Can I search a different location?**
A: Currently, it only searches near your current location. Use manual entry for stations in other areas.

## Success Indicators

You'll know it's working when:
- ✅ Modal opens immediately when clicking "Find Nearby"
- ✅ "Requesting your location..." message appears
- ✅ Location is obtained within 15 seconds
- ✅ Search results show nearby stations with distances
- ✅ Clicking a station fills the form fields automatically

If any step fails, refer to the troubleshooting steps above.