Tekninen kuvaus Kiinteistötietojen kyselypalvelu (REST)
Kiinteistötietojen kyselypalvelu (REST) tarjoaa ajantasaisia tietoja lainhuuto- ja kiinnitysrekisteristä. Tiedot tarjotaan REST rajapinnan kautta XML-formaatissa. Palvelu on suunniteltu tukemaan organisaatioiden toimintaa, kuten yhdyskuntasuunnittelua ja kiinteistönvälitystä.
Yhteyden muodostaminen ja autentikointi
Yhteys palvelun ja asiakkaan välillä on SSL-suojattu (Secure Socket Layer, HTTPS-protokolla). Palveluun kirjautuminen tapahtuu käyttäjätunnuksella (palvelutunnuksella) ja salasanalla käyttäen HTTP Basic Authentication -tunnistusta. Tunnus-salasanayhdistelmä tulee tallentaa asiakkaan sovellukseen niin, että sovelluksen loppukäyttäjä ei saa sitä tietoonsa missään vaiheessa.
Tuotekohtaiset palveluosoitteet ja hakuehdot löytyvät osiosta kyselyt ja esimerkit.
Käyttäjätunnuksella on pääsy vain käyttöluvassa myönnettyihin tuotekokonaisuuksiin ja tuoteversioihin. Lisätietoa tuotekokonaisuuksien sisällöstä.
Loppukäyttäjän lokitus
Kiinteistötietojen Kyselypalvelun (REST) palvelinjärjestelmässä tallennetaan lokeihin tietoa myös asiakassovelluksessa tunnistetusta loppukäyttäjästä. Asiakassovelluksen tulee välittää rajapintapalvelulle loppukäyttäjän eli luonnollisen henkilön tai robotin yksilöivä tunniste jokaisen rajapintapyynnön yhteydessä.
Tunniste tulee välittää HTTP-standardin mukaisena Request Header-kenttänä nimeltään "enduserid". Tunnisteen täytyy olla merkkijono, jonka pituus saa olla max. 60 merkkiä, välilyönnit eivät ole sallittuja. Muutoin merkkijonon sisältö voi olla asiakassovelluksen määrittämä. Tunniste tulee kuitenkin olla sellainen, jonka perusteella asiakasorganisaatio voi tarvittaessa selvittää kuka henkilö on hakenut tietoja Maanmittauslaitoksen rajapintapalvelun kautta. Myös automaattisesti suoritetuilla kyselyillä tulee olla yksilöity tunniste.
Yleistä lisätietoa HTTP:n Request Header-kentistä: https://developer.mozilla.org/en-US/docs/Glossary/Request_header
Lokitietojen ja tunnisteen käytön toimivuus on hyvä varmistaa ennen tuotantopalvelun käyttöönottoa. Ota yhteyttä Maanmittauslaitokseen osoitteeseen verkkopalvelut@maanmittauslaitos.fi
Tunnisteen toimittamisen lisäksi asiakasorganisaation tulee myös itse järjestää lokitietoja säilytys kuuden vuoden ajan. Tämän jälkeen lokitiedot täytyy hävittää.
Käytettävyys ja tuki
Palvelussa on joka yö käyttökatko 23.15 - 01.00, jonka aikana rekisteritiedot päivittyvät.
Rajapinnan tekninen tuki palvelee ma - pe klo 8 - 16. Saat tukeen yhteyden verkkolomakkeella.
Sopimuksiin ja käyttäjätunnuksiin liittyvää tukea saat osoitteesta verkkopalvelut@maanmittauslaitos.fi.
Aineistot ja tuotteet
Palvelun skeemat
Palvelussa on käytössä sovellusversio 8.1. (julkaisu syksy 2024) Version 8.1 skeemat päivitetään tälle sivulle myöhemmin.
Skeemat sovellusversiosta 6.0:
Koko palvelun skeemat zip-pakettina:
http://xml.nls.fi/XML/Schema/sovellus/ktjkir/kios-report-api-6.0-src.zip
(Jos linkki ei avaudu suoraan, kopio osoite selaimen osoiteriville)
Skeemat tuotteittain
Kyselyt ja esimerkit
Tässä osiossa käydään läpi tuotteiden ja tuoteversioiden kyselyosoitteet ja hakuehdot.
- Yleisiä ohjeita
- Perustiedot
- Lainhuutotiedot
- Rasitustiedot
- Vuokraoikeustiedot
- Henkilön omistukset
- Rekisteriyksiköiden haku hakuehdoin
- Haku kiinteistötunnuksella
- Haku kunnalla
- Muutostapahtumien haku
- Määräalojen haku hakuehdoin
- Haku määräalatunnuksella
- Haku kunnalla
- Muutostapahtumien haku
- Laitosten haku hakuehdoin
- Haku laitostunnuksella
- Haku kunnalla
- Haku kiinteistötunnuksella
- Muutostapahtumien haku
- Yhteystiedot
- Koodistot
Yleisiä ohjeita
XML-rakenne pyydetään palvelusta HTTPS/GET-protokollaan perustuvalla kyselyllä. Kyselyyn sisältyvät parametrit, joiden mukaista tietoa haetaan.
Kaikissa parametreissa, joille voi antaa 1-n kappaletta arvoja, arvot voidaan antaa kahdella tavalla:
- Parametrin nimi kerran ja parametrin arvot pilkuilla erotettuina
- Esim. kohdetunnus=41840100060028,41840100060029
- Parametrin nimi toistetaan jokaiselle arvolle
- Esim. kohdetunnus=41840100060028&kohdetunnus=41840100060029
Kiinteistö- määräala- ja laitostunnusta voidaan käyttää
- normaalimuodossa (esim. 41840100060029)
- väliviivamuodossa (esim. 418-401-6-29)
Henkilötietoja sisältävistä tuotteista on olemassa erilaiset tuotekokonaisuuksien mukaiset tuoteversiot. Erilaiset tuoteversiot on tarkoitettu eri asiakasryhmille erilaisia käyttötarpeita varten. Laajat tiedot henkilötunnuksin käyttöoikeus sisältää myös suppeammat tuoteversiot.
Tuoteversiot henkilötietojen laajuuden mukaan:
- tuote sisältää kaikki skeeman mukaiset henkilötiedot
- tuote ei sisällä luonnollisen henkilön henkilötunnusta
- tuote ei sisällä luonnollisen ja tuntemattoman henkilön henkilötietoja
Esimerkkejä kyselyistä löytyy myös koekäyttöpalvelun teknisestä kuvauksesta.
Perustiedot
Perustiedot voidaan pyytää enintään sadasta kohteesta (rekisteriyksikkö/kiinteistö, määräala ja vuokraoikeus eli laitos) kerrallaan.
Hakuparametrit
| Nimi | Arvot | Kuvaus |
| kiinteistotunnus | kiinteistötunnus | Sekä normaalimuoto että väliviivamuoto tuettuna. |
| maaraalatunnus | määräalatunnus | Sekä normaalimuoto että väliviivamuoto tuettuna. |
| laitostunnus | laitostunnus | Sekä normaalimuoto että väliviivamuoto tuettuna. |
| kohdetunnus |
kiinteistötunnus, määräalatunnus, laitostunnus |
Sekä normaalimuoto että väliviivamuoto tuettuna. |
Kyselyjen URL-osoitteet
Alla olevassa taulukossa on esitetty eri tuoteversioissa käytettävä kyselyn URL osoite. Vaihda hakuparametria (kiinteistötunnus/määräalatunnus/laitostunnus/kohdetunnus) tarpeen mukaan.
Vuokraoikeuden eli laitoksen perustiedot sisältävät henkilötietoja. Eri asiakasryhmiä varten on olemassa seuraavat tuoteversiot:
- kaikki skeeman mukaiset henkilötiedot esitetään (henkilötunnukset mukana)
- luonnollisen henkilön henkilötunnusta ei esitetä
- luonnollisen ja tuntemattoman henkilön henkilötietoja ei esitetä
Kiinteistön ja määräalan perustiedot eivät sisällä henkilötietoja, joten niistä ei ole olemassa erilaisia tuoteversioita.
| Tuoteversiot | Kyselyn URL osoite |
| Kiinteistön (rekisteriyksikön) perustiedot | https://ktjws.nls.fi/ktjkir/kysely/perustiedot/kohde/xml?kiinteistotunnus=858-416-3-101 |
| Määräalan perustiedot | https://ktjws.nls.fi/ktjkir/kysely/perustiedot/kohde/xml?maaralatunnus=858-416-3-101-M604 |
| Vuokraoikeus, kaikki henkilötiedot | https://ktjws.nls.fi/ktjkir/kysely/perustiedot/kohde/xml?laitostunnus=858-416-3-101-L1 |
| Vuokraoikeus, ilman henkilötunnusta | https://ktjws.nls.fi/ktjkir/kysely/perustiedot_ilman_henkilotunnusta/kohde/xml?laitostunnus=858-416-3-101-L1 |
| Vuokraoikeus, ilman henkilötietoja | https://ktjws.nls.fi/ktjkir/kysely/perustiedot_ilman_henkilotietoja/kohde/xml?laitostunnus=858-416-3-101-L1 |
Katso esimerkkejä kyselyistä ja vastauksista koekäyttöpalvelun teknisestä kuvauksesta.
Lainhuutotiedot
Lainhuutotiedot voidaan pyytää sadasta kohteesta (rekisteriyksikkö ja määräala) kerrallaan.
Hakuparametrit
| Nimi | Arvot | Kuvaus |
| kiinteistotunnus | kiinteistötunnus | Sekä normaalimuoto että väliviivamuoto tuettuna. |
| maaraalatunnus | määräalatunnus | Sekä normaalimuoto että väliviivamuoto tuettuna. |
| kohdetunnus | kiinteistötunnus, määräalatunnus | Sekä normaalimuoto että väliviivamuoto tuettuna. |
Alla olevassa taulukossa on esitetty eri tuoteversioissa käytettävä kyselyn URL osoite. Vaihda hakuparametria (kiinteistötunnus/määräalatunnus/kohdetunnus) tarpeen mukaan.
Kyselyjen URL-osoitteet
| Tuoteversiot | Kyselyn URL osoite |
| Lainhuutotiedot kiinteistöstä, kaikki henkilötiedot | https://ktjws.nls.fi/ktjkir/kysely/lainhuutotiedot/xml?kiinteistotunnus=858-416-3-101 |
| Lainhuutotiedot kiinteistöstä, ilman henkilötunnusta | https://ktjws.nls.fi/ktjkir/kysely/lainhuutotiedot_ilman_henkilotunnusta/xml?kiinteistotunnus=858-416-3-101 |
| Lainhuutotiedot kiinteistöstä, ilman henkilötietoja | https://ktjws.nls.fi/ktjkir/kysely/lainhuutotiedot_ilman_henkilotietoja/xml?kiinteistotunnus=858-416-3-101 |
Katso esimerkkejä kyselyistä koekäyttöpalvelun teknisestä kuvauksesta.
Rasitustiedot
Rasitustiedot voidaan pyytää sadasta kohteesta (rekisteriyksikkö, määräala tai laitos) kerrallaan.
Hakuparametrit
| Nimi | Arvot | Kuvaus |
| kiinteistotunnus | kiinteistötunnus | Sekä normaalimuoto että väliviivamuoto tuettuna. |
| maaraalatunnus | määräalatunnus | Sekä normaalimuoto että väliviivamuoto tuettuna. |
| laitostunnus | laitostunnus | Sekä normaalimuoto että väliviivamuoto tuettuna. |
| kohdetunnus |
kiinteistötunnus, määräalatunnus, laitostunnus |
Sekä normaalimuoto että väliviivamuoto tuettuna. |
Kyselyjen URL-osoitteet
Alla olevassa taulukossa on esitetty eri tuoteversioissa käytettävä kyselyn URL osoite. Vaihda hakuparametria (kiinteistötunnus/määräalatunnus/laitostunnus/kohdetunnus) tarpeen mukaan.
| Tuoteversiot | Kyselyn URL osoite |
| Rasitustiedot kiinteistöstä, kaikki henkilötiedot | https://ktjws.nls.fi/ktjkir/kysely/rasitustiedot/xml?kiinteistotunnus=858-416-3-115 |
| Rasitustiedot kiinteistöstä, ilman henkilötunnusta | https://ktjws.nls.fi/ktjkir/kysely/rasitustiedot_ilman_henkilotunnusta/xml?kiinteistotunnus=858-416-3-115 |
| Rasitustiedot kiinteistöstä, ilman henkilötietoja | https://ktjws.nls.fi/ktjkir/kysely/rasitustiedot_ilman_henkilotietoja/xml?kiinteistotunnus=858-416-3-115 |
Katso esimerkkejä kyselyistä ja vastauksista koekäyttöpalvelun teknisestä kuvauksesta.
Vuokraoikeustiedot
Vuokraoikeustiedot voidaan pyytää sadasta kohteesta (laitos) kerrallaan.
Hakuparametrit
| Nimi | Arvot | Kuvaus |
| laitostunnus | laitostunnus | Sekä normaalimuoto että väliviivamuoto tuettuna. |
| kohdetunnus | laitostunnus | Sekä normaalimuoto että väliviivamuoto tuettuna. |
Kyselyjen URL-osoitteet
Alla olevassa taulukossa on esitetty eri tuoteversioissa käytettävä kyselyn URL osoite. Vaihda hakuparametria (laitostunnus/kohdetunnus) tarpeen mukaan.
| Tuoteversiot | Kyselyn URL osoite |
| Vuokraoikeustiedot laitoksesta, kaikki henkilötiedot: | https://ktjws.nls.fi/ktjkir/kysely/vuokraoikeustiedot/xml?laitostunnus=858-416-3-101-L1 |
| vuokraoikeustiedot laitoksesta ilman henkilötunnusta | https://ktjws.nls.fi/ktjkir/kysely/vuokraoikeustiedot_ilman_henkilotunnusta/xml?laitostunnus=858-416-3-101-L1 |
| vuokraoikeustiedot laitoksesta ilman henkilötietoja | https://ktjws.nls.fi/ktjkir/kysely/vuokraoikeustiedot_ilman_henkilotietoja/xml?laitostunnus=858-416-3-101-L1 |
Henkilön omistukset
Henkilön omistukset voidaan pyytää yhdeltä omistajalta (henkilö- tai y-tunnus) kerrallaan.
Tuotteen käyttöoikeus voidaan myöntää vain viranomaisille.
Hakuparametrit
| Nimi | Arvot | Lkm | Kuvaus |
| henkilotunnus | henkilötunnus | 0..1 | Kirjainkoko ei merkitsevä |
| ytunnus | y-tunnus | 0..1 | |
| tunnus | henkilötunnus, y-tunnus | 0..1 | Kirjainkoko ei merkitsevä |
| kunta | kuntatunnus | 0..1 | Sekä etunollallinen että etunollaton kuntatunnus tuettuna. |
| rooli |
Koodiston Rooli arvot: LHHS = Lainhuudon saaja LVSA = Luovutuksen saaja LHOS = Omistusoikeuden saaja EOVU = Vuokralainen LHHV = Hallinnoiva viranomainen |
0..n | Koodiston muut arvot eivät ole sallittuja. |
| kohdelaji |
Sallitut arvot: KI = Rekisteriyksikkö MA = Määräala RT = Rekisteröity tontinvuokraoikeus VO = Vuokraoikeus, jolla on laitostunnus |
0..n |
Kyselyjen URL-osoitteet
Alla olevassa taulukossa on esitetty tuotteen kyselyn URL osoite. Vaihda hakuparametria tarpeen mukaan.
| Tuoteversiot | Kyselyn URL osoite |
| Henkilön omistukset henkilötunnuksella | https://ktjws.nls.fi/ktjkir/kysely/omistustiedot/tunnus/xml?henkilotunnus=xxxxxx-xxxx |
Rekisteriyksiköiden haku hakuehdoin
Hakutapa: Rekisteriyksiköiden haku kiinteistötunnuksella
Hakutavalla voidaan pyytää xml-rakennetta sadalla kohteella (rekisteriyksikkö) kerrallaan.
Hakuparametrit
| Nimi | Arvot | Lkm | Kuvaus |
| kiinteistotunnus | kiinteistötunnus | 1..n | Sekä normaalimuoto että väliviivamuoto tuettuna. |
| kohdetunnus | kiinteistötunnus | 1..n | Sekä normaalimuoto että väliviivamuoto tuettuna. |
| olotila |
Koodiston Olotila arvot: 1 = Voimassaoleva 2 = Lakannut |
0..n | |
| rekisteriyksikkolaji | Koodiston Rekisteriyksikkolaji arvot | 0..n | |
| maapintaalaAlku | Pinta-ala neliömetreinä, kokonaisluku | 0..1 | Pinta-alavälin alkuarvo. Raja-arvo sisältyy hakutulokseen. |
| maapintaalaLoppu | Pinta-ala neliömetreinä, kokonaisluku | 0..1 | Pinta-alavälin loppuarvo. Raja-arvo sisältyy hakutulokseen. |
Alla olevassa taulukossa on esitetty tuotteen kyselyn URL osoite. Vaihda ja lisää hakuparametria tarpeen mukaan.
Kyselyjen URL-osoitteet
| Tuoteversio | Kyselyn URL osoite |
| Rekisteriyksiköiden haku kiinteistötunnuksella | https://ktjws.nls.fi/ktjkir/kysely/perustiedot/rekisteriyksikko/kohde/xml?kiinteistotunnus=91-17-16-1 |
| https://ktjws.nls.fi/ktjkir/kysely/perustiedot/rekisteriyksikko/kohde/xml?kiinteistotunnus=91-17-16-1&olotila=1&perustiedotMukana=true |
Hakutapa: Rekisteriyksiköiden haku kunnalla
Hakutavalla voidaan pyytää xml-rakennetta yhdellä kohteella (kunta) kerrallaan.
Hakuparametrit
| Nimi | Arvot | Lkm | Kuvaus |
| kunta | kuntatunnus | 1 | Sekä etunollallinen että etunollaton kuntatunnus tuettuna. Hakee kohteet, jotka tällä hetkellä sijaitsevat annetussa kunnassa. |
| rekisteriyksikonNimi | Rekisteriyksikön nimi tai nimen osa ja jokerimerkki, esim. koivikk* | 0..1 | Kirjainkoko ei merkitsevä. Ehdossa voidaan antaa nimen alkuosa, jokerimerkkinä tähti (*). |
| olotila |
Koodiston Olotila arvot: 1 = Voimassaoleva 2 = Lakannut |
0..n | |
| rekisteriyksikkolaji | Koodiston Rekisteriyksikkolaji arvot | 0..n | |
| maapintaalaAlku | Pinta-ala neliömetreinä, kokonaisluku | 0..1 | Pinta-alavälin alkuarvo. Raja-arvo sisältyy hakutulokseen. |
| maapintaalaLoppu | Pinta-ala neliömetreinä, kokonaisluku | 0..1 | Pinta-alavälin loppuarvo. Raja-arvo sisältyy hakutulokseen. |
Kyselyjen URL-osoitteet
| Rekisteriyksiköiden haku kuntaparametrilla | https://ktjws.nls.fi/ktjkir/kysely/perustiedot/rekisteriyksikko/kunta/xml?kunta=261 |
| Rekisteriyksiköiden haku kunta- ja rekisteriyksikonNimi -parametreilla | https://ktjws.nls.fi/ktjkir/kysely/perustiedot/rekisteriyksikko/kunta/xml?rekisteriyksikonNimi=Koivula&kunta=261 |
Hakutapa: Rekisteriyksiköiden haku muutoksilla
Hakutavalla voidaan pyytää xml-rakennetta rekisterissä muuttuneista kohteista. Kysely palauttaa rekisteriyksiköt, jotka ovat muuttuneet annetun muutostapahtumalajin mukaisesti annetulla aikavälillä. Vastaukseen tulostetaan myös annetuilla hakuparametreilla löytyneet muutostapahtumat.
Muutostapahtumalajit
Tutustu muutostapahtumalaji -koodiston koodiarvoihin, nimiin ja selityksiin.
Hakuparametrit
| Nimi | Arvot | Lkm | Kuvaus |
| muutostapahtumalaji | Koodiston Muutostapahtumalaji arvot | 1 |
Poimitaan rekisteriyksiköt, joissa on tapahtunut annetun muutostapahtumalajin mukainen muutos. |
| muutospvmAlku | Päivämäärä muodossa vvvv-kk-pp | 1 | Muutosaikavälin alkupäivä. Raja-arvo sisältyy hakutulokseen. |
| muutospvmLoppu | Päivämäärä muodossa vvvv-kk-pp | 1 | Muutosaikavälin loppupäivä. Raja-arvo sisältyy hakutulokseen. |
| kunta | kuntatunnus | 0..1 | Sekä etunollallinen että etunollaton kuntatunnus tuettuna. Kuntatunnuksen pois jättäminen tekee haun koko Suomesta. Hakee kohteet, jotka tällä hetkellä sijaitsevat annetussa kunnassa. |
| olotila |
Koodiston Olotila arvot: 1 = Voimassaoleva 2 = Lakannut |
0..n | |
| rekisteriyksikkolaji | Koodiston Rekisteriyksikkolaji arvot | 0..n | |
| maapintaalaAlku | Pinta-ala neliömetreinä, kokonaisluku | 0..1 | Pinta-alavälin alkuarvo. Raja-arvo sisältyy hakutulokseen. |
| maapintaalaLoppu | Pinta-ala neliömetreinä, kokonaisluku | 0..1 | Pinta-alavälin loppuarvo. Raja-arvo sisältyy hakutulokseen. |
Kyselyjen URL-osoitteet
Alla olevassa taulukossa on esitetty tuotteen kyselyn URL osoite. Vaihda ja lisää hakuparametria tarpeen mukaan.
| Tuoteversio | Kyselyn URL osoite |
|
Muuttuneiden kohteiden haku Esimerkiksi uudet rekisteriyksiköt 16.-17.2.2015 Espoosta |
https://ktjws.nls.fi/ktjkir/kysely/perustiedot/rekisteriyksikko/muutos/xml?muutostapahtumalaji=203&muutospvmAlku=2015-02-16&muutospvmLoppu=2015-02-17&kunta=049 |
Määräalojen haku hakuehdoin
Hakutapa: Määräalojen haku määräalatunnuksella
Hakutavalla voidaan pyytää xml-rakennetta sadalla kohteella (määräala) kerrallaan.
Hakuparametrit
| Nimi | Arvot | Lkm | Kuvaus |
| maaraalatunnus | määräalatunnus | 1..n | Sekä normaalimuoto että väliviivamuoto tuettuna. |
| kohdetunnus | määräalatunnus | 1..n | Sekä normaalimuoto että väliviivamuoto tuettuna. |
| olotila |
Koodiston Olotila arvot: 1 = Voimassaoleva 2 = Lakannut |
0..n |
Kyselyjen URL-osoitteet
Alla olevassa taulukossa on esitetty tuotteen kyselyn URL osoite. Vaihda ja lisää hakuparametria tarpeen mukaan.
| Tuoteversio | Kyselyn URL osoite |
| Määräalojen haku määräalatunnuksilla | https://ktjws.nls.fi/ktjkir/kysely/perustiedot/maaraala/kohde/xml?kohdetunnus=05040100010012M0601 |
Hakutapa: Määräalojen haku kunnalla
Hakutavalla voidaan pyytää xml-rakennetta yhdellä kohteella (kunta) kerrallaan.
Hakuparametrit
| Nimi | Arvot | Lkm | Kuvaus |
| kunta | kuntatunnus | 1 | Sekä etunollallinen että etunollaton kuntatunnus tuettuna. Hakee kohteet, jotka tällä hetkellä sijaitsevat annetussa kunnassa. |
| olotila |
Koodiston Olotila arvot: 1 = Voimassaoleva 2 = Lakannut |
0..n |
Kyselyjen URL-osoitteet
Alla olevassa taulukossa on esitetty tuotteen kyselyn URL osoite. Vaihda ja lisää hakuparametria tarpeen mukaan.
| Tuoteversio | Kyselyn URL osoite |
| Määräalojen haku kuntaparametrilla | https://ktjws.nls.fi/ktjkir/kysely/perustiedot/maaraala/kunta/xml?kunta=050 |
Hakutapa: Määräalojen haku muutoksilla
Hakutavalla voidaan pyytää xml-rakennetta rekisterissä muuttuneista kohteista. Kysely palauttaa määräalat, jotka ovat muuttuneet annetun muutostapahtumalajin mukaisesti annetulla aikavälillä. Vastaukseen tulostetaan myös annetuilla hakuparametreilla löytyneet muutostapahtumat.
Muutostapahtumalajit
Tutustu muutostapahtumalaji -koodiston koodiarvoihin, nimiin ja selityksiin.
Hakuparametrit
| Nimi | Arvot | Lkm | Kuvaus |
| muutostapahtumalaji | Koodiston Muutostapahtumalaji arvot | 1 |
Poimitaan määräalat, joissa on tapahtunut annetun muutostapahtumalajin mukainen muutos. |
| muutospvmAlku | Päivämäärä muodossa vvvv-kk-pp | 1 | Muutosaikavälin alkupäivä. Raja-arvo sisältyy hakutulokseen. |
| muutospvmLoppu | Päivämäärä muodossa vvvv-kk-pp | 1 | Muutosaikavälin loppupäivä. Raja-arvo sisältyy hakutulokseen. |
| kunta | kuntatunnus | 0..1 | Sekä etunollallinen että etunollaton kuntatunnus tuettuna. Kuntatunnuksen pois jättäminen tekee haun koko Suomesta. Hakee kohteet, jotka tällä hetkellä sijaitsevat annetussa kunnassa. |
| olotila |
Koodiston Olotila arvot: 1 = Voimassaoleva 2 = Lakannut |
0..n |
Kyselyjen URL-osoitteet
Alla olevassa taulukossa on esitetty tuotteen kyselyn URL osoite. Vaihda ja lisää hakuparametria tarpeen mukaan.
| Tuoteversio | Kyselyn URL osoite |
|
Määräalan haku muutoksilla Esimerkiksi uudet määräalat 16.-17.2.2024 Espoosta |
https://ktjws.nls.fi/ktjkir/kysely/perustiedot/maaraala/muutos/xml?muutostapahtumalaji=203&muutospvmAlku=2024-02-16&muutospvmLoppu=2024-02-17&kunta=049 |
Laitosten haku hakuehdoin
Hakutapa: Laitosten haku laitostunnuksella
Hakutavalla voidaan pyytää xml-rakennetta sadalla kohteella (laitos) kerrallaan.
Hakuparametrit
| Nimi | Arvot | Lkm | Kuvaus |
| laitostunnus | laitostunnus | 1..n | Sekä normaalimuoto että väliviivamuoto tuettuna. |
| kohdetunnus | laitostunnus | 1..n | Sekä normaalimuoto että väliviivamuoto tuettuna. |
| olotila |
Koodiston Olotila arvot: 0 = Vireillä 1 = Voimassaoleva 2 = Lakannut |
0..n |
Kyselyjen URL-osoitteet
Alla olevassa taulukossa on esitetty tuotteen kyselyn URL osoite. Vaihda ja lisää hakuparametria tarpeen mukaan.
| Tuoteversiot | Kyselyn URL osoite |
| Laitoksen haku laitostunnuksella | https://ktjws.nls.fi/ktjkir/kysely/perustiedot/laitos/kohde/xml?kohdetunnus=05040100020047L0001 |
Hakutapa: Laitosten haku kunnalla
Hakutavalla voidaan pyytää xml-rakennetta yhdellä kohteella (kunta) kerrallaan.
Hakuparametrit
| Nimi | Arvot | Lkm | Kuvaus |
| kunta | kuntatunnus | 1 | Sekä etunollallinen että etunollaton kuntatunnus tuettuna. Hakee kohteet, jotka tällä hetkellä sijaitsevat annetussa kunnassa. |
| olotila |
Koodiston Olotila arvot: 0 = Vireillä 1 = Voimassaoleva 2 = Lakannut |
0..n |
Kyselyjen URL-osoitteet
Alla olevassa taulukossa on esitetty tuotteen kyselyn URL osoite. Vaihda ja lisää hakuparametria tarpeen mukaan.
| Tuoteversiot | Kyselyn URL osoite |
| Laitoksen haku kuntatunnuksella | https://ktjws.nls.fi/ktjkir/kysely/perustiedot/laitos/kunta/xml?kunta=050 |
Hakutapa: Laitosten haku kiinteistötunnuksella
Hakutavalla voidaan pyytää xml-rakennetta sadalla kohteella (kiinteistötunnus) kerrallaan.
Hakuparametrit
| Nimi | Arvot | Lkm | Kuvaus |
|
kohdetunnus kiinteistotunnus |
kiinteistötunnus | 0..100 | Sekä normaalimuoto ja tavuviivamuoto tuettuna |
| olotila |
Koodiston Olotila arvot: 0 = Vireillä 1 = Voimassaoleva 2 = Lakannut |
0..n |
Kyselyjen URL-osoitteet
| Tuoteversiot | Kyselyn URL osoite |
| Laitoksen haku kiinteistötunnuksella | https://ktjws.nls.fi/ktjkir/kysely/perustiedot/laitos/kiinteisto/xml?kiinteistotunnus=91-10-631-5 |
Hakutapa: Laitosten haku muutoksilla
Hakutavalla voidaan pyytää xml-rakennetta rekisterissä muuttuneista kohteista. Kysely palauttaa laitokset, jotka ovat muuttuneet annetun muutostapahtumalajin mukaisesti annetulla aikavälillä. Vastaukseen tulostetaan myös annetuilla hakuparametreilla löytyneet muutostapahtumat.
Muutostapahtumalajit
Tutustu muutostapahtumalaji -koodiston koodiarvoihin, nimiin ja selityksiin.
Hakuparametrit
| Nimi | Arvot | Lkm | Kuvaus |
| muutostapahtumalaji | Koodiston Muutostapahtumalaji arvot | 1 |
Poimitaan laitokset, joissa on tapahtunut annetun muutostapahtumalajin mukainen muutos. |
| muutospvmAlku | Päivämäärä muodossa vvvv-kk-pp | 1 | Muutosaikavälin alkupäivä. Raja-arvo sisältyy hakutulokseen. |
| muutospvmLoppu | Päivämäärä muodossa vvvv-kk-pp | 1 | Muutosaikavälin loppupäivä. Raja-arvo sisältyy hakutulokseen. |
| kunta | kuntatunnus | 0..1 | Sekä etunollallinen että etunollaton kuntatunnus tuettuna. Kuntatunnuksen pois jättäminen tekee haun koko Suomesta. Hakee kohteet, jotka tällä hetkellä sijaitsevat annetussa kunnassa. |
| olotila |
Koodiston Olotila arvot: 0 = Vireillä 1 = Voimassaoleva 2 = Lakannut |
0..n |
Kyselyjen URL-osoitteet
Alla olevassa taulukossa on esitetty tuotteen kyselyn URL osoite. Vaihda ja lisää hakuparametria tarpeen mukaan.
| Tuoteversiot | Kyselyn URL osoite |
|
Laitoksen haku muutoksilla Esimerkiksi laitokset, joilla vuokraoikeuden muutos on hyväksytty lainvoimaisesti 8.-12.12.2023 Espoosta: |
https://ktjws.nls.fi/ktjkir/kysely/perustiedot/laitos/muutos/xml?muutostapahtumalaji=112&muutospvmAlku=2023-12-08&muutospvmLoppu=2023-12-12&kunta=049 |
Yhteystiedot
Yhteystiedot voidaan pyytää sadasta kohteesta (rekisteriyksikkö, määräala tai laitos) kerrallaan.
Hakuparametrit
| Nimi | Arvot | Kuvaus |
| kiinteistotunnus | kiinteistötunnus | Sekä normaalimuoto että väliviivamuoto tuettuna. |
| maaraalatunnus | määräalatunnus | Sekä normaalimuoto että väliviivamuoto tuettuna. |
| laitostunnus | laitostunnus | Sekä normaalimuoto että väliviivamuoto tuettuna. |
| kohdetunnus |
kiinteistötunnus, määräalatunnus, laitostunnus |
Sekä normaalimuoto että väliviivamuoto tuettuna. |
Kyselyjen URL-osoitteet
Alla olevassa taulukossa on esitetty tuotteen kyselyn URL osoite. Vaihda ja lisää hakuparametria tarpeen mukaan.
| Tuoteversiot | Kyselyn URL osoite |
|
Yhteystiedot useasta kohteesta |
https://ktjws.nls.fi/ktjkir/kysely/yhteystiedot/xml?kohdetunnus=638-414-1-301-M603,858-416-3-101,698-3-101-19-L1,444-1-106-12 |
Koodistot
Koodistojen nimet ja arvot xml-muodossa. Koodiston avaaminen vaatii käyttäjätunnuksen.
Url: https://ktjws.nls.fi/ktjkir/kysely/koodistot/xml
Virheiden hallinta
Palveluun kytkeytymiseen tai saatavuuteen sekä tietoliikenteeseen liittyvistä virhe-tilanteista palautetaan asiakassovellukselle virheilmoitus HTTP-virhekoodeina. Mm. seuraavat virhekoodit voivat tulla kyseeseen:
| Virhekoodi | HTTP-tunnus | Selitys |
| 400 | Bad Request | Hakupyyntö tai sen parametrit ovat virheellisiä. |
| 401 | Unauthorized | Palvelu ei hyväksy asiakassovelluksen välittämää käyttäjätunnistetta. |
| 403 | Forbidden | Käyttäjälle ei ole oikeuksia tuotteeseen |
| 500 | Internal Server Error | Pyyntöä käsiteltäessä tapahtunut jokin odottamaton virhetilanne. |
| 503 | Service Unavailable | Palvelussa on liikaa ruuhkaa tai samalla käyttäjällä on liian monta samanaikaista pyyntöä. |