HTML Geolocation

Introduction

Geolocation API (navigator.geolocation) exposes device position to JavaScript after explicit user permission — powering Google Maps "near me", Uber pickup pins, and DoorDash store selection. Staff engineers never make geolocation the only input path: always offer manual ZIP/address, cache with maximumAge, handle denial gracefully, and treat precise location as PII under GDPR/CCPA.

Business problem

Business pressure: Location drives conversion for local commerce — Starbucks store finder, Instacart zone check, Zillow neighborhood search. Denied permission or slow GPS fix feels like "app broken" if no fallback. Apple requires purpose strings; EU requires lawful basis logging — enterprise legal reviews geolocation prompts like cookie banners.

• Conversion: Store locator without ZIP fallback loses 40%+ users who deny GPS — Target pattern: parallel manual entry.
• Compliance: Precise coords are personal data — retention limits, privacy policy link at prompt context.
• SEO: Bot has no location — default content must rank nationally; geo personalization is client-only enhancement.

Why this feature exists

Platform motivation: W3C Geolocation API unified GPS, Wi-Fi triangulation, and IP guesswork behind one interface — replacing proprietary Flash/Java location calls. Mobile explosion (2008+) made maps the killer web app.

• History: iPhone Safari early adopter; desktop Chrome uses Wi-Fi/ IP with lower accuracy.
• Alternative rejected: IP geolocation alone in JS — inaccurate, privacy theater, server-side better.
• Modern role: High-accuracy UX enhancement; IP/server geo for default region — Netflix content licensing uses IP, not browser API.

Browser internals

Inside the engine: getCurrentPosition marshals to platform location service (Core Location, Fused Location Provider). Callback on success with Coordinates object; error codes 1 PERMISSION_DENIED, 2 POSITION_UNAVAILABLE, 3 TIMEOUT. watchPosition subscribes to updates — battery cost on mobile if high accuracy continuous.

• Secure context: Blocked on HTTP except localhost — throws or error immediately.
• Permissions API: navigator.permissions.query({name:'geolocation'}) — state prompt/granted/denied; Safari partial support.
• iframe: Disabled unless allow="geolocation" on iframe and parent has permission.

navigator.geolocation.getCurrentPosition(
  pos => console.log(pos.coords.latitude, pos.coords.accuracy),
  err => console.warn(err.code, err.message),
  { enableHighAccuracy: false, timeout: 8000, maximumAge: 60000 }
);

Rendering workflow

Rendering path: Map tile paint independent of geolocation callback — show default map center (US centroid or IP-derived) immediately; pan to user on fix. CLS when "stores near you" list populates — skeleton placeholders for N rows during GPS wait.

• Critical path: Never await geolocation before first paint — Maps loads tiles from default viewport.
• Layout: Reserve map height — Google Maps embed min-height 400px pattern.
• Paint: Re-render store list on position update — virtualize long lists for INP.

Feature deep dive

Geolocation production model: User gesture triggers request — "Use my location" button, not onload. Options: enableHighAccuracy false for store finder (100m enough); true for turn-by-turn. Clear watch on unmount. Display accuracy radius visually — honest UX when 5km IP guess.

• Fallback: Address autocomplete (Google Places) or ZIP input — required for a11y and denial.
• Server: Reverse geocode on server — don't expose API keys client-side without restrictions.
• Testing: Chrome DevTools Sensors override lat/lng — CI E2E with mock coordinates.

<button type="button" id="near-me">Use my location</button>
<label for="zip">Or enter ZIP</label>
<input id="zip" inputmode="numeric" pattern="[0-9]{5}" autocomplete="postal-code">
<div id="stores" aria-live="polite"></div>

Accessibility analysis

A11y architecture: Location-only store finder fails WCAG — users who cannot travel or deny permission need manual search. Announce results via aria-live when stores load. Map markers need textual list alternative — Google Maps list view pattern.

• Screen readers: Don't rely on map pan alone — announce "3 stores found near 94102."
• Keyboard: List of stores fully keyboard navigable without dragging map.
• WCAG: 1.3.1 Info and Relationships — geo filter is supplementary input method.

SEO impact

SEO architecture: Googlebot crawls from US datacenter IP — geo-redirect based on client geolocation hides content from crawlers. Hreflang and server geo for country; client geolocation for store distance only. LocalBusiness schema uses static addresses, not live GPS.

• Crawl: Default national store index page indexable; geo sort client-side OK for UX.
• Rich results: LocalBusiness JSON-LD with geo coordinates of each store — not user's GPS.
• CWV: Maps SDK + geolocation parallel — don't serialise.

Security considerations

Security boundary: Precise coords in URL query params leak via Referer — POST or sessionStorage with care. XSS exfiltrating position to attacker — treat coords like secrets in logs. Permissions-Policy: geolocation=() blocks embedded abuse.

• XSS: Stolen watchPosition stream tracks user movement — sanitize all inputs elsewhere.
• Privacy: Log retention — Uber trip coords regulated; web analytics must not store raw GPS without consent.
• Spoofing: DevTools override — server must not trust client coords for authorization, only UX.

Performance impact

Performance: enableHighAccuracy:true triggers GPS chip — 2–10s fix, battery drain. DoorDash uses coarse first, refine optional. maximumAge:300000 (5 min) avoids re-query on every page navigation in session.

• LCP: Map static image or tiles before GPS — not blank waiting spinner.
• INP: watchPosition firing every second re-sorting DOM — throttle to 30s or significant distance delta.
• Timeout: 8s timeout with ZIP prompt fallback — Google Maps "Can't determine location".

Real production example

Starbucks store locator pattern: Map centered on city from IP; "Use my location" button; ZIP search always visible; stores rendered as accessible list + map pins; coords sent to server for distance sort — server validates plausibility.

• Denied flow: Inline message + focus ZIP field — no modal dead end.
• Accuracy UI: Circle overlay when accuracy >500m — prompt refine or manual.
• Mobile: Combine with device orientation only when explicitly needed — separate permission.

let watchId;
function findStores(lat, lng) {
  fetch('/api/stores/near', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ lat, lng })
  }).then(r => r.json()).then(renderStoreList);
}
document.getElementById('near-me').onclick = () => {
  navigator.geolocation.getCurrentPosition(
    p => findStores(p.coords.latitude, p.coords.longitude),
    () => document.getElementById('zip').focus(),
    { maximumAge: 120000, timeout: 8000 }
  );
};

Enterprise usage

Enterprise: Field service apps on managed iPads — geolocation policy enforced by MDM. Intranet HTTP blocked — geolocation unavailable; IP-only fallback documented. Healthcare: geofencing check-in logs coords — HIPAA audit trail.

• Design system: LocationButton component — always pairs with manual input sibling.
• Legal: Privacy policy link adjacent to first geolocation request in flow.
• CI: E2E tests mock geolocation via Playwright context.setGeolocation.

Common production failures

What breaks in prod: Onload geolocation prompt (Safari auto-deny), no timeout (infinite spinner), trusting client coords for pricing (fraud), HTTP staging environment "broken maps."

• Incident: Retail app sorted prices by GPS — spoofing changed currency region.
• UX: Permission denied with no fallback — 1-star reviews "doesn't work on iPhone."
• Perf: watchPosition in SPA never cleared — battery drain reports on Android.

Architecture review questions

• Is manual address/ZIP available without geolocation?
• Is permission requested on user gesture only?
• Are timeout and maximumAge configured?
• Is watchPosition cleared on unmount?
• Are coords treated as PII in logs and analytics?
• Does SEO content work without client geolocation?

Hands-on project

Project: Store finder: map placeholder, gesture-triggered geolocation, ZIP fallback, aria-live results, accuracy-aware copy, mocked E2E tests.

• Deliverable: Error handling for all three error codes with specific UI.
• Verify: Deny permission flow completes order; axe passes.
• Stretch: maximumAge cache + clearWatch on route change.

Interview questions

Try it yourself

Edit the HTML, CSS, or JS panels — the preview updates as you type.

Summary

Geolocation powers local UX like Google Maps and Uber — production engineering pairs gesture-triggered permission, ZIP/address fallback, accuracy-aware messaging, cached positions, and privacy-safe handling over HTTPS only.