---
created: 2026-03-12
source: Rivet
tags: [agent-archive, rivet]
---

# GPS Auto-Detect Location Feature Spec

## Overview
Eliminate manual address entry for RateRight's construction labour marketplace by implementing GPS auto-detection with Google Places API integration.

## Technical Research Summary

### PWA Geolocation API
- **Accuracy**: 3-30 meters with `enableHighAccuracy: true`
- **Limitations**: 
  - Urban canyon effect from tall buildings
  - Requires clear sky view for best results
  - Initial location may be cached/inaccurate
  - Browser must request permission
- **Best Practice**: Use `watchPosition()` for continuous updates until desired accuracy achieved

### Google Places API Pricing (2024)
- **Autocomplete**: $2.83 per 1000 requests (first 10K free/month)
- **Place Details**: $5.00 per 1000 requests (first 10K free/month)
- **Session-based**: Autocomplete sessions ending with Place Details are FREE
- **Monthly Credit**: $200 credit applies to all requests

### Privacy & Permission Best Practices
- Request permission only after user interaction
- Provide context explaining why location is needed
- Offer manual entry alternative
- Handle blocked permissions gracefully

## User Flows

### 1. Job Posting (Contractors)

**Auto-Detect Flow:**
1. Tap "Use Current Location" button (glove-friendly, large target)
2. Show permission prompt with context: "We need your location to find nearby workers"
3. Display loading spinner while detecting location
4. Show detected address with confirmation prompt:
   - "Is this correct? [Address]"
   - Buttons: "Yes, use this" / "No, enter manually"
5. If confirmed, auto-populate location field with full address

**Manual Fallback:**
- Always visible "Enter address manually" option
- Large text input field for address typing
- Google Places autocomplete for assistance

### 2. Worker Job Search

**Jobs Near Me:**
1. Prominent "Find Jobs Near Me" button on home screen
2. Request location permission with context
3. Show jobs within 10km radius (adjustable filter)
4. Display distance from current location for each job
5. Allow location refinement via map pin drag

## Implementation Requirements

### Accuracy Standards
- **Minimum**: 50 meters accuracy for construction sites
- **Target**: 10-20 meters accuracy for precise job locations
- **Fallback**: Allow manual correction within 100m radius

### Permission Handling
```javascript
// Check permission status first
const permission = await navigator.permissions.query({ name: 'geolocation' });

// Only request after user interaction
locationButton.addEventListener('click', async () => {
  navigator.geolocation.getCurrentPosition(
    successCallback,
    errorCallback,
    { enableHighAccuracy: true, timeout: 10000, maximumAge: 60000 }
  );
});
```

### Address Resolution
1. Get GPS coordinates from device
2. Reverse geocode using Google Geocoding API ($5 per 1000 requests)
3. Parse response for street address, suburb, state, postcode
4. Display formatted Australian address

### Error Handling
- **GPS Unavailable**: Show manual entry with message "GPS not available, please enter address"
- **Permission Denied**: Show manual entry with "Location access denied, please enter address"
- **Poor Accuracy**: Show warning "Poor GPS signal detected. Tap to retry or enter manually"
- **Timeout**: Auto-retry up to 3 times, then offer manual entry

## Cost Estimates

### Monthly Usage (Sydney Launch)
- **Job Posts**: 500/month × 1 location request = 500 requests
- **Job Searches**: 5,000/month × 1 location request = 5,000 requests
- **Total**: 5,500 requests/month

### Monthly Cost
- **Autocomplete Sessions**: FREE (with Place Details completion)
- **Place Details**: 5,500 × $0.005 = $27.50
- **After $200 Credit**: $0 (well within free tier)

### Scale Projections
- **10K requests**: $0 (within free tier)
- **50K requests**: $113 (after free tier)
- **100K requests**: $283 (after free tier)

## Implementation Timeline

**Week 1**: Core geolocation detection
**Week 2**: Google Places integration
**Week 3**: UI/UX implementation
**Week 4**: Error handling and edge cases
**Total**: 4 weeks development time

## Key Considerations

1. **Construction Site Reality**: GPS may be poor on active sites - always provide manual override
2. **Glove-Friendly Design**: Large buttons, clear visual feedback
3. **Battery Impact**: Use single location request, not continuous tracking
4. **Privacy First**: Only request when user explicitly chooses location feature
5. **Fallback Strategy**: Manual entry must be equally accessible and functional