Filling a ZIP code from browser geolocation

Context

A request to add "fill the ZIP from my location" to a form. The architects asked to estimate it have not seen an implementation or its failure modes, so the estimate has nothing to anchor on. This document and its demo exist to give them one: a working control they can click, and a plain account of what happens between the click and the filled field.

The proof

Click the control. The panel beneath it shows what the browser reported, what the geocoder returned, how long each step took, and why the field did or did not fill. The Simulate switch triggers each failure path without changing browser settings. The same component runs on its own page at /zip-locator.

The sequence

1. The user clicks Use my location. Nothing runs on page load — a permission prompt on arrival is the pattern users have learned to refuse, and each attempt costs a billable request.
2. The browser asks for permission (once per origin; a refusal is remembered).
3. navigator.geolocation.getCurrentPosition returns a latitude, longitude, and an accuracy radius in meters — from GPS on a phone, from Wi‑Fi or IP on a laptop.
4. The Maps JavaScript SDK's Geocoder is asked to reverse‑geocode that point.
5. The response's address_components are searched for the one typed postal_code.
6. If it matches the field's own constraint (five digits for a US ZIP), the field is filled and focused. Otherwise the field is left untouched and a one‑line status says why.

The field is editable in every state. Location is an accelerator, never a gate.

Implications an estimate has to price in

• Permission is one‑shot and sticky. A denial persists for the origin; the UI must read well in the denied state forever, not just on the first visit.
• HTTPS is required. getCurrentPosition is unavailable on insecure origins.
• Accuracy varies by device. A desktop on Wi‑Fi can be kilometres out — enough to cross a ZIP boundary. The accuracy radius is available and should be shown, not hidden.
• A ZIP is not a service area. Filling a ZIP says where the user is, not what they are eligible for; those are separate lookups.
• The key is public by design. A Maps browser key ships to every visitor. Its protection is the HTTP‑referrer restriction and the per‑API quota caps, which is where the real setup work is.
• Every click is a billable geocoding request. Caps bound the cost; the UI never fires without a click.
• Nothing is stored. The position is used for one lookup and discarded.

Alternatives the estimate should weigh

For an AEM implementation

This is a client‑side component with one external script and one key: no dispatcher or CDN change, one connect-src line for maps.googleapis.com in the content security policy, and key management as the substantive task.

What was measured

Pending — see the metrics on this document as the POC records them: geocode round‑trip, accuracy radius on desktop versus mobile, and requests per day against the cap.