Kysymykset · Osoitteet

Miten lisään osoitteiden automaattitäydennyksen lomakkeeseeni?

Mitä lomakkeen täyttäjä näkee

Hän kirjoittaa ”aleksis kiven” ja näkee ”Aleksis Kiven katu” niiden postitoimipaikkojen kanssa, joissa se katu on; jos hän on jo täyttänyt kaupungin, ehdotukset rajautuvat siihen. Kun katu on valittu, hän kirjoittaa talonumeron, ja lomake kertoo, onko se olemassa: Suomessa postinumero riippuu kadusta ja usein kadun osuudesta, ja saapuva postinumero on juuri sen numeron postinumero, ei kaupungin yleinen.

Valinnassa osoite-, postinumero- ja postitoimipaikkakentät täyttyvät moottorin käsittelemällä tietueella, samalla kuin osoitteen tarkistuksessa. Rekisteri syntyy puhtaana sen sijaan, että se siivottaisiin jälkikäteen.

Miten se veloitetaan

Istunnoittain, ei näppäinpainalluksittain. Ehdotuspyynnöt kirjoittamisen aikana ovat ilmaisia; yksi käsittely lasketaan vasta, kun käyttäjä valitsee osoitteen ja kentät täyttyvät. Jos hän sen jälkeen vaihtaa talonumeroa ja valitsee uudelleen samassa istunnossa, uutta veloitusta ei tule. Jokainen istunto sallii enintään kolmekymmentä pyyntöä ja on voimassa kymmenen minuuttia. Hinnasto on hintasivulla.

Miten se integroidaan

Kolme osaa:

1. API-tunnus omalta tililtäsi.
2. Pieni välityspalvelin omalla palvelimellasi: sivu, joka ottaa pyynnön vastaan selaimelta, lisää tunnuksen ja välittää pyynnön meidän päätepisteeseemme. Se tarvitaan, koska tunnus ei saa koskaan olla selaimessa suoritettavassa koodissa.
3. Widget ra-suggerisci.js, ilman riippuvuuksia: annat sille välityspalvelimen osoitteen ja lomakekenttien valitsimet, ja se hoitaa loput: odotuksen kirjoittamisen aikana, jo täytettyjen kenttien käytön hakuehtona ja kenttien täyttämisen valinnasta.

Se, joka haluaa tehdä itse, kutsuu suoraan päätepistettä /api/v1/suggest: asiakasohjelman luoma istuntotunniste, kirjoitettu teksti, jo tiedossa olevat kentät hakuehtona; sitten valintatoiminto valitun kadun ja talonumeron kanssa. Kaikki on API-dokumentaatiossa ja OpenAPI-määrittelyssä.

Erityistapaukset

• Kaksikieliset kunnat: kadun voi kirjoittaa suomeksi tai ruotsiksi, ja ehdotus tulee rekisterin muodossa.
• Muut maat: ehdotuksia on jokaisessa maassa, jonka osoiterekisteri on käytössä (luettelo); lomake välittää käyttäjän valitseman maan, ja widget hakee sieltä, sen maan talonumeron ja postinumeron muodossa. Käyttäjä voi kirjoittaa kaiken yhteen kenttään (”Kalverstraat 92 Amsterdam”): vastaus kertoo, miten se luettiin (parsed: katu, talonumero, postinumero). Maassa, jolla ei ole rekisteriä, vastaus sanoo sen eikä avaa istuntoa: täyttäminen jatkuu käsin, ilman veloitusta.
• WooCommerce ja PrestaShop: mitään ei tarvitse kirjoittaa, sillä WooCommerce-lisäosa ja PrestaShop-moduuli tuovat automaattitäydennyksen kassalle ja tilausten tarkistuksen.
• Katu, joka ei tule näkyviin: käyttäjä voi aina kirjoittaa osoitteen kokonaan; tietue käy tarkistuksen läpi myöhemmin, tiedostosta tai API:sta.
• Useita lomakkeita, useita sivustoja: sama tunnus palvelee kaikkia lomakkeita; välityspalvelin voi olla jokaisella sivustolla tai yhteinen.

Mitä kentille tapahtuu

Katu täydennetään rekisterin kirjoitusasuun, postitoimipaikka valitaan niistä, joissa se katu on, ja postinumeron asettaa moottori: Helsingissä se on kadun osuuden postinumero, joka tulee talonumeron mukana.