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.