feat: add `geocode-autocomplete` for free-text address lookup #562

jmcbroom · 2025-07-16T08:45:31Z

a very rough start -- more or less taking code from the existing address-autocomplete.

some questions/thoughts i have:

i'm assuming we just want the input in the autocomplete box, and not as a separate component?
should this fetch/hit find as the user enters text with some kind of debounce/min length before fetching? or should it wait until Enter is hit?

netlify · 2025-07-16T08:45:37Z

✅ Deploy Preview for oslmap ready!

Name	Link
🔨 Latest commit	`d58ba61`
🔍 Latest deploy log	https://app.netlify.com/projects/oslmap/deploys/6892c70fb53eb50008e495b5
😎 Deploy Preview	https://deploy-preview-562--oslmap.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

jessicamcinchak

This works exactly as a I expect! Welcome to geo web component land 🌟

A few minor comments below - think "option" display is the big one to address before merging, but very close to ready !

src/components/geocode-autocomplete/geocode-autocomplete.doc.js

src/components/geocode-autocomplete/index.ts

index.html

jmcbroom · 2025-07-28T13:35:18Z

thanks for the review @jessicamcinchak -- i think this should be good to go now!

DafyddLlyr

Looking great! A few nitpick comments on the code - please feel free to fix or ignore as you see fit.

A few other comments below to be addressed. Happy to talk these through if you'd like, just let me know.

Sorting
We should sort the results in a format expected by the user - currently they're sorted lexicographic which put 1, 10, 11 before 2, 3, 4. I think a user would expect these to be naturally sorted (localCompare()?).

See PlanX for reference -

A quick glance at the docs didn't show a param for this, so we might need to do this ourselves. We probably want to account for MATCH and MATCH_DESCRIPTION here - we don't want to sort naturally, but discounting exactness here. I guess we could group results by MATCH and then sort the subgroups? You could write this by hand or reach for something like orderBy() from lodash which allows sorting by multiple properties (docs).

Number of results
This might be too restrictive - populateResults(options.slice(0, 5))

It's possible that a user would type an address to the greatest accuracy they can (e.g. a full postcode, or street name) and still not be able to select their address. We're fetching up to 100 records from the OS on each request - should we just show them all here? If we decide that a more limited subset is best (e.g 30, 50?) we should match this value with maxResults so that we're never over-fetching 👍

DafyddLlyr · 2025-07-29T13:16:35Z

src/components/geocode-autocomplete/geocode-autocomplete.doc.js

+      name: "osApiKey",
+      type: "String",
+      values: "https://osdatahub.os.uk/plans",
+      required: true,


nit: This should be optional (as long as a proxyEndpoint is provided). I don't think the docs let us express that level of conditionality so it's probably best we just say required: false here.

DafyddLlyr · 2025-07-29T13:17:50Z

README.md

Thanks for updating the links here 💪

DafyddLlyr · 2025-07-29T13:19:55Z

src/components/geocode-autocomplete/styles.scss

@@ -0,0 +1,63 @@
+@import "govuk-frontend/dist/govuk/index";
+// @import "accessible-autocomplete";


nit: Could we tidy up this commented out line?

DafyddLlyr · 2025-07-29T13:22:04Z

src/components/geocode-autocomplete/index.ts

+      : html`
+          <link
+            rel="stylesheet"
+            href="https://cdn.jsdelivr.net/npm/[email protected]/dist/accessible-autocomplete.min.css"


It looks like we missed this link when updating the package. I guess this should point to 3.0.1 both here and in the other autocomplete?

DafyddLlyr · 2025-07-29T13:24:44Z

src/components/geocode-autocomplete/index.ts

+        // min query length of 3 before fetching
+        if (query.length >= 3) {
+          this._fetchData(query, populateResults);
+        }


This is great! I think ideally we'd use the same logic before displaying the tNoResults value also. Currently I get "no addressed found" as soon as I type the first character.

It actually looks like there might be a parameter for this we can use? https://github.com/alphagov/accessible-autocomplete?tab=readme-ov-file#minlength-default-0

DafyddLlyr · 2025-07-29T13:25:29Z

src/components/geocode-autocomplete/index.ts

+type ArrowStyleEnum = "default" | "light";
+type LabelStyleEnum = "responsive" | "static";
+
+// debounce function


nit: Slightly redundant comment?

DafyddLlyr · 2025-07-29T13:27:01Z

src/components/geocode-autocomplete/index.ts

+import styles from "./styles.scss?inline";
+import { getServiceURL } from "../../lib/ordnanceSurvey";
+
+// https://apidocs.os.uk/docs/os-places-lpi-output


This link doesn't work for me - I just get redirected to their docs homepage.

Should it be https://docs.os.uk/os-apis/accessing-os-apis/os-places-api/technical-specification/find?

DafyddLlyr · 2025-07-29T13:34:13Z

src/components/geocode-autocomplete/index.ts

+type Address = {
+  LPI: any;
+};


Where possible, I'd recommend avoiding the use of any.

A few options -

Type out the whole object (using something like https://transform.tools/json-to-typescript to copy the response object from the OS docs)

Not actually a great solution as it's potentially brittle if they change their API, and adds a lot of boilerplate here for us to maintain without that much benefit

Using unknown

Much better than any - means we can code defensively

Sketching out just the shape we care about, so that we at least get type safety within this library (e.g. LPI.ADDRESS on line 108`)

I'd probably go for the third option here 👍

jmcbroom · 2025-08-04T13:32:01Z

hey @DafyddLlyr, thanks for your comments and the helpful example search -- I did choose to dedupe based on UPRN as the Find endpoint returns some duplicate addresses, example here:

{
  "LPI" : {
    "UPRN" : "49051071",
    "ADDRESS" : "1, RHYD-Y-BONT, PENPARCAU, ABERYSTWYTH, CEREDIGION, SY23 1SR",
    "USRN" : "47100668",
    "LPI_KEY" : "6820L000055750",
    "PAO_START_NUMBER" : "1",
    "STREET_DESCRIPTION" : "RHYD-Y-BONT",
    "LOCALITY_NAME" : "PENPARCAU",
    "TOWN_NAME" : "ABERYSTWYTH",
    "ADMINISTRATIVE_AREA" : "CEREDIGION",
    "POSTCODE_LOCATOR" : "SY23 1SR",
    "RPC" : "1",
    "X_COORDINATE" : 259166.13,
    "Y_COORDINATE" : 280339.26,
    "STATUS" : "APPROVED",
    "LOGICAL_STATUS_CODE" : "1",
    "CLASSIFICATION_CODE" : "RD03",
    "CLASSIFICATION_CODE_DESCRIPTION" : "Semi-Detached",
    "LOCAL_CUSTODIAN_CODE" : 6820,
    "LOCAL_CUSTODIAN_CODE_DESCRIPTION" : "CEREDIGION",
    "COUNTRY_CODE" : "W",
    "COUNTRY_CODE_DESCRIPTION" : "This record is within Wales",
    "POSTAL_ADDRESS_CODE" : "D",
    "POSTAL_ADDRESS_CODE_DESCRIPTION" : "A record which is linked to PAF",
    "BLPU_STATE_CODE" : "2",
    "BLPU_STATE_CODE_DESCRIPTION" : "In use",
    "TOPOGRAPHY_LAYER_TOID" : "osgb1000020602516",
    "WARD_CODE" : "W05001301",
    "PARISH_CODE" : "W04000359",
    "LAST_UPDATE_DATE" : "10/02/2016",
    "ENTRY_DATE" : "24/11/2006",
    "BLPU_STATE_DATE" : "06/10/2011",
    "STREET_STATE_CODE" : "2",
    "STREET_STATE_CODE_DESCRIPTION" : "Open",
    "LPI_LOGICAL_STATUS_CODE" : "1",
    "LPI_LOGICAL_STATUS_CODE_DESCRIPTION" : "APPROVED",
    "LANGUAGE" : "CY",
    "MATCH" : 1.0,
    "MATCH_DESCRIPTION" : "EXACT"
  }
}
{
  "LPI" : {
    "UPRN" : "49051071",
    "ADDRESS" : "1, RHYD-Y-BONT, PENPARCAU, ABERYSTWYTH, CEREDIGION, SY23 1SR",
    "USRN" : "47100668",
    "LPI_KEY" : "6820L000027970",
    "PAO_START_NUMBER" : "1",
    "STREET_DESCRIPTION" : "RHYD-Y-BONT",
    "LOCALITY_NAME" : "PENPARCAU",
    "TOWN_NAME" : "ABERYSTWYTH",
    "ADMINISTRATIVE_AREA" : "CEREDIGION",
    "POSTCODE_LOCATOR" : "SY23 1SR",
    "RPC" : "1",
    "X_COORDINATE" : 259166.13,
    "Y_COORDINATE" : 280339.26,
    "STATUS" : "APPROVED",
    "LOGICAL_STATUS_CODE" : "1",
    "CLASSIFICATION_CODE" : "RD03",
    "CLASSIFICATION_CODE_DESCRIPTION" : "Semi-Detached",
    "LOCAL_CUSTODIAN_CODE" : 6820,
    "LOCAL_CUSTODIAN_CODE_DESCRIPTION" : "CEREDIGION",
    "COUNTRY_CODE" : "W",
    "COUNTRY_CODE_DESCRIPTION" : "This record is within Wales",
    "POSTAL_ADDRESS_CODE" : "D",
    "POSTAL_ADDRESS_CODE_DESCRIPTION" : "A record which is linked to PAF",
    "BLPU_STATE_CODE" : "2",
    "BLPU_STATE_CODE_DESCRIPTION" : "In use",
    "TOPOGRAPHY_LAYER_TOID" : "osgb1000020602516",
    "WARD_CODE" : "W05001301",
    "PARISH_CODE" : "W04000359",
    "LAST_UPDATE_DATE" : "10/02/2016",
    "ENTRY_DATE" : "24/11/2006",
    "BLPU_STATE_DATE" : "06/10/2011",
    "STREET_STATE_CODE" : "2",
    "STREET_STATE_CODE_DESCRIPTION" : "Open",
    "LPI_LOGICAL_STATUS_CODE" : "1",
    "LPI_LOGICAL_STATUS_CODE_DESCRIPTION" : "APPROVED",
    "LANGUAGE" : "EN",
    "MATCH" : 1.0,
    "MATCH_DESCRIPTION" : "EXACT"
  }
}

as far as I can tell the main difference is the USRN and LPI_KEY (which I'd guess is because of the USRN difference?). I assume this deduping is OK since it's not happening in the address-autocomplete component.. but not 100% sure.

DafyddLlyr · 2025-08-04T16:11:52Z

@jmcbroom This is a fun UK one to welcome you to the team 😂 The OS Places API is returning both English and Welsh results 🏴󠁧󠁢󠁷󠁬󠁳󠁿 🏴󠁧󠁢󠁥󠁮󠁧󠁿

{
  "LPI" : {
    ...
    "LANGUAGE" : "CY",
  }
}
{
  "LPI" : {
    ...
    "LANGUAGE" : "EN",
  }
}

It's not actually obvious in this instance as this is an all Welsh address example I've unwittingly provided sorry - if you try a Cardiff postcode you'll probably spot a difference in Cardiff / Caerdydd in the address line for example.

As PlanX is currently England only we can safely just set the lr param to EN (default is "EN, CY") (docs).

jmcbroom · 2025-08-06T03:13:40Z

thanks for catching that!

also note: I kept the max_results fetched at 100, in order to most closely match the address-autocomplete search results for the example postcode (SY23 1SR).

DafyddLlyr

Looking great @jmcbroom - thanks for resolving all this 👍

Next steps would be to merge this and then publish a new version of the repo so that we can integrate this into LPS.

jmcbroom added 2 commits July 16, 2025 08:18

add /places/v1/find to url constructor lib

293fedd

render new component that doesn't do anything yet

85b6b15

jmcbroom added 7 commits July 16, 2025 10:53

make the component actually do something :)

89e0d3e

turn onConfirm back on..

ab26095

dont expose API key

b053b23

add testing

29ddaa5

add docs

1d0cd39

add debounce

f475124

label tweak

4a7561b

jmcbroom marked this pull request as ready for review July 21, 2025 09:22

jmcbroom added 2 commits July 21, 2025 12:25

bump timeout for map OSRaster test

fc1192c

add to README, update OS API links

5a7b5b1

jmcbroom requested review from DafyddLlyr and jessicamcinchak July 22, 2025 11:26

jessicamcinchak reviewed Jul 22, 2025

View reviewed changes

jmcbroom added 3 commits July 28, 2025 09:33

add event listener

62d9aa6

fix copy-paste err

fcaca83

include admin area in address display

592254e

DafyddLlyr reviewed Jul 29, 2025

View reviewed changes

jmcbroom added 6 commits August 4, 2025 08:14

update css version

c7632e7

don't require osApiKey

5129b1f

remove commented css import

c396eaf

use minLength

c57230d

add better Address type

5b2f82d

dedupe and sort full results; add isLoading state

5c0c15b

use "EN" for language parameter

d58ba61

DafyddLlyr approved these changes Aug 7, 2025

View reviewed changes

jmcbroom merged commit 744042c into main Aug 8, 2025
5 checks passed

jmcbroom deleted the jimmy/geocode-autocomplete branch August 8, 2025 12:11

		@@ -0,0 +1,63 @@
		@import "govuk-frontend/dist/govuk/index";
		// @import "accessible-autocomplete";

feat: add geocode-autocomplete for free-text address lookup #562

feat: add geocode-autocomplete for free-text address lookup #562

Uh oh!

Conversation

jmcbroom commented Jul 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

netlify bot commented Jul 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for oslmap ready!

Uh oh!

jessicamcinchak left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jmcbroom commented Jul 28, 2025

Uh oh!

DafyddLlyr left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jmcbroom commented Aug 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

DafyddLlyr commented Aug 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jmcbroom commented Aug 6, 2025

Uh oh!

DafyddLlyr left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

feat: add `geocode-autocomplete` for free-text address lookup #562

feat: add `geocode-autocomplete` for free-text address lookup #562

jmcbroom commented Jul 16, 2025 •

edited

Loading

netlify bot commented Jul 16, 2025 •

edited

Loading

jmcbroom commented Aug 4, 2025 •

edited

Loading

DafyddLlyr commented Aug 4, 2025 •

edited

Loading