Nopea vasteaika – miksi se on kriittistä?​

Osoitetietojen automaattinen täydennys on monissa nykyaikaisissa verkkopalveluissa käytössä. Käyttäjä syöttää osoitteen alun, ja osoite, postinumero, sekä postitoimipaikka, täydentyvätl lomakkeelle automaattisesti. Osoitetietojen automaattinen täydennys parantaa loppukäyttäjän käyttökokemusta. Samalla myös datan laatu parantuu, koska loppukäyttäjät eivät voi antaa virheellisiä tietoja yhtä helposti. Sallittuihin osoitteisiin voidaan jopa tehdä rajoituksia, verkkokaupan kuljetukset voidaan esimerkiksi hyväksyä vain osoitteisiin, joissa on käytössä olevia asuinrakennuksia.

Toiminnallisuuden suurin riski on kuitenkin hitaus: jos käyttäjä joutuu odottamaan tietojen latautumista, kokemus heikkenee välittömästi. Palvelu pitää myös suunnitella niin, että liiketoimintaprosessi ei keskeydy, vaikka yhteys tietolähteeseen olisi katkennut. Lisäksi käyttöliittymän ja rajapinnan väliset verkkokutsut lisäävät aina pienen viiveen kokonaisvasteaikaan.

Suunnittelumme lähtökohtana toiminut näiden asioiden huomioon ottaminen: rajapinnan itsensä on oltava niin nopea, ettei se muodostu pullonkaulaksi. Lisäksi palvelu pitää suunnitella erittäin vikasietoisesti, jotta vikatilanteiden syyt rajautuvat enää yhteyksiin.

Lopputulos on varsin onnistunut. Rajapinta itsessään vastaa osoitekyselyihin alle 20 millisekunnissa, eikä käyttäjä oikeastaan edes huomaa viivettä kyselyjen välillä. Vertailukohtana voidaan todeta, että ihmisen reaktioaika lienee parhaimmillaankin 100 millisekunnin luokkaa. Lisäksi rajapinta on toteutettu osana uutta Kontakto 2.0 -rajapintaa, joka on ollut keskeytyksettä käytettävissä julkaisustaan lähtien. Suunnittelussa on minimoitu ulkoiset riippuvuudet, jotta muiden palveluiden yhteysvirheet eivät vaikuta palvelun käytettävyyteen.

Tiedot SYKE:n aineistoista​

Osoitepalvelun:n tiedot perustuvat Suomen ympäristökeskuksen (SYKE) ylläpitämään valtakunnalliseen rakennus- ja osoiterekisteriin. Hyödynnämme siis SYKE:n avoimia paikkatietoaineistoja.

Aineisto sisältää muun muassa:

• Suomalaiset osoitteet: Osoitteet sekä suomen- että ruotsinkielisenä.
• Rekisteröidyt rakennukset: Tiedot rakennuksista, kuten käyttötarkoitus, pinta-ala ja tekniset ominaisuudet.
• Sijaintitiedot: Maantieteelliset koordinaatit karttasovelluksia ja sijaintipalveluita varten.
• Kunta- ja postinumerotiedot: Kuntakoodi, postinumero ja postitoimipaikka.
• Yksityiskohtaiset rakennusominaisuudet: Kerrosten lukumäärä, lämmitystapa, asuntojen määrä ja paljon muuta.

Palvelu hakee osoitteet suoraan SYKE:n aineistosta sisäiseen tietokantaan. Tietokanta päivitetään kerran päivässä. Näin pystymme tarjoamaan tiedot, vaikka esimerkiksi yhteys SYKE:hen olisi katkennut. Tiedot ovat tallenettu erittäin nopeaan dokumenttietokantaan, joka on optimoitu nimeonomaan nopeaan vastaavaan käyttötarkoitukseen.

Rajapinnat​

Osoitepalvelulla on kolme rajapintaa.

• Haku: Palauttaa listan parhaiten hakusanaa vastaavista osoitteista. Osoitteista palautetaan vain olennaisimmat tiedot, kuten osoite ja postinumero. Sopii hyvin ennustavaan hakuun.
• Yksittäinen osoite: Palauttaa yhden osoitteen tiedot. Sisältää osoitteessa olevat rakennukset, ja niihin liittyvät tiedot.
• Tarkennettu haku: Palauttaa listan hakukriteerien perusteella. Mahdollistaa haun rajaamisen esimerkiksi rakennuksien käyttötarkoituksen perusteella. Lisäksi vastauksen palauttamat tiedot voi määritellä sopiviksi.

Alla esimerkkivastaus yksittäisen osoitteen tiedoista. Osa kentistä on poistettu, mutta dokumentaatiosta lyötyy kokonaiset esimerkit:

{
  "id": "b75f82f3-4075-461a-b033-aa35724a3155",
  "addressFin": "Mannerheimintie 1",
  "addressSwe": "Mannerheimvägen 1",
  "addressNameFin": "Mannerheimintie",
  "addressNameSwe": "Mannerheimvägen",
  "numberPartOfAddressNumber": 1,
  "postalCode": "00100",
  "postalOfficeFin": "Helsinki",
  "postalOfficeSwe": "Helsingfors",
  "domicileCode": "091",
  "country": "FI",
  "coordinates": {
    "longitude": 24.945831,
    "latitude": 60.169856
  },
  "buildings": [
    {
      "id": "building-123",
      "completionDate": "1920-01-01",
      "mainPurpose": {
        "descriptionFi": "Asuinrakennus",
      },
      "facadeMaterial": {
        "id": "01",
        "descriptionFi": "Betoni",
      },
      "heatingMethod": {
        "id": "01",
        "descriptionFi": "Vesikeskuslämmitys",
      },
      "numberOfStoreys": 6,
      "apartmentCount": 12,
      "grossFloorArea": 1200.5
    }
  ]
}

Palvelun hyödyt​

• Suorituskyky: Rajapinta on optimoitu reaaliaikaiseen käyttöön. Nopea vasteaika tekee siitä ihanteellisen työkalun käyttöliittymien automaattiseen täydennykseen ja osoitteiden validointiin.
• Helppokäyttöisyys: Tarjoamme selkeän REST-rajapinnan ja kattavan dokumentaation, mikä tekee integroinnista nopeaa ja vaivatonta.
• Kattavuus: Osoitepalvelu on osa laajempaa Kontakto-alustaa. Saman integraation kautta saat käyttöösi myös kattavat yritystiedot ja muut tietolähteemme.

Käyttöönotto itsepalveluna​

Osoitepalvelu on osa Kontakto API:n maksullista palvelua. Saat palvelun käyttöösi heti rekisteröitymällä Kontakto-palveluun ja luomalla rajapinta -avaimen.

Tarkemmat tiedot integraatiota varten löydät dokumentaatiostamme.

Vanha rajapintaversio toimii uuden rinnalla toistaiseksi, jotta kaikilla käyttäjillä on riittävästi aikaa siirtyä uuteen versioon.

Uutta kohti​

Tavoitteenamme Kontaktolla on aina ollut parantaa kansallisesti yritystietojen saatavuutta ja laatua. Uuden v2.0-rajapinnan kehitys aloitettiin alkuvuodesta 2025, koska halusimme tarjota asiakkaillemme entistä laajemmat tietosisällöt nopeudesta ja luotettavuudesta tinkimättä. Vaikka vuonna 2020 julkaistu alkuperäinen rajapintamme on palvellut luotettavasti miljoonia kyselyitä ja saavuttanut 99,99 %:n käytettävyyden, uusien tietolähteiden lisääminen siihen oli haastavaa.

Uudistunut rajapinta ja uudet ominaisuudet​

Uusi v2.0-rajapinta on rakennettu kokonaan uudelle perustalle, mikä mahdollistaa tulevaisuudessa entistä nopeamman kehityksen ja uusien ominaisuuksien lisäämisen. Tämä julkaisu tuo mukanaan useita merkittäviä parannuksia mm. seuraavat ominaisuudet:

• Domainrekisteritiedot
• Laajennettu haku
• Postinumerot

Parannettu kehittäjäkokemus ja tulevaisuuden näkymät​

Uuden rajapinnan julkaisun myötä olemme panostaneet myös kehittäjäkokemuksen parantamiseen. Olemme julkaisseet täysin uuden ja kattavan dokumentaation osoitteessa https://docs.kontakto.fi/api, joka tekee uuden rajapinnan käyttöönotosta entistä helpompaa. Lisäksi API-avainten hallinnointi on nyt mahdollista suoraan kontakto.fi-palvelun kautta.

Nyt kun v2.0 on julkaistu, työ uusien tietolähteiden ja toiminnallisuuksien parissa jatkuu. Tulemme lähiaikoina lisäämään rajapintaan uusia tietolähteitä. Aloitamme myös muiden kehitystä tukevien toimintojen, kuten SDK-kehityspakettien (Software Development Kit), kehittämisen, jotka helpottavat Kontakton tietojen integroimista muihin sovelluksiin.