Tekninen kuvaus Kiinteistökauppojen kyselypalvelu (OGC API Features) BETA

Aineisto

Kiinteistöjen kauppahintarekisteriin tallennetut tiedot siirretään tietopalveluun maanantaista lauantaihin aamuyöllä (normaalitilanteessa ennen klo. 5) ja onnistuneen siirron päätteeksi asetetaan kuluva päivä rekisteritilannepäivämääräksi. BETA-palvelussa tiedot siirtyvät Kauppahintarekisterin testitietokannasta.

Rekisteritilannepäivämäärä löytyy palvelun tuotteilta, jolloin se esitetään .json-formaatissa meta-osiossa: 

• rekisteritilannepvm
  • Kauppahintarekisterin tietopalvelun ajantasapäivämäärä. Kuvaa, minkä päivän tasalla tietopalvelussa esitetyt tiedot ovat

 Rekisteritilannepvm:n  pystyy myös kysymään maksuttomasti erillisellä metadata-kyselyllä 

Esimerkki metadata-kyselystä tehtynä tuotteelle KiinteistonluovutuksenTunnistetiedot. (Riittää, että kysyy tiedon yhdeltä tuotteelta, koska rekisteritilannepvm on sama kaikille tuotteille):

https://[PALVELUOSOITE]collections/KiinteistonluovutuksenTunnistetiedot/metadata

Tuotteet

Tuotteiden kuvaukset löytyvät alla olevasta taulukosta. Tietosisältö on kuvattu UML-kaavioina ja sanallisissa kuvauksissa (.pdf). Niiden tarkoitus on antaa yleiskuva tuotteiden tietosisällöstä. Ne eivät kuvaa tuotteiden teknistä rakennetta, eikä niistä siis voi päätellä .json -vastauksen rakenteellista muotoa. Tuotteiden skeemat kuvaavat niiden teknisen rakenteen. Kunkin tuotteen skeema on kysyttävissä palvelusta. Esimerkiksi tuotteen  KiinteistonluovutuksenLaajatTiedotIlmanHenkilotietoja-skeema kysytään seuraavasti: https://[PALVELUOSOITE]collections/KiinteistonluovutuksenLaajatTiedotIlmanHenkilotietoja/schema 

Tuotteista löytyy  lisäksi esimerkit .json-formaatissa otsikon Rajapinnan kyselypalvelutuotteet alta (esimerkit kysytään palvelusta).

Rajapinnan kyselypalvelutuotteet

Palvelu tukee kahdenlaista tietojen kyselytapaa: kyselypalvelukäyttöä ja asynkronisia rajapintakyselyitä. 

Kyselypalvelukäyttö

Kyselypalvelukäytössä palvelua käytetään OGC API Features-standardin mukaisesti (https://ogcapi.ogc.org/features/). Käytössä on tällöin monipuoliset kyselymahdollisuudet Kauppahintarekisterin tietoihin (ajantasakyselyt) ja asiakkaalle kuuluvan tuotekokonaisuuden kaikki tuotteet. Isojen aineistojen latausta (esim. alkulataus koko Suomesta) ei kuitenkaan tueta. 

Yhtenä hakuehtona on tarjolla muuttuneiden kohteiden kysely (uudet ja muuttuneet kohteet annetusta rekisteritilannepäivämäärästä lähtien kyselyhetken rekisteritilannepäivämäärään saakka). Palvelusta voi myös kysyä pelkästään uusia kiinteistönluovutuksia aikaväliltä. Eheän rekisterikopion ylläpitäminen edellyttää kuitenkin sekä uusien että muuttuneiden ottamista ja eheää lähtötilannetta, jonka päälle muutoksia ladataan. Yksilöivänä tunnisteena käytetään kiinteistönluovutustunnusta.

On hyvä huomioida, että tuotetta "Kiinteistönluovutuksen tunnistetiedot" laskutetaan  tuotannollisessa käytössä hinta/kysely ja kaikkia muita tuotteita laskutetaan hinta/tuote (=hinta/palautunut kohde).

Kyselypalvelukäytössä voi etukäteen selvittää, kuinka monta kohdetta sen rajausehtoihin kaiken kaikkiaan osuu (OGC-NumberMatched) ja kuinka monta kohdetta palvelu ensimmäisen kyselyn osajoukkona palauttaisi (OGC-NumberReturned).

Kohteiden määrän kysyminen on maksutonta. Kohteiden määrän kysymisen esimerkki löytyy  jäljempänä otsikon "OGC API Features palvelun käyttäminen" alta.

Esimerkkejä mahdollisista hakutavoista

Kiinteistönluovutuksen sijainti on tallennettu pisteenä. Kiinteistönluovutuksia voi hakea  mm. bbox-kyselyillä (suorakaiderajaus). 

Lisäksi on käytössä OGC API - Features - Part 3 luonnoksen mukaiset monipuoliset sijaintihakumahdollisuudet.

Käytössä on mm. seuraavat  Part 3 mukaiset sijaintirajaukset:

• piste ja annettu säde (point with radius)
• viiva bufferoituna (line string with buffer (distance from line))
• vapaa aluerajaus (polygon)
• vapaa aluerajaus bufferoituna (polygon with buffer (distrance from outer ring of polygon)

Kyselyssä voi käyttää myös rajaamista ominaisuustiedoilla. Käytössä on monipuoliset hakuehdot. Esimerkkejä käytössä olevista hakumahdollisuuksista:

• kuntatunnus tai kunnan nimi (kiinteistönluovutushetken)
• luovutetun kohteen kiinteistötunnus
• luovutetun kohteen määräalatunnus
• kiinteistönluovutustunnus
• kauppahinta, kiinteistönluovutuksen päivämäärää, kiinteistönluovutuksen käyttötarkoituslaji (esim. lomarakennuspaikka), rajoittuminen rantaan, pinta-alatiedot jne. 

Kyselyparametrit ovat samat kaikille niille tuotteilla, jotka tuotekokonaisuudella on käytössään. 

Kyselyparametreja voi vapaasti yhdistellä.

Käytettäessä pinta-aloihin liittyvää kyselyparametria (esim. maapintaalaYhteensa, metsamaanPintaala jne), niin alarajalle ei kannata asettaa arvoa 0. (muuten ei hae kaikkia kohteita, koska osalla pinta-aloista ei ole arvoa ollenkaan)

Lisäksi tuotteiden hakuesimerkkejä eri käyttötapauksiin sovitettuna löytyy alasvetovalikosta Esimerkkejä. 

Asynkroniset rajapintakyselyt

Asynkroniset rajapintakyselyt on tarkoitettu käytettäväksi silloin, kun palvelusta halutaan irrottaa suuri määrä aineistoa esim. alkulataus koko Suomesta (koko rekisterin tietosisältö). Tätä kautta voi myös pyytää muuttuneet kohteet  (uudet ja muuttuneet kohteet annetusta rekisteritilannepäivämäärästä lähtien kyselyhetken rekisteritilannepäivämäärään saakka) eli ylläpitää eheää rekisterikopiota (tai rekisterin osan kopiota) alkulatauksen jälkeen tai mikäli pohjalla on jo valmiiksi ehjä rekisteritilanne, niin ruveta lataamaan uusia ja muuttuneita sen päälle. Yksilöivänä tunnisteena käytetään kiinteistönluovutustunnusta.

Asiakassovelluksen tekemä asynkroninen tietojen irrotuspyyntö (execution) käynnistää eräajotyön, jonka tilaa (status) voi seurata vastauksena saatavan linkin kautta. Kun eräajotyö on onnistuneesti valmistunut ("status" : "successful"), niin eräajotyön tilan kertova vastaus sisältää myös linkin results-kyselyyn, jonka avulla käyttäjä saa json-muotoisessa tiedostossa linkit ladattaviin tulostiedostoihin. Tiedostolinkit sisältävä json-tiedosto on otettava talteen, mikäli asiakassovellus haluaa noutaa syntyneet tulostiedostot vasta myöhemmin. 

On huomioitava, että eräajotyön eri vaiheissa palauttamiin linkkeihin tulee lisätä alkuun tuotekokonaisuuden käyttämä palveluosoite.

Tulostiedostoja säilytetään 30 vrk, mutta tiedot ovat irrotushetken rekisteritilanteen mukaiset. Kts. rekisteritilannepäivämäärästä tarkemmin  alasvetovalikosta Aineistot ja tuotteet.  

Toiminta poikkeaa kyselypalvelukäytöstä myös seuraavin osin:

• ei voi kysellä kohteiden määrää etukäteen
• ei voi rajata limit-parametrilla kohteiden määrää
• kaikki kyselyn kohteet palautuvat aina vastauksena oleviin tulostiedostoihin  (ei ole käytössä maksimi limit arvoa)
• tulostiedostot eivät sisällä next linkkejä, eikä streamausmahdollisuutta (paging)

Asiakassovellus saa listattua palvelun käytössä olevat eräajoirrotusprosessit seuraavalla käskyllä (GET /collections/<collectionId>/processes). Esimerkiksi:

https://[PALVELUOSOITE]KiinteistonluovutuksenLaajatTiedotIlmanHenkilotietoja/processes

Esimerkki processes-pyynnön vastauksesta:

Seuraavassa kuvataan esimerkki asynkronisen rajapintakyselyn käytöstä. Esimerkissä irrotetaan yhdestä kunnasta (kuntatunnus=143) kaikki kiinteistönluovutukset (kiinteistönluovutukset ovat BETA-palvelussa testidataa). Vastaus halutaan koordinaatistoon ETRS-TM35FIN (EPSG:3067).

Esimerkissä käytetty tuotekokonaisuus on: "Kyselypalvelu ilman henkilötietoja", jolla laajimman tietosisällön omaava tuote on KiinteistonluovutuksenLaajatTiedotIlmanHenkilotietoja.

1. Asiakassovellus tekee tietojen irrotuspyynnön eli käynnistää halutun eräajoirrotusprosessin  execution-kyselyllä haluamillaan kyselyparametreilla (esimerkissä: kuntatunnus=143) (GET /collections/<collectionId>/processes/<processId>/execution?<parameters>)

   Kyselyparametreina voi käyttää Open API-kuvauksessa kuvattuja parametreja.

   Esimerkiksi:

   https://[PALVELUOSOITE]collections/KiinteistonluovutuksenLaajatTiedotIlmanHenkilotietoja/processes/items/execution?kuntatunnus=143&crs=http://www.opengis.net/def/crs/EPSG/0/3067

    Execution-kyselyn jälkeen rajapinta palauttaa linkin prosessin käynnistämään uniikkiin eräajotyöhön. 

   Esimerkki execution-kyselyn vastauksesta:

   {
    "links" : [ {
      "href" : "collections/KiinteistonluovutuksenLaajatTiedotIlmanHenkilotietoja/jobs/446f9895-9a61-45da-ab3b-9294b800c861",
      "rel" : "job",
      "type" : "application/json"
    } ]
   }

    

2. Asiakassovellus voi seurata eräajotyön etenemistä eräajotyön uniikista linkistä (GET /collections/<collectionId>/jobs/<jobId>), eli esimerkkitapauksessa linkistä:

   https://[PALVELUOSOITE]collections/KiinteistonluovutuksenLaajatTiedotIlmanHenkilotietoja/jobs/446f9895-9a61-45da-ab3b-9294b800c861

   Kyselyn vastauksena saadaan eräajotyön status. Onnistuneen eräajotyön status on "successful". Onnistuneesta eräajotyöstä palautetaan myös linkki results-kyselyyn, jonka avulla asiakassovellus saa linkit ladattaviin tiedostoihin.

   Esimerkki onnistuneesti tehdyn eräajotyön vastauksesta:

   {

   "type" : "process",

    "jobID" : "446f9895-9a61-45da-ab3b-9294b800c861",

    "status" : "successful",

    "created" : "2026-02-13T15:04:08.704406329Z",

    "started" : "2026-02-13T15:04:08.707631719Z",

    "finished" : "2026-02-13T15:04:27.557029095Z",

    "updated" : "2026-02-13T15:04:27.557069241Z",

    "progress" : 0,

    "links" : [ {

      "href" : "collections/KiinteistonluovutuksenLaajatTiedotIlmanHenkilotietoja/jobs/446f9895-9a61-45da-ab3b-9294b800c861/results",

      "rel" : "results",

      "type" : "application/json"

    } ]

   }

   Tarvittaessa kaikki eräajotyöt saa listattua käskyllä: GET /collections/<collectionId>/jobs

3. Asiakassovellus tekee results-kyselyn (GET /collections/<collectionId>/jobs/<jobId>/results), eli esimerkissä: 

   https://[PALVELUOSOITE]collections/KiinteistonluovutuksenLaajatTiedotIlmanHenkilotietoja/jobs/446f9895-9a61-45da-ab3b-9294b800c861/results

   Esimerkki results-kyselyn vastauksesta. Vastaus sisältää json-muotoisessa tiedostossa linkit ladattaviin tulostiedostoihin:

   {

     "jobID" : "446f9895-9a61-45da-ab3b-9294b800c861",

     "status" : "successful",

     "progress" : 0,

     "links" : [ {

       "href" : "collections/KiinteistonluovutuksenLaajatTiedotIlmanHenkilotietoja/jobs/446f9895-9a61-45da-ab3b-9294b800c861/results/batches/1.json",

       "rel" : "result",

       "type" : "application/geo+json"

     }, {

       "href" : "collections/KiinteistonluovutuksenLaajatTiedotIlmanHenkilotietoja/jobs/446f9895-9a61-45da-ab3b-9294b800c861/results/batches/2.json",

       "rel" : "result",

       "type" : "application/geo+json"

     }, {

       "href" : "collections/KiinteistonluovutuksenLaajatTiedotIlmanHenkilotietoja/jobs/446f9895-9a61-45da-ab3b-9294b800c861/results/batches/3.json",

       "rel" : "result",

       "type" : "application/geo+json"

     }, {

       "href" : "collections/KiinteistonluovutuksenLaajatTiedotIlmanHenkilotietoja/jobs/446f9895-9a61-45da-ab3b-9294b800c861/results/batches/4.json",

       "rel" : "result",

       "type" : "application/geo+json"

     }, {

       "href" : "collections/KiinteistonluovutuksenLaajatTiedotIlmanHenkilotietoja/jobs/446f9895-9a61-45da-ab3b-9294b800c861/results/batches/5.json",

       "rel" : "result",

       "type" : "application/geo+json"

     } ]

   }

Lisää asynkronisten rajapintakyselyiden esimerkkejä eri käyttötapauksiin sovitettuna löytyy alasvetovalikosta Esimerkkejä. Asynkronisia rajapintakyselyitä käytetään erityisesti eheän rekisterikopion tai sen osan ylläpitämisessä. 

OGC API Features palvelun käyttäminen

Tässä on lyhyt ohje kuinka käyttää OGC API Features rajapintapalvelua, esimerkkitapauksissa on käytetty tuotteita KiinteistonluovutuksenTunnistetiedot ja KiinteistonluovutuksenLaajatTiedotIlmanHenkilotietoja. Open API kuvauksessa on listattu eri tuotteille mahdolliset palvelupyynnöt ja niiden hakuparametrit.

Kunkin tuotekokonaisuuden palveluosoite on listattu "Tuotekokonaisuudet"-taulukkoon ja siihen viitataan esimerkkitapauksissa seuraavasti: [PALVELUOSOITE]

Lisää tuotteiden hakuesimerkkejä eri käyttötapauksiin sovitettuna löytyy alasvetovalikosta Esimerkkejä. 

Paikkatietokohteen haku tunnisteella

Vastaus on GeoJSON-muotoista: 

https://[PALVELUOSOITE]collections/KiinteistonluovutuksenLaajatTiedotIlmanHenkilotietoja/items/42602656?

Jos asiakas ylläpitää omaa rekisterikopioita tai sen osan kopioita, niin yksilöivänä tunnisteena käytetään kiinteistönluovutustunnusta.

Vastausten sivutus

OGC API Features rajapinnan mukaisesti toteutettuna palvelussa on hyvä tuki kohteiden kokoelmien sivutukselle. Esimerkiksi seuraava kysely palauttaa osajoukon KiinteistonluovutuksenTunnistetiedot- kokoelmasta eli ensimmäiset 100 kohdetta:

https://[PALVELUOSOITE]collections/KiinteistonluovutuksenTunnistetiedot/items?limit=100

Vastauksena tulee siis nuo 100 kohdetta sekä vastauksen lopussa myös kyselylinkki seuraaviin 100 kohteeseen, esim.:

https://[PALVELUOSOITE]collections/KiinteistonluovutuksenTunnistetiedot/items?next=MTAwOg%3D%3D&limit=100

Tämä puolestaan palauttaa kyselylinkin sitä seuraavaan osajoukkoon jne.

Jos kyselyssä ei ole annettu limit-parametrille arvoa, palvelussa käytetään API-kuvauksessa määriteltyä oletusarvoa. Palvelun oletus limit- arvo ei välttämättä pysy vakiona, vaan sitä saatetaan muuttaa myöhemmin.

API-kuvauksessa on myös määritelty maksimi limit-parametrin arvolle.

Asiakassovellus voi pyytää palautumaan yhdessä osajoukossa korkeintaan maksimi limit -arvon mukaisen määrän kohteita. Palvelun maksimi limit -arvo ei välttämättä pysy vakiona, vaan sitä saatetaan muuttaa myöhemmin.

Asiakassovelluksen käytön kannalta on hyvä hakea limit-arvoa, joka on asiakassovelluksen kulloisenkin käyttötapauksen kannalta sopivin.

Kohteiden määrän kysyminen

Kohteiden määrän kysymiseen käytetään HEAD-operaatiota. Palautuvissa tiedoissa on mukana OGC-headerit.

Annetusta kyselystä voi etukäteen selvittää, kuinka monta kohdetta sen rajausehtoihin kaiken kaikkiaan osuu (OGC-NumberMatched) ja kuinka monta kohdetta palvelu ensimmäisen kyselyn osajoukkona palauttaisi (OGC-NumberReturned). 

Esim. Halutaan tietää, kuinka monta kohdetta täyttää seuraavan kyselyn rajausehdot: kysytään KiinteistonluovutuksenTunnistetiedot Espoon (kuntatunnus=049) voimassaolevista (olotila=1) kiinteistönluovutuksista, joiden joku kiinteistönluovutuslajeista on kiinteistökauppa (kiinteistonluovutuslaji=1) ja  joiden ensisijainen käyttötarkoituslaji (kayttotarkoitustiedonEnsisijaisuuslaji=1) on lomarakennuspaikka (kiinteistonluovutuksenKayttotarkoituslaji=703). Tehdään HEAD-kysely:

curl -H "Authorization:Basic [HASH]" -H "X-Road-Client:[CLIENT]" -I "https://[PALVELUOSOITE]collections/KiinteistonluovutuksenTunnistetiedot/items?kuntatunnus=049&olotila=1&kiinteistonluovutuslaji=1&kayttotarkoitustiedonEnsisijaisuuslaji=1&kiinteistonluovutuksenKayttotarkoituslaji=703"

Kysely on maksuton.

Koordinaatistot ja suorakaiderajaukset

Oletuksena bbox-suorakaiderajaus ja vastauksena palautettavien paikkatietokohteiden geometriat sisältävät WGS 84 koordinaatteja (CRS80), esimerkiksi:

https://[PALVELUOSOITE]collections/KiinteistonluovutuksenTunnistetiedot/items?&bbox=22.15,63.45,22.2,63.5

Rajaaminen ETRS-TM35FIN koordinaateilla (EPSG:3067) tehdään bbox-crs parametrin avulla, esimerkiksi:

https://[PALVELUOSOITE]collections/KiinteistonluovutuksenTunnistetiedot/items?bbox=116000,6654000,140000,6666000&bbox-crs=http://www.opengis.net/def/crs/EPSG/0/3067

Edellinen esimerkki palauttaa vastauksen kohteiden geometriat edelleen WGS 84 koordinaatteina. Jos myös vastaus halutaan projisoida toiseen koordinaatistoon, niin tähän voi käyttää crs parametria. Jos halutaan hakea vain voimassaolevia kohteita, liitetään kyselyyn hakuehto olotila=1, kuten tässä:

https://[PALVELUOSOITE]collections/KiinteistonluovutuksenTunnistetiedot/items?olotila=1&bbox=116000,6654000,140000,6666000&bbox-crs=http://www.opengis.net/def/crs/EPSG/0/3067&crs=http://www.opengis.net/def/crs/EPSG/0/3067

Tuettujen koordinaatistojen tunnisteet on lueteltu:

https://[PALVELUOSOITE]collections

Monipuoliset sijaintihaut

Käytettävä sijaintioperaatio ja haluttu sijaintirajaus annetaan filter-parametrissa. 

Oletuksena annettava sijaintirajaus sisältää WGS 84 koordinaatteja (CRS80).

Sijaintirajaus ETRS-TM35FIN koordinaateilla (EPSG:3067)  annetaan filter-crs parametrin avulla.

Ensimmäisessä esimerkissä on käytetty S_INTERSECTS-sijaintioperaatiota ja haetaan voimassaolevia KiinteistonluovutuksenTunnistetiedot-kohteita annetulla vapaalla aluerajauksella (POLYGON). Sijaintirajaus on annettu ETRS-TM35 koordinaatistossa. Myös vastaus halutaan ETRS-TM35 koordinaatistoon.

Vastauksena saadaan ne voimassaolevat KiinteistonluovutuksenTunnistetiedot-kohteet, jotka sijaitsevat vapaan aluerajauksen sisällä tai rajalla. 

https://[PALVELUOSOITE]collections/KiinteistonluovutuksenTunnistetiedot/items?olotila=1&filter=S_INTERSECTS(geometry,POLYGON((573442%206986417,580025%206986572,579888%206992142,573316%206991987,573442%206986417)))&filter-crs=http://www.opengis.net/def/crs/EPSG/0/3067&filter-lang=cql2-text&crs=http://www.opengis.net/def/crs/EPSG/0/3067

Toisessa esimerkissä on käytetty S_INTERSECTS-sijaintioperaatiota ja haetaan voimassaolevia KiinteistonluovutuksenTunnistetiedot-kohteita annetun säteen etäisyydeltä (100 m) annetusta pisteestä (POINT). Sijaintirajaus on annettu ETRS-TM35 koordinaatistossa.  Myös vastaus halutaan ETRS-TM35 koordinaatistoon.

Vastauksena saadaan ne voimassaolevat KiinteistonluovutuksenTunnistetiedot-kohteet, jotka sijaitsevat sen alueen sisällä tai rajalla, joka on 100 m etäisyydellä annetusta pisteestä. 

https://[PALVELUOSOITE]collections/KiinteistonluovutuksenTunnistetiedot/items?olotila=1&filter=S_INTERSECTS(geometry,BUFFER(POINT(533598%206972406),100))&filter-crs=http://www.opengis.net/def/crs/EPSG/0/3067&filter-lang=cql2-text&crs=http://www.opengis.net/def/crs/EPSG/0/3067

Rajaus ominaisuustiedoilla

Tämä esimerkki hakee kiinteistotunnus-parametria käyttäen yhden rekisteriyksikön voimassaolevat kiinteistönluovutukset. Pyydetty tuotetta KiinteistonluovutuksenLaajatTiedotIlmanHenkilotietoja :

https://[PALVELUOSOITE]collections/KiinteistonluovutuksenLaajatTiedotIlmanHenkilotietoja/items?kiinteistotunnus=58140900050039&olotila=1

Useamman rekisteriyksikön voimassaolevat kiinteistönluovutukset voidaan hakea yhdellä kyselyllä listaamalla kiinteistötunnukset pilkulla erotettuna (jolloin arvojen käsittely toimii OR-operaation mukaisesti, tässä esimerkissä siis "58140900050039" tai "62540500630000"). Pyydetty tuotetta KiinteistonluovutuksenLaajatTiedotIlmanHenkilotietoja:

https://[PALVELUOSOITE]collections/KiinteistonluovutuksenLaajatTiedotIlmanHenkilotietoja/items?kiinteistotunnus=58140900050039,62540500630000&olotila=1

Eheän rekisterikopion ylläpitäminen

Alkulatauskysely ja muutostietokyselyt tehdään yhdenmukaisella tavalla asynkronisten rajapintakyselyiden avulla kts. teknisesti asynkronisen rajapintakyselyn käyttö luvusta "Kyselyt ja esimerkit"

Prosessi asiakkaan kannalta

• asiakassovellus hakee rajapinnasta alkulatausaineiston, siinä kerrotaan minkä pvm mukaista Kauppahintarekisterin tietopalvelun rekisteritilannetta alkulataus vastaa (pvm on saatavilla vastauksen metatiedoissa nimellä rekisteritilannepvm)
  • asiakassovellus laittaa talteen onnistuneen irrotuksen rekisteritilannepvm -tiedon kts. tarkemmin esimerkistä
• asiakassovellus hakee rajapinnasta ensimmäisen muutostietoaineiston, rajaukseksi annetaan edellisessä kohdassa talteen laitettu onnistuneen irrotuksen  rekisteritilannepvm, ja vastauksessa saadaan minkä pvm mukaista Kauppahintarekisterin tietopalvelun rekisteritilannetta palautetut muutostiedot vastaa (pvm on saatavilla vastauksen metatiedoissa nimellä rekisteritilannepvm)
  • asiakassovellus laittaa talteen onnistuneen irrotuksen rekisteritilannepvm -tiedon kts. tarkemmin esimerkistä
• jne.

Asiakassovelluksen tulee käyttää yksilöivänä tunnisteena tietojen päivityksessä omaan järjestelmäänsä kiinteistönluovutustunnusta (kiinteistonluovutustunnus). Mikäli asiakassovellus haluaa pääasiassa niitä kiinteistönluovutuksia, joiden tietosisältö on valmis, niin tämä onnistuu pyytämällä tietyllä viiveellä esim. kerran kuussa muutostiedot. Tietosisältö ei ole aina valmis uuden kiinteistönluovutuksen tallennushetkellä, koska kiinteistönluovutuksien tietoja täydennetään Kauppahintarekisteriin vielä jälkikäteen.

Sekä alkuaineiston hakeminen, että muutostietoaineiston hakeminen kannattaa ajoittaa ma-la välille ja  aamuyöhön klo. 5 jälkeen, jolloin rekisteritilanne on normaalitilanteessa vaihtunut kuluvan päivän mukaiseksi.

Eheän rekisterikopion ylläpitäminen koko Suomesta tai halutusta kunnasta

Esimerkissä käytetty  tuotetta KiinteistonluovutuksenLaajatTiedot ja koordinaatistoa ETRS-TM35FIN (EPSG:3067) 

• asiakassovellus hakee rajapinnasta alkulatausaineiston, esimerkissä alkulatausaineisto pyydetään ma 16.2.2026 klo. 6.00
  • rekisteritilanteen voi  halutessaan tarkistaa ennen tietojen irrotuksen käynnistämistä. Ma-la sen tulisi klo. 5 jälkeen aamuyöllä olla kuluva päivä. Sunnuntaisin rekisteritilanne on normaalitilanteessa edellinen päivä. Rekisteritilanne kysytään seuraavalla kyselyllä: https://[PALVELUOSOITE]collections/KiinteistonluovutuksenTunnistetiedot/metadata
    • esimerkkitilanteessa vastaus: 

      • {
          "rekisteritilannepvm" : "2026-02-16"
        }

  • Alkulatauskyselyesimerkit

    • Esimerkki 1: alkulatauskyselyn tekeminen koko Suomesta: 

      https://[PALVELUOSOITE]collections/KiinteistonluovutuksenLaajatTiedot/processes/items/execution?crs=http://www.opengis.net/def/crs/EPSG/0/3067

    • Esimerkki2: alkulatauskyselyn tekeminen yhdestä kunnasta (esimerkissä käytetty kuntatunnus=420)

      https://[PALVELUOSOITE]collections/KiinteistonluovutuksenLaajatTiedot/processes/items/execution?kuntatunnus=420&crs=http://www.opengis.net/def/crs/EPSG/0/3067

    • Esimerkki3: alkulatauskyselyn tekeminen yhdestä kunnasta (esimerkissä käytetty kuntatunnus=420). On haluttu irrottaa annetusta kunnasta vain ne kiinteistönluovutukset, joiden kiinteistönluovutuksen käyttötarkoitus on lomarakennuspaikka (kiinteistonluovutuksenKayttotarkoituslaji=703) 

      https://[PALVELUOSOITE]collections/KiinteistonluovutuksenLaajatTiedot/processes/items/execution?kuntatunnus=420&kiinteistonluovutuksenKayttotarkoituslaji=703&crs=http://www.opengis.net/def/crs/EPSG/0/3067

• asiakassovellus noutaa alkulatausaineiston kts. teknisesti asynkronisen rajapintakyselyn käyttö luvusta "Kyselyt ja esimerkit"
• asiakassovellus laittaa talteen onnistuneen irrotuksen rekisteritilannepvm -tiedon (tieto otetaan talteen json-vastauksen links-osion ensimmäisestä tulostiedostosta)
  • esimerkki ensimmäisen tulostiedoston lopussa olevasta rekisteritilannepvm tiedosta:

    • "meta":{"rekisteritilannepvm":"2026-02-16"}

• asiakassovellus hakee rajapinnasta ensimmäisen muutostietoaineiston, esimerkissä muutostietoaineisto pyydetään ti 17.2.2026 klo. 6.00
  • rekisteritilanteen voi halutessaan tarkistaa ennen tietojen irrotusten käynnistymistä kuten alkulatausaineiston hakeminen kohdassa on kuvattu käskyllä https://[PALVELUOSOITE]collections/KiinteistonluovutuksenTunnistetiedot/metadata
  • Muutostietokyselyesimerkit

    • Esimerkki 1: muutostietokyselyn tekeminen koko Suomesta:

       https://[PALVELUOSOITE]collections/KiinteistonluovutuksenLaajatTiedot/processes/items/execution?muutostietojenIrrotuksenAlkupvm=2026-02-16&crs=http://www.opengis.net/def/crs/EPSG/0/3067

      • jossa muutostietojenIrrotuksenAlkupvm-tiedoksi annetaan edellisessä kohdassa talteen laitettu onnistuneen irrotuksen  rekisteritilannepvm

    • Esimerkki 2: muutostietokyselyn tekeminen yhdestä kunnasta (esimerkissä käytetty kuntatunnus=420)

      https://[PALVELUOSOITE]collections/KiinteistonluovutuksenLaajatTiedot/processes/items/execution?muutostietojenIrrotuksenAlkupvm=2026-02-16&kuntatunnus=420&crs=http://www.opengis.net/def/crs/EPSG/0/3067

      • jossa muutostietojenIrrotuksenAlkupvm-tiedoksi annetaan edellisessä kohdassa talteen laitettu onnistuneen irrotuksen  rekisteritilannepvm

    • Esimerkki 3: muutostietokyselyn tekeminen yhdestä kunnasta (esimerkissä käytetty kuntatunnus=420). On haluttu irrottaa annetusta kunnasta vain ne kiinteistönluovutukset, joiden kiinteistönluovutuksen käyttötarkoitus on lomarakennuspaikka

      https://[PALVELUOSOITE]collections/KiinteistonluovutuksenLaajatTiedot/processes/items/execution?muutostietojenIrrotuksenAlkupvm=2026-02-16&kuntatunnus=420&kiinteistonluovutuksenKayttotarkoituslaji=703&crs=http://www.opengis.net/def/crs/EPSG/0/3067

      • jossa muutostietojenIrrotuksenAlkupvm-tiedoksi annetaan edellisessä kohdassa talteen laitettu onnistuneen irrotuksen  rekisteritilannepvm
• asiakassovellus noutaa muutostietoaineiston kts. teknisesti asynkronisen rajapintakyselyn käyttö luvusta "Kyselyt ja esimerkit"
• asiakassovellus laittaa talteen onnistuneen irrotuksen rekisteritilannepvm -tiedon (tieto otetaan talteen json-vastauksen links-osion ensimmäisestä tulostiedostosta)
  • esimerkki ensimmäisen tulostiedoston lopussa olevasta rekisteritilannepvm tiedosta:

    • "meta":{"rekisteritilannepvm":"2026-02-17"}

• jne.

Alkulatauskyselyissä ja muutostietokyselyissä on mahdollisuus rajata kyselyä samoilla kyselyparametreilla kuin kyselypalvelukäytössä. (esimerkkeinä mm. edellä olevat esimerkit 2 ja 3). On kuitenkin huolehdittava siitä, että kyselyparametrit ovat yhtenäiset alkulatauskyselyssä ja muutostietokyselyssä, jotta ladattu aineisto pysyy eheänä.

Jos asiakassovelluksella on olemassa tietyn ajanhetken mukainen tilanne järjestelmässään, voi muutostietoja ruveta lataamaan siten, että muutostietojenIrrotuksenAlkupvm on eheän rekisteritilanteen päivämäärä.

Ajantasakyselyesimerkkejä

(kyselypalvelukäyttö)

Tuote KiinteistonluovutuksenTunnistetiedot

Kysytään suorakaiteella rajatulta alueelta niitä voimassaolevia (olotila=1) kiinteistönluovutusten tunnistetietoja, joiden kiinteistönluovutuspvm  on  aikaväliltä 1.1.2019-31.12.2019. Lisäksi rajataan kiinteistönluovutuksen sopimuslajilla ottaen mukaan vain varsinaiset kiinteistönluovutukset (kiinteistonluovutuksenSopimuslaji=1)eli ei oteta mukaan esisopimuksia. Sijaintirajaus on annettu ETRS-TM35 koordinaatistossa. Myös vastaus halutaan ETRS-TM35 koordinaatistoon.

https://[PALVELUOSOITE]collections/KiinteistonluovutuksenTunnistetiedot/items?olotila=1&kiinteistonluovutuksenSopimuslaji=1&filter=kiinteistonluovutuspvm%3E=DATE(%272019-01-01%27)%20AND%20kiinteistonluovutuspvm%3C=DATE(%272019-12-31%27)&filter-lang=cql2-text&crs=http://www.opengis.net/def/crs/EPSG/0/3067&bbox=116000,6654000,140000,6666000&bbox-crs=http://www.opengis.net/def/crs/EPSG/0/3067&f=json

Kysytään kiinteistönluovutuksen tunnistetietoja kiinteistönluovutustunnuksella 

https://[PALVELUOSOITE]collections/KiinteistonluovutuksenTunnistetiedot
 /items?kiinteistonluovutustunnus=L2014-125989&f=json

Kysytään Tampereelta (kuntatunnus=837) niitä voimassaolevia (olotila=1) kiinteistönluovutuksen tunnistetietoja, joiden kiinteistönluovutuspvm on aikaväliltä 1.10.2024-31.12.2024 . Vastaus halutaan ETRS-TM35 koordinaatistoon.

https://[PALVELUOSOITE]collections/KiinteistonluovutuksenTunnistetiedot/items?olotila=1&kuntatunnus=837&filter=kiinteistonluovutuspvm%3E=DATE(%272024-10-01%27)%20AND%20kiinteistonluovutuspvm%3C=DATE(%272024-12-31%27)&filter-lang=cql2-text&crs=http://www.opengis.net/def/crs/EPSG/0/3067&f=json

Kysytään Espoosta (kuntatunnus=049) niitä voimassaolevia (olotila=1) kiinteistönluovutuksen tunnistetietoja, joiden joku kiinteistönluovutuslajeista on kiinteistökauppa (kiinteistonluovutuslaji=1) ja  joiden ensisijainen käyttötarkoituslaji (kayttotarkoitustiedonEnsisijaisuuslaji=1) on lomarakennuspaikka (kiinteistonluovutuksenKayttotarkoituslaji=703

https://[PALVELUOSOITE]collections/KiinteistonluovutuksenTunnistetiedot/items?kuntatunnus=049&olotila=1&kiinteistonluovutuslaji=1&kayttotarkoitustiedonEnsisijaisuuslaji=1&kiinteistonluovutuksenKayttotarkoituslaji=703

Kysytään koko Suomesta ne voimassaolevat kiiinteistönluovutukset, joiden kauppahinta euroina on vähintään 100000 euroa ja enintään 200000 euroa. Vastaus halutaan ETRS-TM35 koordinaatistoon. Pyydetty tuotetta KiinteistonluovutuksenTunnistetiedot.

https://[PALVELUOSOITE]collections/KiinteistonluovutuksenTunnistetiedot/items?olotila=1&filter=kauppahintaEuroina+BETWEEN+100000+AND+200000&crs=http://www.opengis.net/def/crs/EPSG/0/3067&f=json

Kysytään kaikki uusina tallennetut kiinteistönluovutukset aikaväliltä 1.12.2025-31.1.2026. Vastaus halutaan ETRS-TM35 koordinaatistoon. Pyydetty tuotetta KiinteistonluovutuksenTunnistetiedot. (Kyselyä ei ole rajattu kiinteistönluovutuksen olotilalla eli palautuu sekä voimassaolevat, että mahdolliset lakkautetut)

Huom ! Kysely ei ole tarkoitettu eheän rekisterikopion ylläpitämiseen, josta on oma ohjeistuksensa

https://[PALVELUOSOITE]collections/KiinteistonluovutuksenTunnistetiedot/items?filter=rekisterointipvm%3E=DATE(%272025-12-01%27)%20AND%20rekisterointipvm%3C=DATE(%272026-01-31%27)&filter-lang=cql2-text&crs=http://www.opengis.net/def/crs/EPSG/0/3067&f=json

Tuote KiinteistonluovutuksenLaajatTiedotIlmanHenkilotietoja

Kysytään kiinteistotunnus-parametria käyttäen yhden rekisteriyksikön voimassaolevat kiinteistönluovutukset. Pyydetty tuotetta KiinteistonluovutuksenLaajatTiedotIlmanHenkilotietoja.

https://[PALVELUOSOITE]collections/KiinteistonluovutuksenLaajatTiedotIlmanHenkilotietoja/items?kiinteistotunnus=58140900050039&olotila=1

Kysytään useamman rekisteriyksikön voimassaolevat kiinteistönluovutukset yhdellä kyselyllä listaamalla kiinteistötunnukset pilkulla erotettuna. Pyydetty tuotetta KiinteistonluovutuksenLaajatTiedotIlmanHenkilotietoja.

https://[PALVELUOSOITE]collections/KiinteistonluovutuksenLaajatTiedotIlmanHenkilotietoja/items?kiinteistotunnus=58140900050039,62540500630000&olotila=1