Geolocation API
debt(d7/e3/b3/t5)
Closest to 'only careful code review or runtime testing' (d7). The detection_hints indicate automated detection is 'no' and the code pattern is simply checking for getCurrentPosition usage. Missing error callbacks and unset timeouts are not caught by standard linters or compilers — they only surface during manual testing or when users actually encounter permission denial or timeout scenarios in the field.
Closest to 'simple parameterised fix' (e3). The quick_fix describes adding error callback handlers covering all three error codes and setting the timeout option. This is a small, localised change within a single component — not a one-liner swap, but also not a multi-file refactor. Cleaning up watchPosition() leaks similarly requires targeted additions in a few places.
Closest to 'localised tax' (b3). The Geolocation API applies only to web contexts and is typically used in isolated feature components (location-based features). Its misuse (missing error handling, uncancelled watchers) imposes a localised maintenance tax on the component that uses it, without spreading structural debt across the wider codebase.
Closest to 'notable trap' (t5). The misconception field explicitly states that developers assume GPS-accurate coordinates everywhere, when in reality desktop and many mobile devices use WiFi/IP fallbacks with accuracy of hundreds to thousands of metres. This is a well-documented gotcha that most developers discover only after deploying location-dependent features.
TL;DR
Explanation
navigator.geolocation.getCurrentPosition(success, error, options) requests location once. watchPosition() continuously monitors. The Position object includes coords: { latitude, longitude, accuracy, altitude, altitudeAccuracy, heading, speed }. Options: { enableHighAccuracy, timeout, maximumAge }. Error codes: PERMISSION_DENIED (1), POSITION_UNAVAILABLE (2), TIMEOUT (3). Accuracy depends on hardware: GPS chips give metres, WiFi/IP gives kilometres. Always: check navigator.geolocation support, handle all error codes, provide fallback for denied permission, set timeout to avoid indefinite waiting.
Common Misconception
Why It Matters
Common Mistakes
- Not handling error callback — silent failure.
- Not setting timeout — hangs indefinitely.
- Not calling clearWatch() when watchPosition() is no longer needed.
Code Examples
navigator.geolocation.getCurrentPosition(pos => {
showMap(pos.coords.latitude, pos.coords.longitude);
}); // No error handling!if (!navigator.geolocation) {
showError('Geolocation not supported');
return;
}
navigator.geolocation.getCurrentPosition(
pos => showMap(pos.coords.latitude, pos.coords.longitude),
err => {
const msgs = {
1: 'Location access denied — enable in browser settings',
2: 'Location unavailable',
3: 'Location request timed out',
};
showError(msgs[err.code] ?? 'Unknown error');
},
{ timeout: 10000, enableHighAccuracy: false }
);