Tekninen kuvaus Avoimet tuotteet (sopimus)
Palvelun kautta saat käyttöösi kiinteistörekisterin avoimet tuotteet (ml. kiinteistöjaotus).
Palvelun käyttöönotto vaatii sopimusta. Katso lisää kohdasta ’Ota käyttöösi’.
Rajapintapalvelu on saatavilla OGC API Features-standardin mukaisena seuraavista osoitteista:
| Palvelu | Käyttäjätunnistus | Palveluosoite | API-kuvaus | Tuotteet |
|---|---|---|---|---|
Avoin, Simple | Käyttäjätunnus | https://sopimus-paikkatieto.maanmittauslaitos.fi/kiinteisto-avoin/simple-features/v3/ | API | Avoimet simple-tuotteet |
Avoin, kaikki | Käyttäjätunnus | https://sopimus-paikkatieto.maanmittauslaitos.fi/kiinteisto-avoin/features/v3/ | API | Kaikki avoimet tuotteet |
Yleistä
Rajapinnan tietotuotteet ovat muotoa GeoJSON
Oletuskoordinaatisto on OGC API Features -standardin ja GeoJSON-spesifikaation mukaisesti WGS84 lon-lat (tunniste CRS84) maantieteellinen koordinaatisto. Palvelu tukee myös ETRS-TM35FIN, ETRS-TM34..36 ja ETRS-GK19..31FIN projisoituja koordinaatistoja, WGS84-koordinaatistoa EPSG:4326 tunnisteella, ETRS89 (2D) maantieteellistä koordinaatistoa sekä Web Mercator -koordinaatistoa.
Osa kyselyparametreista ja kohteiden ominaisuustiedoista on mallinnettu koodistoarvoina, joiden selitystekstit on julkaistu erillisen luettelopalvelun kautta:
http://www.luettelopalvelu.fi/codelist/KTJkii
Esimerkkejä asiakassovelluksista
Avoin, Simple:
Voit käyttää Simple – muotoisia avoimia tuotteita esim. QGIS- tai GDAL-ohjelmistoissa tms. sekä sovelluksissa, joissa keskeisintä on kiinteistöjaotuksen (sisältäen myös määräalat) sijaintitietojen esittäminen.
Avoin, kaikki:
Käyttö sovellusintegraatioissa, joissa hyödynnetään myös palvelun monimuotoisia tuotteita (esim. rekisteriyksikön tai palstan laajat sijaintitiedot) tai laajempia ominaisuustietoja (esim. rekisteriyksikön avoimet ominaisuustiedot).
Alasvetovalikosta Aineistot ja tuotteet löytyy lisää tietoa tuotteista.
Aineistot ja tuotteet
Aineisto
Palvelusta tarjottavat tiedot tuotetaan ajantasaisesta Kiinteistörekisteristä. Palvelusta tarjottavat tiedot päivitetään vastaamaan Kiinteistörekisterin kulloistakin rekisteritilannetta.
Normaalitilanteessa palvelusta tarjottavat tiedot vastaavat Kiinteistörekisterin rekisteritilannetta. Palvelusta tarjottavien tietojen ajantasaisuutta Kiinteistörekisteriin nähden kuvaa rekisteritilanteen tiedot.
Rekisteritilanteen tiedot esitetaan .json-formaatissa meta-osiossa: .
- rekisteritilanneAjantasalla
- onko tieto ajantasalla Kiinteistörekisteriin nähden
- rekisteritilannepvm
- se virallinen Kiinteistörekisterin rekisteröintipäivämäärä, jonka mukaisia tiedot ovat
Tuotteet
Palvelu sisältää alla olevassa taulukossa esitellyt avoimet tuotteet. Taulukossa tuotteiden tietosisältö on kuvattu UML-kaavioina. UML-kaavioiden 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. UML-kaavioissa attribuuttien tyyppeinä esiintyy koodistoja esim. Rajamerkkilaji, jotka sisältyvät Kiinteistötietojärjestelmän kiinteistörekisterin koodistoihin (.pdf).
Tuotteista löytyy lisäksi esimerkit .json-formaatissa otsikon Rajapinnan kyselypalvelutuotteet alta.
| Tuote | Kuvaus | Tiedot |
|---|---|---|
| Rajamerkin sijaintitiedot | rajamerkin sijainti ja muut tiedot esim. numero ja tasosijaintitarkkuus Rajamerkin tasosijaintitarkkuus on tasosijainnin (pohjois- ja itäkoordinaatit) pistekeskivirhe metreinä. | UML-kaavio |
| Kiinteistörajan sijaintitiedot | kiinteistörajan sijainti ja muut tiedot esim. kiinteistörajalaji ja interpolointitapa | UML-kaavio |
| Kiinteistötunnuksen sijaintitiedot | palstan kiinteistötunnuksen sijainti, kiinteistötunnus ja kiinteistötunnuksen esitysmuoto | UML-kaavio |
| Palstan sijaintitiedot | palstan sijainti ja palstan kiinteistötunnuksen sijainti, kiinteistötunnus ja kiinteistötunnuksen esitysmuoto | UML-kaavio |
| Palstan laajat sijaintitiedot | palstan sijainti ja palstan kiinteistötunnuksen sijainti, kiinteistötunnus ja kiinteistötunnuksen esitysmuoto, sekä palstan kiinteistörajat ja kuhunkin kiinteistörajaan liittyvät rajamerkit sijainti- ja ominaisuustietoineen | UML-kaavio |
| Projisoidun palstan kiinteistötunnuksen sijaintitiedot | projisoidun palstan kiinteistötunnuksen sijainti, kiinteistötunnus ja kiinteistötunnuksen esitysmuoto ja lisäksi rekisteriyksikön suhde peruskiinteistöön Projisoitu palsta on 3D-kiinteistön vaakatasoon projisoitu palsta. | UML-kaavio |
| Projisoidun palstan sijaintitiedot | projisoidun palstan sijainti ja kiinteistötunnuksen sijainti, kiinteistötunnus ja kiinteistötunnuksen esitysmuoto ja lisäksi rekisteriyksikön suhde peruskiinteistöön Projisoitu palsta on 3D-kiinteistön vaakatasoon projisoitu palsta. | UML-kaavio |
| Rekisteriyksikön laajat sijaintitiedot | kiinteistötunnus, kiinteistötunnuksen esitysmuoto, olotila, suhde peruskiinteistöön sekä 2D-kiinteistön palstat ja kuhunkin palstaan liittyvät kiinteistörajat ja kuhunkin kiinteistörajaan liittyvät rajamerkit sijainti- ja ominaisuustietoineen tai 3D-kiinteistöjen osalta rekisteriyksikön projisoitu palsta sijainti-ja ominaisuustietoineen | UML-kaavio |
| Rekisteriyksikön avoimet ominaisuustiedot | kiinteistötunnus, kiinteistötunnuksen esitysmuoto, olotila, suhde peruskiinteistöön, rekisteröintipäivämäärä, mahdollinen lakkaamispäivämäärä, rekisteriyksikön kuntatiedot (rekisteriyksikön nykyisen sijaintikunnan ominaisuustiedot), 3D-kiinteistöistä ylin ja alin korkeus sekä lisäksi 3D-kiinteistöjen osalta ja peruskiinteistöjen osalta yläpuolisten ja alapuolisten rekisteriyksiköiden kiinteistötunnukset Tuote ei sisällä sijaintitietoja. | UML-kaavio |
| Rekisteriyksikön sijaintikuntatiedot | rekisteriyksikön nykyisen sijaintikunnan ominaisuustiedot sekä mahdollisten aiempien sijaintikuntien ominaisuustiedot vuodesta 2014 lähtien Tuote ei sisällä sijaintitietoja. | UML-kaavio |
| Määräalan osan sijaintitiedot | mm. määräalan osan sijainti ja määräalatunnuksen sijainti, määräalatunnus ja määräalatunnuksen esitysmuoto ja lisäksi määräalan suhde peruskiinteistöön Määräalan osan sijainti voi olla joko pistegeometria tai aluegeometria. | UML-kaavio |
Rajapinnan kyselypalvelutuotteet
OGC API Features-rajapintapalvelun tarjoamat avoimet kyselypalvelutuotteet esimerkkeineen (GeoJSON). Taulukossa on lisäksi kerrottu, onko tuote Simple-tyyppinen.
Esimerkkilinkit edellyttävät käyttäjätunnistusta.
| Tuote | Esimerkkikohteita | FeatureCollection tunniste (OGC API Features) | Simple? |
|---|---|---|---|
| Rajamerkin sijaintitiedot | GeoJSON | RajamerkinSijaintitiedot | X |
| Kiinteistörajan sijaintitiedot | GeoJSON | KiinteistorajanSijaintitiedot | X |
| Kiinteistötunnuksen sijaintitiedot | GeoJSON | KiinteistotunnuksenSijaintitiedot | X |
| Palstan sijaintitiedot | GeoJSON | PalstanSijaintitiedot | X |
| Palstan laajat sijaintitiedot | GeoJSON | PalstanLaajatSijaintitiedot | |
| Projisoidun palstan kiinteistötunnuksen sijaintitiedot | GeoJSON | ProjisoidunPalstanKiinteistotunnuksenSijaintitiedot | X |
| Projisoidun palstan sijaintitiedot | GeoJSON | ProjisoidunPalstanSijaintitiedot | X |
| Rekisteriyksikön laajat sijaintitiedot | GeoJSON (2D-kiinteistö) GeoJSON (3D-kiinteistö) | RekisteriyksikonLaajatSijaintitiedot | |
| Rekisteriyksikön avoimet ominaisuustiedot | GeoJSON (2D-kiinteistö) GeoJSON (3D-kiinteistö) | RekisteriyksikonAvoimetOminaisuustiedot | |
| Rekisteriyksikön sijaintikuntatiedot | GeoJSON | RekisteriyksikonSijaintikuntatiedot | |
| Määräalan osan sijaintitiedot | GeoJSON (pistegeometria) GeoJSON (aluegeometria) | MaaraalanOsanSijaintitiedot | X |
Palvelun koodilistat löytyvät luettelopalvelusta osoitteesta:
http://www.luettelopalvelu.fi/codelist/KTJkii
Koodistoarvojen käännökset löytyvät suomeksi ja ruotsiksi.
Koodistoja käytetään sekä hakuparametreissa että vastausten kohteiden ominaisuuksissa.
Kyselyt ja esimerkit
Palvelussa tuetaan sijainnilla kyselyistä bbox-kyselyt (suorakaiderajaus).
Lisäksi on käytössä OGC API - Features - Part 3 luonnoksen mukaiset monipuoliset sijaintihakumahdollisuudet.
Käytössä olevia Part 3 mukaisia sijaintirajauksia:
- piste (point)
- piste ja annettu säde (point with radius)
- viiva (linestring)
- 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. Kullekin tuotteelle tarjolla olevat ominaisuushakuehdot kuvauksineen löytyvät API-kuvauksesta.
Kyselyparametreja voi vapaasti yhdistellä.
Esimerkkikyselyitä löytyy myöhemmin tästä luvusta.
Sijaintikyselyt ovat käytettävissä kaikille muille tuotteille paitsi RekisteriyksikonSijaintikuntatiedot
Osoitteen https://sopimus-paikkatieto.maanmittauslaitos.fi/kiinteisto-avoin/simple-features/v3/ kautta on tarjolla kaikki ne Simple-tuotteet, joita voi kysellä sijainnilla ja joiden vastaus sisältää geometrian. Tätä osoitetta kannattaa käyttää, jos asiakassovelluksessa keskeisintä on kiinteistöjaotuksen (sisältäen myös määräalat) sijaintitietojen esittäminen.
Yhteensopivuus ja tuotteet
Palvelu on yhteensopiva OGC API - Features - standardin kanssa (https://ogcapi.ogc.org/features/).
Kuvaukset saatavissa Open API mukaisina kuvauksina.
Avoin, Simple:
Palveluosoite (landing page):
https://sopimus-paikkatieto.maanmittauslaitos.fi/kiinteisto-avoin/simple-features/v3/
Tuetut yhteensopivuusluokat (conformance classes):
https://sopimus-paikkatieto.maanmittauslaitos.fi/kiinteisto-avoin/simple-features/v3/conformance
Palvelun tarjoamat tuotteet (collections) ja tuetut koordinaatistot:
https://sopimus-paikkatieto.maanmittauslaitos.fi/kiinteisto-avoin/simple-features/v3/collections
API-kuvaus (Open API 3.0-spesifikaation mukainen kuvaus):
https://sopimus-paikkatieto.maanmittauslaitos.fi/kiinteisto-avoin/simple-features/v3/api
Avoin, kaikki:
Palveluosoite (landing page):
https://sopimus-paikkatieto.maanmittauslaitos.fi/kiinteisto-avoin/features/v3/
Tuetut yhteensopivuusluokat (conformance classes):
https://sopimus-paikkatieto.maanmittauslaitos.fi/kiinteisto-avoin/features/v3/conformance
Palvelun tarjoamat tuotteet (collections) ja tuetut koordinaatistot:
https://sopimus-paikkatieto.maanmittauslaitos.fi/kiinteisto-avoin/features/v3/collections
API-kuvaus (Open API 3.0-spesifikaation mukainen kuvaus):
https://sopimus-paikkatieto.maanmittauslaitos.fi/kiinteisto-avoin/features/v3/api
Koodistot
Koodilistat löytyvät luettelopalvelusta osoitteesta:
http://www.luettelopalvelu.fi/codelist/KTJkii
OGC API Features palvelun käyttäminen
Tässä on lyhyt ohje kuinka käyttää OGC API Features rajapintapalvelua, esimerkkitapauksissa on käytetty tuotteita PalstanSijaintitiedot ja RekisteriyksikonAvoimetOminaisuustiedot. Open API kuvauksessa on kuvattu tarkemmin eri tuotteille mahdolliset palvelupyynnöt ja niiden hakuparametrit.
Esimerkkitapauksissa on käytetty palveluosoitteena kaikkien avoimien tuotteiden osoitetta: https://sopimus-paikkatieto.maanmittauslaitos.fi/kiinteisto-avoin/features/v3/
Paikkatietokohteen haku tunnisteella
Vastaus on GeoJSON-muotoista:
Vastausten sivutus
OGC API Features rajapinnan mukaisesti toteutettuna palvelussa on hyvä tuki kohteiden kokoelmien sivutukselle. Esimerkiksi seuraava kysely palauttaa osajoukon PalstanSijaintitiedot- kokoelmasta eli ensimmäiset 100 kohdetta:
Vastauksena tulee siis nuo 100 kohdetta sekä vastauksen lopussa myös kyselylinkki seuraaviin 100 kohteeseen, esim.:
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 kaikenkaikkiaan 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 Espoon (kuntatunnus=049) voimassaolevista (olotila=1) rekisteriyksiköistä avoimet ominaisuustiedot. Tehdään HEAD-kysely:
curl -u USERNAME:PASSWD -I "https://sopimus-paikkatieto.maanmittauslaitos.fi/kiinteisto-avoin/features/v3/collections/RekisteriyksikonAvoimetOminaisuustiedot/items?kuntatunnus=049&olotila=1"
Kysely on maksuton.
Koordinaatistot ja suorakaiderajaukset
Oletuksena bbox-suorakaiderajaus ja vastauksena palautettavien paikkatietokohteiden geometriat sisältävät WGS 84 koordinaatteja (CRS80), esimerkiksi:
Rajaaminen ETRS-TM35FIN koordinaateilla (EPSG:3067) tehdään bbox-crs parametrin avulla:
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:
Tuettujen koordinaatistojen tunnisteet on lueteltu:
https://sopimus-paikkatieto.maanmittauslaitos.fi/kiinteisto-avoin/features/v3/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 PalstanSijaintitiedot-kohteita annetulla vapaalla aluerajauksella (POLYGON). Sijaintirajaus on annettu ETRS-TM35 koordinaatistossa. Myös vastaus halutaan ETRS-TM35 koordinaatistoon.
Vastauksena saadaan kaikki PalstanSijaintitiedot-kohteet, jotka leikkaavat tai koskettavat annettua vapaata aluerajausta.
Toisessa esimerkissä on käytetty S_INTERSECTS-sijaintioperaatiota ja haetaan RekisteriyksikonAvoimetOminaisuustiedot-kohteita annetun säteen etäisyydeltä (100 m) annetusta pisteestä (POINT). Sijaintirajaus on annettu ETRS-TM35 koordinaatistossa. RekisteriyksikonAvoimetOminaisuustiedot-tuote ei sisällä vastauksessaan sijaintitietoja, joten vastauskoordinaatistolla ei ole merkitystä.
Vastauksena saadaan kaikki RekisteriyksikonAvoimetOminaisuustiedot-kohteet, jotka leikkaavat tai koskettavat aluetta, joka on 100 m etäisyydellä annetusta pisteestä.
Rajaus ominaisuustiedoilla
Tämä esimerkki hakee kiinteistotunnus-parametria käyttäen yhden rekisteriyksikön kaikki palstat (PalstanSijaintitiedot-kohteet):
Useamman rekisteriyksikön palstat (PalstanSijaintitiedot-kohteet) voidaan hakea yhdellä kyselyllä listaamalla kiinteistötunnukset pilkulla erotettuna (jolloin arvojen käsittely toimii OR-operaation mukaisesti, tässä esimerkissä siis "17440100030006" tai "29751000120195"):
Tämä esimerkki hakee kiinteistotunnuksenEsitysmuoto-parametria käyttäen yhden rekisteriyksikön kaikki palstat (PalstanSijaintitiedot-kohteet):
Lisää hakuesimerkkejä eri käyttötapauksiin sovitettuna löytyy alasvetovalikosta Esimerkkejä.
Versiohallinta
Tuotantojulkaisu 28.11.2023
- Koordinaatiston EPSG:4326 axis order EPSG-standardin mukaiseksi. Jos asiakassovelluksessa pyydetään crs-parametria käyttäen tulostusta EPSG:4326-koordinaatistoon, niin koordinaatit tulostuvat vastaukseen jatkossa järjestyksessä NE. Mikäli tekee sijaintikyselyitä koordinaatistossa EPSG:4326 käyttäen parametria bbox-crs tai filter-crs, niin koordinaatit annetaan kyselyyn jatkossa järjestyksessä NE.
- Muiden koordinaatistojen osalta ei tapahdu muutoksia. Myös oletuskoordinaatiston CRS84 osalta ei tapahdu mitään muutosta.
Bugikorjaus 22.11.2022 PalstanLaajatSijaintitiedot-tuotteella ja RekisteriyksikonLaajatSijaintitiedot-tuotteella alikohteiden geometriat (kiinteistörajojen ja rajamerkkien geometriat) eivät tulleet pyydettyyn koordinaatistoon (oletuskoordinaatistoon tai annettuun koordinaatistoon), vaan ne tulostettiin virheellisesti aina koordinaatistoon EPSG:3067.
Bugikorjaus 24.8.2022. PalstanLaajatSijaintitiedot-tuotteen vastauksesta oli palstalta saattanut jäädä puuttumaan kiinteistörajoja (laajatSijaintitiedotKiinteistoraja-elementtejä) tietoineen
Tuotantojulkaisu 6/2022
Esimerkkejä
1) Sijaintitietojen kyselyesimerkkejä
Tuote KiinteistotunnuksenSijaintitiedot
Kiinteistötunnuksien selailu kartalla: kiinteistötunnukset bbox-suorakaiderajauksella (ETRS-TM35FIN koordinaateilla)
Tuote KiinteistorajanSijaintitiedot
Kiinteistörajojen selailu kartalla: kiinteistörajat bbox-suorakaiderajauksella (ETRS-TM35FIN koordinaateilla)
Rekisteriyksikön 17440100030006 kiinteistörajat
Tuote RajamerkinSijaintitiedot
Rekisteriyksikön 17440100030006 rajamerkit
Tuote PalstanSijaintitiedot
Rekisteriyksikön 17440100030006 palstat (PalstanSijaintitiedot-kohteet)
Annetun palstan naapuripalstat (kun palstan id on 181000363)
Palsta annetussa pisteessä (ETRS-TM35FIN koordinaateilla)
Tuote MaaraalanOsanSijaintitiedot
Määräalan osat kiinteistötunnuksella
Määräalan osat määräalatunnuksella
Määräalan osien selailu kartalla: määräalan osat bbox-suorakaiderajauksella (ETRS-TM35FIN koordinaateilla)
Kyselyesimerkkejä, tuote RekisteriyksikonLaajatSijaintitiedot
Rekisteriyksikön 17440100030006 palstat, kunkin palstan kiinteistörajat ja kunkin kiinteistörajan rajamerkit
2) Lisää kyselyesimerkkejä tuotteittain
Tuote RekisteriyksikonAvoimetOminaisuustiedot
Rekisteriyksikön avoimet ominaisuustiedot rekisteriyksiköstä 17440100030006.
Rekisteriyksikön avoimet ominaisuustiedot rekisteriyksiköistä, jotka leikkaavat tai koskettavat annettua vapaamuotoista aluerajausta. (ETRS-TM35FIN koordinaateilla kysyttynä)
Rekisteriyksikön avoimet ominaisuustiedot Espoon voimassaolevista rekisteriyksiköistä. Selvitetään ensin, kuinka monta kohdetta rajausehtoihin osuu.
Halutaan ensin tietää, kuinka monta kohdetta ko. rajausehtoihin kaikenkaikkiaan osuisi:
curl -u USERNAME:PASSWD -I "https://sopimus-paikkatieto.maanmittauslaitos.fi/kiinteisto-avoin/features/v3/collections/RekisteriyksikonAvoimetOminaisuustiedot/items?kuntatunnus=049&olotila=1"
Kohteiden määrä saadaan kyselystä palautuvasta OGC-NumberMatched arvosta
Saatu OGC-NumberMatched arvo on esimerkiksi 34171. Pyydetään niin monta kohdetta ensimmäiseen osajoukkoon kuin mahdollista eli maksimi limit mukainen määrä (10000). Käytetään maksimi arvoa, koska se on tähän käyttötapaukseen sopiva.
Jotta saadaan seuraavat 10000 kohdetta, tehdään uusi kysely saadun vastauksen lopussa olevan kyselylinkin avulla esim.
jne.
Kaikki kohteet saa siis tässä esimerkissä palautettua tekemällä neljä kyselyä.