Uusi osoitepalvelu tarjoaa kaikki suomalaiset osoitteet ja rakennukset yhdestä rajapinnasta

Uusi osoitteiden hakupalvelu mahdollistaa valtakunnallisesti kattavien osoite- ja rakennustietojen liittämisen osaksi digitaalisia palveluita. Osoitehaun avulla voidaan parantaa käyttökokemusta esimerkiksi verkkokaupan kassalla, tai rekisteröitymislomakkeissa, joissa kysytään asiakkaan osoitetietoja. Rajapinta on suunniteltu nykypäivän sovellusten tarpeisiin ja palauttaa vastaukset tyypillisesti niin nopeasti, että käyttäjä ei edes huomaa viivettä kyselyjen välillä.

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.