Frågor · Adresser

Hur lägger jag till autokomplettering av adresser i mitt formulär?

Vad den som fyller i ser

I ett land med register i drift skriver användaren början på gatunamnet och ser de gator som finns, med orterna där gatan finns; är orten redan ifylld smalnar förslagen av till den. När gatan är vald skriver användaren husnumret och formuläret säger om det finns: postnumret som kommer är det som hör till just det numret, inte en gissning ur ortnamnet.

Vid valet fylls fälten gata, husnummer, postnummer och ort i med posten som motorn kontrollerat, samma som vid adresskontrollen. Registret föds rent i stället för att städas efteråt.

För en svensk adress ser användaren i dag inga förslag: hen skriver adressen som vanligt, och svaret från endpointen säger att det inte finns något register i drift för landet och öppnar ingen session. Adressen får sin form i stället i nästa steg, vid sparandet, genom kontaktverifieringen: gatan utskriven, postnumret som ”111 52”, orten med versaler.

Så betalas det

Per session, inte per tangenttryckning. Förslagen medan man skriver är gratis; en bearbetning räknas när användaren väljer adressen och fälten fylls i. Ändrar användaren sedan husnumret och väljer igen i samma session betalas inget nytt. Varje session tillåter upp till trettio anrop och gäller i tio minuter. I ett land utan register i drift, som Sverige i dag, öppnas ingen session och inget dras. Prislistan finns på prissidan.

Så integreras den

Tre delar:

1. En API-token, från ditt konto.
2. En liten proxy på din server, en sida som tar emot anropet från webbläsaren, lägger till token och skickar det vidare till vår endpoint. Den behövs för att token aldrig får ligga i kod som körs i webbläsaren.
3. Widgeten ra-suggerisci.js, utan beroenden: du anger proxyns adress och selektorerna för formulärets fält, och den sköter resten: väntetiden medan man skriver, sammanhanget från de fält som redan är ifyllda och ifyllningen vid valet.

Den som hellre gör det själv anropar endpointen /api/v1/suggest direkt: ett sessions-id som klienten skapar, den skrivna texten, de redan kända fälten som sammanhang; sedan valet med den valda gatan och husnumret. Allt finns i API-dokumentationen och i specifikationen OpenAPI.

Särskilda fall

• Svenska adresser: inga förslag ännu, eftersom det svenska registret inte är i drift. Widgeten stör inte: svaret säger att registret saknas, ingen session öppnas, och användaren fyller i adressen för hand. Sätter du sedan posten genom kontaktverifieringen vid sparandet får adressen sin svenska postform. Sverige följer så snart tillgången till registret är på plats, utan att du behöver ändra något i formuläret.
• Andra länder: förslagen finns i alla länder vars nationella adressregister är i drift (listan); formuläret skickar med landet användaren valt och widgeten söker där, med det landets form för husnummer och postnummer. Användaren kan skriva allt i ett enda fält (”Karl Johans gate 22 Oslo”): svaret säger hur det lästes (parsed: gata, husnummer, postnummer).
• WooCommerce och PrestaShop: inget behöver skrivas, det finns pluginen för WooCommerce och modulen för PrestaShop med autokomplettering i kassan och kontroll av ordrarna.
• En gata som inte dyker upp: användaren kan alltid skriva hela adressen; posten går genom kontrollen i ett senare steg, från en fil eller från API:et.
• Flera formulär, flera webbplatser: samma token tjänar alla formulär; proxyn kan ligga på varje webbplats eller vara gemensam.

Vad som händer med fälten för en svensk adress i dag

Ingen autokomplettering ännu för Sverige: användaren skriver adressen själv, och vid sparandet sätter kontaktverifieringen den i svensk postform: gatan utskriven, postnumret med mellanslag, orten med versaler. Gatans existens är inte kontrollerad, och resultatet säger det. I länderna med register i drift föreslås gata och husnummer redan medan användaren skriver.