what3words

what3words gives every 3 m × 3 m square on Earth a unique three-word address (///filled.count.soap). Crews can read one over the radio far more reliably than a pair of decimal coordinates, and a mis-heard word does not land next door. Similar-sounding addresses are deliberately placed far apart, so a wrong word usually resolves hundreds of kilometres away. The UI uses that quietly: every suggestion shows its nearest place and distance as plain metadata. There are no warning icons; the number speaks for itself.

Where it appears

Surface	What it does
Coordinates card (right-click, long-press, Get Coordinates)	A featured what3words block leads the card: red-tinted with a left accent, the words a size up, nearest place, and a copy button. The numeric formats follow below it. The square is outlined on the map while the card is open.
Voice	A mic in the search box and in the alert-form address field (Chrome, Edge, Safari; hidden in Firefox). Dictation is sent to what3words as input-type=generic-voice, which corrects recogniser slips such as "filled count soap" or "filled dot count dot soap". Speech goes to the browser vendor's recogniser, not to our servers.
Share link	/?w3w=filled.count.soap opens the map at zoom 19 on that square, outlined. The address bar follows the searched square. The coordinates card and the map pill both have Copy link. Signed-in users only, like the rest of what3words.
Outgoing alerts	Done in the backend (Frontend.API looks the address up when an alert is created or moved, and stores it in AlertMessage.What3Words). The email has a linked what3words: row, the SMS a Location: line, the phone call speaks the words, and the webhook has a what3words field. See the ImageAcquisition doc what3words on Alerts for the rollout order.
Search box	The magnifier collapses as soon as you type, giving the text its room back. Up to 3 suggestions in a what3words group. Each row has a red /// in the icon slot, the words in full on the first line (never truncated, wrapped if long), and a muted "nearest place · distance from map centre in miles" on the second. Dotted input (filled.count.so, ///…, a w3w.co/… link) puts the group first. Radio-style input (filled count soap) adds it last, and only when no camera matches. Picking one zooms to the square (zoom 19) and draws exactly that 3 m square: a red fill with a thin dashed red edge over a thin white one. Nothing else is drawn, because any marker sized in pixels would suggest an area that isn't the square. There is no search pin, because it would cover the square. A pill shows the words, Copy link and ×.
Camera details (Location Details)	A W3W row in the same copy · label · value pattern as DD/DDM/DMS.
Alerts panel + map alert modal	A plain W3W row under Lat/Long, matching it (no actions). Shows the alert's stored what3words (the Alerts layer field the backend writes); older alerts, or alerts whose lookup failed, fall back to a live lookup (in the panel, only once expanded). After an edit the row looks up the new square.
Alert create / edit (Alert Origin)	A what3words field. It shows the pin's address and accepts a typed or radio-relayed one. You pick from suggestions, each showing its nearest place and distance from the current pin, so a typo can never silently move the pin.
Locate on map	The result card and the located-point chip show the target's address. The copied report adds (///words) after the coordinates. The card's tooltip says the address is only as precise as the fix (a few hundred feet), not 3 m.

Architecture

browser ── /api/w3w/{convert-to-3wa, convert-to-coordinates, autosuggest}
              │  session-gated in proxy.ts; zod-validated; per-user rate ceilings
              ▼
        lib/server/what3words.ts ── X-Api-Key header ──► api.what3words.com/v3
              (key: W3W_API_KEY, else Key Vault "What3WordsApiKey")

• The key never reaches the browser. Every call goes through the BFF. The routes are in the proxy.ts matcher, so only signed-in users can spend the plan's quota.
• Caching. A square's words never change, so conversions are cached in memory for 30 days (20k entries, LRU). Each conversion seeds the reverse lookup, and concurrent identical requests share one upstream call. Autosuggest is cached for 10 min (focus rounded to 0.01°). The browser also keeps conversions (Cache-Control: private, max-age=86400, and React Query staleTime: Infinity).
• Quota guard. convert-to-coordinates is the only metered call. It only runs when a person picks an address, and the user limit is 30/min. A 401/402 from what3words (bad key, plan without the feature, quota spent) makes the BFF stop calling for 10 min and answer 503 unavailable. The client then latches useW3WStore.unavailable and every surface hides, rather than showing users an error they cannot fix.
• Kill switch. The enable-what3words feature flag (default on). Without a key, the BFF answers 503 not-configured and the UI hides on its own.
• No 3 m grid. what3words offers a grid overlay; it was tried and removed. The coordinates card already names and outlines the exact square of any point, the grid only reads from street-level zoom, and around a located smoke point (good to a few hundred feet) it would suggest precision the fix does not have. The outlined square draws on a hidden GraphicsLayer (w3w-layer), loaded through the shared ArcGIS on-demand module.

Files

Path	Role
util/w3w/what3words.ts	Pure helpers: parsing/normalising (///, links, any separator), isPartial3wa, didYouMean3wa, findPossible3wa, distance formatting.
lib/server/what3words.ts	Key resolution, upstream client, caches, backoff, per-user limits, error mapping.
pages/api/w3w/*.ts	The four routes.
queries/useWhat3Words.ts	useW3WAddress, useW3WAutosuggest, useResolve3wa, useW3WEnabled.
stores/w3wStore.ts	Highlighted square (with its owner: search or coordinates), the unavailable latch.
components/atoms/W3WAddress	W3WWords (red /// + words) and W3WAddress (looks up a point, renders its words as text). The host row owns layout and actions.
components/molecules/W3WLocationInput	Address entry with suggestions (alert forms).
components/organisms/W3WMap	Map layer (the outlined square + its pill) and its on-demand host.

Operations

1. Create the Key Vault secret What3WordsApiKey in each environment's vault (the one AZURE_KEY_VAULT_NAME points at). Alternatively, set the W3W_API_KEY App Service setting.
2. Restart the App Service. The key is cached per instance for the process lifetime.
3. Check: right-click the map while signed in. The card should show a WHAT3WORDS row.
4. Quota: watch the what3words dashboard. Grep the logs for [What3Words] what3words rejected the key or plan.

Not done (candidates)

• Spotting 3 word addresses inside free-text alert messages (findPossible3wa is ready).
• Languages other than English (the routes accept language).
• Offline use needs what3words' Enterprise mobile SDK (native apps only).