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

Palvelusta on julkaistu 3/2021 BETA-versiona kiinteistöjaotuksen avoimet tuotteet.

Rajapintapalvelu on saatavilla OGC API Features-standardin mukaisena osoitteestahttps://beta-paikkatieto.maanmittauslaitos.fi/kiinteisto-avoin/features/v1/

Rajapinnan tietotuotteet ovat muotoa GeoJSON 

Oletuskoordinaatisto OGC API Features ja GeoJSON spesifikaatioiden mukaisesti on WGS 84 maantieteelliset koordinaatit. Palvelu tukee myös ETRS-TM35FIN, ETRS-TM34..36 ja ETRS-GK19..31FIN projisoituja koordinaatistoja, ETRS89 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

API-kuvaus OpenAPI-muotoisena:
https://beta-paikkatieto.maanmittauslaitos.fi/kiinteisto-avoin/features/v1/api

Aineisto

Palvelun data on testidataa ja sitä ei saa käyttää muihin tarkoituksiin kuin BETA-palvelun (julkaisu 03/2021) kokeilemiseen.

 

Tuotteet

BETA-julkaisu 03/2021 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).

Jo julkaistuista avoimista tuotteista löytyy  lisäksi esimerkit .json-formaatissa otsikon Rajapinnan kyselypalvelutuotteet alta.

Palvelussa myöhemmin julkaistavat tuotteet on esitelty otsikon Tulevat tuotteet alla.

 

Jokaiseen tuotteeseen tulevat myöhemmin sisältymään seuraavat tiedot (KTJkiiTPRekisteritilanne) . Nämä tiedot eivät ole mukana vielä BETA 03/2021 julkaisussa.

  • rekisteritilanneAjantasalla
    • onko tieto ajantasalla Kiinteistörekisteriin nähden
  • rekisteritilannepvm
    • se virallinen Kiinteistörekisterin rekisteröintipäivämäärä, jonka mukaisia tiedot ovat

 

Avoimet tuotteet 
Tuote Kuvaus Tiedot

Rajamerkin sijaintitiedot

rajamerkin sijainti ja muut tiedot esim. numero ja  tasosijaintitarkkuus 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 

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 tiedot), 3D-kiinteistöistä ylin ja alin korkeus

lisäksi 3D-kiinteistöjen osalta ja peruskiinteistöjen osalta yläpuolisten ja alapuolisten rekisteriyksiköiden kiinteistötunnukset

UML-kaavio

Rekisteriyksikön sijaintikuntatiedot

rekisteriyksikön nykyisen sijaintikunnan tiedot sekä mahdollisten aiempien sijaintikuntien tiedot vuodesta 2014 lähtien  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 kyselypalvelutuotteet BETA 03/2021 julkaisussa:

 

Avoimet tuotteet

Tuote

Esimerkkikohteita

FeatureCollection tunniste (OGC API Features)

Huomioita
Rajamerkin sijaintitiedot GeoJSON RajamerkinSijaintitiedot  
Kiinteistörajan sijaintitiedot GeoJSON KiinteistorajanSijaintitiedot  
Kiinteistötunnuksen sijaintitiedot GeoJSON KiinteistotunnuksenSijaintitiedot  
Palstan sijaintitiedot GeoJSON PalstanSijaintitiedot  
Palstan laajat sijaintitiedot GeoJSON PalstanLaajatSijaintitiedot json rakenne paremmin standardia vastaavaksi 03/2021 julkaisun jälkeen
Projisoidun palstan kiinteistötunnuksen sijaintitiedot GeoJSON ProjisoidunPalstanKiinteistotunnuksenSijaintitiedot  
Projisoidun palstan sijaintitiedot GeoJSON ProjisoidunPalstanSijaintitiedot  
Rekisteriyksikön laajat sijaintitiedot

GeoJSON (2D-kiinteistö)

GeoJSON (3D-kiinteistö)

RekisteriyksikonLaajatSijaintitiedot json rakenne paremmin standardia vastaavaksi 03/2021 julkaisun jälkeen
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  

 

03/2021 BETA-julkaisun 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.

 

Tulevat tuotteet

Luvanvaraiset tuotteet
Tuote Kuvaus Tiedot

Rekisteriyksikön perustiedot

mm. kiinteistötunnus, kiinteistötunnuksen esitysmuoto, olotila, nimi, rekisteriyksikkölaji, suhde peruskiinteistöön, rekisteröintipäivämäärä, mahdollinen lakkaamispäivämäärä, pinta-alatiedot sekä rekisteriyksikön kuntatiedot

UML-kaavio

Rekisteriyksikön 3D-ominaisuustiedot

kiinteistötunnus, kiinteistötunnuksen esitysmuoto, olotila, suhde peruskiinteistöön, 3D-kiinteistöistä projisoitu pinta-ala sekä ylin ja alin korkeus

lisäksi 3D-kiinteistöjen osalta ja peruskiinteistöjen osalta yläpuolisten ja alapuolisten rekisteriyksiköiden kiinteistötunnukset

UML-kaavio

Määräalan perustiedot

mm. määräalatunnus, määräalatunnuksen esitysmuoto, olotila, määräalan tyyppi (määräala vai erillisenä luovutettu yhteisalueosuus), suhde peruskiinteistöön, rekisteröintipäivämäärä, mahdollinen lakkaamispäivämäärä, määräalan vaihe (esim. erottamaton, muodostettu osittain rekisteriyksiköksi), määräalan sijaintirekisteriyksikkö sekä määräalan luovuttajarekisteriyksikkö tai luovuttajamääräala sekä määräalan sijaintikunnan tiedot

määräalan alkuperäisen saannon mukaiset pinta-alat ovat laillistumattomia, eivätkä ole kiinteistörekisteritietoja, mutta ne esitetään informatiivisina tietoina

UML-kaavio

Rekisteriyksiköt hakuehdoin

Tuotteella esitetään vain kiinteistötunnus ja kiinteistötunnuksen esitysmuoto. Tuote on tarkoitettu käytettäväksi esim. tilanteessa, jossa ennen yksityiskohtaisempien tuotteiden hakua halutaan tämän tuotteen avulla etsiä kiinnostavia kohteita. UML-kaavio

Määräalat hakuehdoin

Tuotteella esitetään vain määräalatunnus ja määräalatunnuksen esitysmuoto. Tuote on tarkoitettu käytettäväksi esim. tilanteessa, jossa ennen yksityiskohtaisempien tuotteiden hakua halutaan tämän tuotteen avulla etsiä kiinnostavia kohteita.

UML-kaavio

 

 

 

 

 

Palvelusta on julkaistu 3/2021 BETA-versiona kiinteistöjaotuksen avoimet tuotteet.

Palvelun data on testidataa ja sitä ei saa käyttää muihin tarkoituksiin kuin tämän BETA-palvelun kokeilemiseen.

BETA 03/2021 julkaisussa tuetaan sijainnilla kyselyistä bbox-kyselyt (suorakaiderajaus). Myöhemmissä julkaisuissa tulee käyttöön muitakin tapoja tehdä sijaintikysely.

Yhteensopivuus ja tuotteet

Kehitettäessä OGC API Features asiakassovelluksia kannattaa ensin tutustua OGC API - Features - standardiin (Part 1: Core ja Part 2: Coordinate Reference Systems by Reference) (https://www.ogc.org/standards/ogcapi-features) 

Tämä OGC API Features palvelu on yhteensopiva standardin kanssa.

Palveluosoite (landing page):
https://beta-paikkatieto.maanmittauslaitos.fi/kiinteisto-avoin/features/v1/

Tuetut yhteensopivuusluokat (conformance classes):
https://beta-paikkatieto.maanmittauslaitos.fi/kiinteisto-avoin/features/v1/conformance

Palvelun tarjoamat tuotteet (collections) ja tuetut koordinaatistot:
https://beta-paikkatieto.maanmittauslaitos.fi/kiinteisto-avoin/features/v1/collections

Open API kuvaukset

Open API kuvauksessa on kerrottu tarkemmin kuinka palvelusta voidaan hakea metatietoa ja kiinteistörekisterin mukaisia kohteita OGC API Features mukaisilla palvelupyynnöillä:

API-kuvaus (Open API 3.0-spesifikaation mukainen kuvaus)
https://beta-paikkatieto.maanmittauslaitos.fi/kiinteisto-avoin/features/v1/api

Koodistot

03/2021 BETA-julkaisun 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, esimerkkitapauksena tuote PalstanSijaintitiedot. Open API kuvauksessa on kuvattu tarkemmin eri tuotteille mahdolliset palvelupyynnöt ja niiden hakuparametrit.

Paikkatietokohteen haku tunnisteella

Vastaus on GeoJSON-muotoista: 

https://beta-paikkatieto.maanmittauslaitos.fi/kiinteisto-avoin/features/v1/collections/PalstanSijaintitiedot/items/56119275?

 

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:

https://beta-paikkatieto.maanmittauslaitos.fi/kiinteisto-avoin/features/v1/collections/PalstanSijaintitiedot/items?limit=100

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

https://beta-paikkatieto.maanmittauslaitos.fi/kiinteisto-avoin/features/v1/collections/PalstanSijaintitiedot/items?next=MDoxMzUwMzcxNw%3D%3D&limit=100

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

Koordinaatistot ja suorakaiderajaukset

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

https://beta-paikkatieto.maanmittauslaitos.fi/kiinteisto-avoin/features/v1/collections/PalstanSijaintitiedot/items?&bbox=22.15,63.45,22.2,63.5

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

https://beta-paikkatieto.maanmittauslaitos.fi/kiinteisto-avoin/features/v1/collections/PalstanSijaintitiedot/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:

https://beta-paikkatieto.maanmittauslaitos.fi/kiinteisto-avoin/features/v1/collections/PalstanSijaintitiedot/items?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://beta-paikkatieto.maanmittauslaitos.fi/kiinteisto-avoin/features/v1/collections

Rajaus ominaisuustiedoilla

Tämä esimerkki hakee kiinteistotunnus-parametria käyttäen yhden rekisteriyksikön  kaikki palstat (PalstanSijaintitiedot-kohteet):

https://beta-paikkatieto.maanmittauslaitos.fi/kiinteisto-avoin/features/v1/collections/PalstanSijaintitiedot/items?kiinteistotunnus=49540700010010

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 "49540700010010 tai 49540700200011"):

https://beta-paikkatieto.maanmittauslaitos.fi/kiinteisto-avoin/features/v1/collections/PalstanSijaintitiedot/items?kiinteistotunnus=49540700010010,49540700200011

Tämä esimerkki hakee kiinteistotunnuksenEsitysmuoto-parametria käyttäen yhden rekisteriyksikön  kaikki palstat (PalstanSijaintitiedot-kohteet):

https://beta-paikkatieto.maanmittauslaitos.fi/kiinteisto-avoin/features/v1/collections/PalstanSijaintitiedot/items?kiinteistotunnuksenEsitysmuoto=495-407-1-10

Lisää hakuesimerkkejä eri käyttötapauksiin sovitettuna alempana kohdassa Esimerkkejä.

 

Tulossa 03/2021 (BETA)

Palvelun data on testidataa ja sitä ei saa käyttää muihin tarkoituksiin kuin tämän BETA-palvelun (julkaisu 03/2021) kokeilemiseen.

 

 

Kyselyesimerkkejä, tuote KiinteistotunnuksenSijaintitiedot

Kiinteistötunnuksien selailu kartalla: kiinteistötunnukset bbox-suorakaiderajauksella (ETRS-TM35FIN koordinaateilla )

GeoJSON: https://beta-paikkatieto.maanmittauslaitos.fi/kiinteisto-avoin/features/v1/collections/KiinteistotunnuksenSijaintitiedot/items?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

Kyselyesimerkkejä, tuote KiinteistorajanSijaintitiedot

Kiinteistörajojen selailu kartalla: kiinteistörajat bbox-suorakaiderajauksella  (ETRS-TM35FIN koordinaateilla )

GeoJSON: https://beta-paikkatieto.maanmittauslaitos.fi/kiinteisto-avoin/features/v1/collections/KiinteistorajanSijaintitiedot/items?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

Rekisteriyksikön 49540700010010 kiinteistörajat

GeoJSON: https://beta-paikkatieto.maanmittauslaitos.fi/kiinteisto-avoin/features/v1/collections/KiinteistorajanSijaintitiedot/items?kiinteistotunnus=49540700010010

Kyselyesimerkkejä, tuote RajamerkinSijaintitiedot

Rekisteriyksikön 49540700010010 rajamerkit

GeoJSON: https://beta-paikkatieto.maanmittauslaitos.fi/kiinteisto-avoin/features/v1/collections/RajamerkinSijaintitiedot/items?kiinteistotunnus=49540700010010

Kyselyesimerkkejä, tuote PalstanSijaintitiedot

Rekisteriyksikön 49540700010010 palstat  (PalstanSijaintitiedot-kohteet):

https://beta-paikkatieto.maanmittauslaitos.fi/kiinteisto-avoin/features/v1/collections/PalstanSijaintitiedot/items?kiinteistotunnus=49540700010010

Annetun palstan naapuripalstat  (kun palstan id on 181000363)

GeoJSON:https://beta-paikkatieto.maanmittauslaitos.fi/kiinteisto-avoin/features/v1/collections/PalstanSijaintitiedot/items?naapuripalstat=181000363  

 

Kyselyesimerkkejä, tuote MaaraalanOsanSijaintitiedot

Määräalan osat kiinteistötunnuksella

GeoJSON: https://beta-paikkatieto.maanmittauslaitos.fi/kiinteisto-avoin/features/v1/collections/MaaraalanOsanSijaintitiedot/items?kiinteistotunnus=56042500030030

Määräalan osat määräalatunnuksella

GeoJSON: https://beta-paikkatieto.maanmittauslaitos.fi/kiinteisto-avoin/features/v1/collections/MaaraalanOsanSijaintitiedot/items?maaraalatunnus=01540100030030M0602

Määräalan osat halutulla bbox-suorakaiderajauksella (ETRS-TM35FIN koordinaateilla )

GeoJSON:https://beta-paikkatieto.maanmittauslaitos.fi/kiinteisto-avoin/features/v1/collections/MaaraalanOsanSijaintitiedot/items?bbox=373652,6674759,373739,6674859&bbox-crs=http://www.opengis.net/def/crs/EPSG/0/3067&crs=http://www.opengis.net/def/crs/EPSG/0/3067

 

Kyselyesimerkkejä, tuote RekisteriyksikonLaajatSijaintitiedot

Rekisteriyksikön 49540700010010 palstat, kunkin palstan kiinteistörajat ja kunkin kiinteistörajan rajamerkit

GeoJSON: https://beta-paikkatieto.maanmittauslaitos.fi/kiinteisto-avoin/features/v1/collections/RekisteriyksikonLaajatSijaintitiedot/items?kiinteistotunnus=49540700010010

Kyselyesimerkkejä, tuote RekisteriyksikonAvoimetOminaisuustiedot

Tuotteen tiedot rekisteriyksiköstä 49540700010010.

GeoJSON: https://beta-paikkatieto.maanmittauslaitos.fi/kiinteisto-avoin/features/v1/collections/RekisteriyksikonAvoimetOminaisuustiedot/items?kiinteistotunnus=49540700010010