Tekninen kuvaus - Rakennukset (OGC API Features)

Palvelu tarjoaa OGC API Features -kyselyrajapinnan rakennuksien ja rakennuksen osien paikkatietokohteille, jotka on tallennettu Kansalliseen maastotietokannan (KMTK) rakennukset ja rakennelmat -teeman mukaiseen tietovarastoon.

Rajapintapalvelu tarjotaan maksuttomana ja Maanmittauslaitoksen avoimen rajapintapalvelun käyttöehtojen mukaisesti. Rajapinnan käyttö vaatii API-avaimen liittämistä pyyntöihin. Ohjeet tähän löydät sivulta Avoimet rajapintapalvelut. Rajapintapalvelu on saatavilla osoitteesta: https://avoin-paikkatieto.maanmittauslaitos.fi/buildings/features/v1/

Rajapintapalvelu perustuu OGC API - Features - Part 1: Core (http://docs.opengeospatial.org/DRAFTS/17-069r1.html) -standardiin ja rajapinnan tekninen kuvaus on julkaistu Open API 3.0.1 spesifikaation mukaisena. Paikkatietokohteita voidaan hakea id-tunnisteilla ja suorakaiderajauksella (bbox). Vastaukset palautetaan GeoJSON-tiedostomuodossa.

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 sekä ETRS89 maantieteellistä koordinaatistoa.

Osa kyselyparametreista ja paikkatietokohteiden ominaisuustiedoista on mallinnettu koodistoarvoina, joiden selitystekstit on julkaistu erillisen luettelopalvelun kautta.

Aineistolähteet ja käsitemallit

Kyselypalvelun aineistolähteenä on Kansalliseen maastotietokantaan (KMTK) tallennetut kuntien ja Maanmittauslaitoksen rakennusaineistot. Aineisto on Suomen kattavaa. Palvelun kautta tarjottaville rakennuksille ei toistaiseksi olla lisätty ominaisuustietoja.

Kyselypalvelussa tietotuotteet ovat tarjolla GeoJSON mukaisissa tietorakenteissa, joiden mallinnuksessa on huomioitu myös KMTK:n rakennukset ja rakennelmat -teeman käsitemallit. Käsitemallissa rakennus on määritelty seuraavasti:

Rakennus: Vapaasti seisova, itsekantava, pysyvä, maan päällä tai maan alla oleva rakenne, joka on tarkoitettu ihmisten oleskeluun (esim. työ- tai vapaa-ajankäyttö), asumista varten ja/tai suojaksi ihmisille, eläimille tai tavaroille. (Määritelmä ”maan päällä tai maan alla” on INSPIRE:n ja CityGML:n mukainen.)

RakennuksenOsa: Rakennuksen osat, jotka lasketaan mukaan ominaisuustiedoissa ilmoitettuihin arvoihin. RakennuksenOsa-kohteita tarvitaan silloin, kun rakennuksen osilla on toisistaan poikkeavia ominaisuustietoja. Rakennus-kohde koostuu RakennuksenOsa-kohteista. Jo yksi RakennuksenOsa muodostaa Rakennus-kohteen.

RakennuksenVaruste: Rakennuksen pienemmät ulokkeet, esimerkiksi parvekkeet. Eivät voi itsenäisesti muodostaa Rakennus-kohdetta.

 

GeoJSON-skeemat

Kyselypalvelua varten on mallinnettu kaksi GeoJSON-skeemaa, Building ja BuildingPart, jotka vastaavat käsitemallin Rakennus ja RakennuksenOsa kohteita. Skeemoissa on mukana käsitemallissa kuvatut rakennusten osien 2,5D-pintageometriat, mutta ei esim. 3D-geometrioita. Skeemojen tietorakenteet ja attribuutit on määritelty käyttäen englanninkielisiä tunnisteita kun käsitemallissa kohdeluokat, niiden sisältämät osakohteet ja ominaisuustiedot on puolestaan määritelty käyttäen suomenkielisiä tunnisteita. Skeemojen sisältämillä attribuuteilla on joka tapauksessa vastaavuus käsitemallin ominaisuustietoihin, joten käsitemalli toimii yleiskuvauksena myös rajapinnan skeemoja hyödynnettäessä.    

Building on tarkoitettu rakennustiedon yleispiirteiseen esittämiseen. Skeemassa on mukana vain 'Building' -kohdeluokan ominaisuustiedot. Vastaavien 'BuildingPart' -kohteiden geometriat yhdistetään 'Building' -kohteen 'MultiPolygon' -tyyppisen geometrian osapolygoneiksi.

BuildingPart on puolestaan tarkoitettu rakennustiedon yksityiskohtaiseen esittämiseen. Skeemassa on mukana sekä 'Building' -kohdeluokan että 'BuildingPart' -kohdeluokan ominaisuutiedot - yhteiset ominaisuustiedot kuitenkin vain kerran. Yhteisten ominaisuustietojen osalta arvoina käytetään 'BuildingPart' -kohteen arvoja. 'Building' -kohdeluokan mukaiset ominaisuudet erotetaan varsinaisista 'BuildingPart' -ominaisuuksista 'building.' -etuliitteellä. Kullakin 'BuildingPart' -kohteella on oma geometriansa 'MultiPolygon' -geometriatyyppinä.

Kutakin 'BuildingPart' -kohdetta vastaava 'Building' -kohde voidaan löytää käyttäen 'BuildingPart' -kohteelle tallennettua 'Building' -kohteen tunnusta ('building.id').

 

Rajapinnan kyselypalvelutuotteet

Palvelussa on tarjolla kaksi kyselypalvelutuotetta GeoJSON-skeemojen mukaisina voimassa olevien rakennusten tietojen ja kaksi tuotetta rakennusten historiatietojen hakua varten (alla taulukossa esimerkit eri tiedostomuodoissa tuotetaan suoraan rajapinnasta, esimerkkilinkkien käyttö edellyttää käyttäjätunnusta rajapintaan):

Tuote

Esimerkkikohteita

FeatureCollection tunniste (OGC API Features)

FeatureType

Rakennukset GeoJSON buildings Building
Rakennuksen osat GeoJSON building_parts BuildingPart
Rakennukset (historia) GeoJSON buildings_versions Building
Rakennuksen osat (historia) GeoJSON building_parts_versions BuildingPart

Eli samaa Building skeemaa on käytetty sekä buildings- että buildings_versions-kyselypalvelutuotteissa. Ensin mainitusta voidaan hakea vain olemassa olevia kohteita, kun taas jälkimmäisen kautta voidaan hakea myös lakanneita kohteita. Vastaavasti kaksi eri tuotetta tarjolla myös BuildingPart skeemalle.

Koodistot on julkaistu kyselypalvelun rinnalla toimivassa luettelopalvelussa (johon tietosisältö on synkronoitu INSPIRE-koodilistarekisteristä) ja niitä käytetään sekä hakuparameteissa että vastausten paikkatietokohteiden ominaisuuksissa:

Koodilistan nimi suomeksi

Liitty attribuuttiin

Koodilistat

Elinkaaren tila lifecycleStatus fin, eng
Käyttötarkoitus function fin, eng
Käyttötarkoituksen tarkenne functionSpecifier fin, eng
Suhde maanpintaan relationToGround fin, eng
Lämmitystapa heatingType fin, eng
Lämmityspolttoaine heatingFuel fin, eng

 

Huom! Esimerkkilinkkien käyttö edellyttää API-avaimen käyttöä. Lue lisää sivulta Avoimet rajapintapalvelut.

 

Yhteensopivuus ja tuotteet

Kehitettäessä OGC API Features asiakassovelluksia kannattaa ensin tutustua OGC API - Features - Part 1: Core -standardiin (http://docs.opengeospatial.org/is/17-069r3/17-069r3.html)

Tämä OGC API Features palvelu on yhteensopiva standardin kanssa lukuunottamatta seuraavia poikkeuksia ja laajennuksia:

  • laajennus (epävirallinen): laajennettu koordinaatistotuki bbox-suorakaiderajauksissa (crs-bbox parametri) ja vastauksien geometrioissa (crs parametri)

Tuetut yhteensopivuusluokat (conformance classes):

https://avoin-paikkatieto.maanmittauslaitos.fi/buildings/features/v1/conformance

Palvelun tarjoamat tuotteet (collections) ja tuetut koordinaatistot: 

https://avoin-paikkatieto.maanmittauslaitos.fi/buildings/features/v1/collections

 

Open API kuvaukset

Open API 3.0 kuvauksessa on kerrottu tarkemmin kuinka palvelusta voidaan hakea metatietoa ja paikkatietokohteita OGC API Features mukaisilla palvelupyynnöillä:

https://avoin-paikkatieto.maanmittauslaitos.fi/buildings/features/v1/api

 

Luettelopalvelun Codelist API tarjoaa myös indeksisivun jossa on lueteltu palvelun käyttämät koodilistat. Lisätietoa koodilistojen ja koodien selitteiden hakemisesta Open API 3.0 kuvauksesta:

https://beta-paikkatieto.maanmittauslaitos.fi/catalogue/openapi.json

https://beta-paikkatieto.maanmittauslaitos.fi/catalogue/openapi.yaml

Paikkatietokohteiden haku

Lyhyt ohje OGC API Features -palveluiden eri hakutavoista (esim. paikkatietokohteen haku tunnisteella, vastausten sivutus, koordinaatistot ja suorakaiderajaukset, rajaus ominaisuustiedoilla) löytyy Nimistö (OGC API Features)palvelun dokumentaation kohdasta Kyselyt ja esimerkit. Ohjeessa kuvattuja hakutapoja voi soveltaa myös Rakennukset (OGC API Features) -palveluun, toki kohdeluokat skeemoineen ja hakuparametrit ovat tuotekohtaisia.

Alla muutama esimerkkihaku Rakennukset (OGC API Features) palveluun.

Yhden (määrittelemättömän) paikkatietokohteen haku tietystä tuotteesta (tässä collections tunnisteen jälkeen sallitut tuotetunnisteet: buildingsbuildings_partsbuildings_versionsbuildings_parts_versions):

https://avoin-paikkatieto.maanmittauslaitos.fi/buildings/features/v1/collections/buildings/items?limit=1/collections/buildings/items?limit=1

Rakennuksien osakohteiden hakua BBOX-rajauksella (ETRS-TM35FIN) siten että myös vastauksessa rakennuksien osien 2,5D-pintageometriat palautetaan ETRS-TM35FIN-koordinaatiston mukaisina MultiPolygon-geometrioina:

https://avoin-paikkatieto.maanmittauslaitos.fi/buildings/features/v1/collections/building_parts/items?bbox=327273,6822258,327373,6822358&bbox-crs=http://www.opengis.net/def/crs/EPSG/0/3067&crs=http://www.opengis.net/def/crs/EPSG/0/3067

Rakennuskohteen haku kmtkId-tunnisteella (KMTK:n pysyvä ID):

https://avoin-paikkatieto.maanmittauslaitos.fi/buildings/features/v1/collections/buildings/items?kmtkId=00000096-ad45-4b1a-8142-c35fb09ba1f4

Muuttuneiden kohteiden haku buildings_versions tuotteesta:

https://avoin-paikkatieto.maanmittauslaitos.fi/buildings/features/v1/collections/buildings_versions/items?datetime=2020-02-03T00:00:00Z/2020-02-04T00:00:00Z

Tietyn kohteen muutoshistorian haku buildings_versions tuotteesta:

https://avoin-paikkatieto.maanmittauslaitos.fi/buildings/features/v1/collections/buildings_versions/items?kmtkId=7af7e01d-3cb0-49e8-bdd4-82e95dd595a0

Hakuparametreina käytettävissä olevat ominaisuudet on lueteltu kattavammin rajapinnan OpenAPI-kuvauksessa. 

 

Tuotannollinen julkaisu 2020-02

BETA-julkaisu 2019-05 (tämä versio saatavilla vain Paikkatietoalustan kehitys- ja koulutusympäristöön käyttäjiksi liittyneille osoitteesta)