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. Aineisto tulee pääosin Maanmittauslaitoksen Maastotietokonnasta.
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 Ohje API-avaimen käyttöön. Rajapintapalvelu on saatavilla osoitteesta: https://avoin-paikkatieto.maanmittauslaitos.fi/buildings/features/v1/.
Rajapintapalvelu perustuu OGC API - Features - Part 1: Core (https://docs.ogc.org/is/17-069r3/17-069r3.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 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 paikkatietokohteiden ominaisuustiedoista on mallinnettu koodistoarvoina, joiden selitystekstit on julkaistu erillisen luettelopalvelun kautta.
Huom! Rakennuksille ei toistaiseksi olla lisätty ominaisuustietoja. Osalle rakennuksista on tallennettu kuitenkin pysyvä rakennustunnus (VTJ-PRT). Tieto pysyvän rakennustunnuksen tallentamisesta näkyy Tuotannon tilannekartalta.
Aineistot ja tuotteet
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, koska uuden maastotietojen tuotantojärjestelmän käyttöönotto on kesken. Katso ominaisuustietokenttien kuvaukset.
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 |
Kyselyt ja esimerkit
Huom! Esimerkkilinkkien käyttö edellyttää API-avaimen käyttöä.
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 ja tukee seuraavaa standardilaajennusta:
- laajennus: laajennettu koordinaatistotuki bbox-suorakaiderajauksissa (bbox-crs -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: buildings, buildings_parts, buildings_versions, buildings_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:
Rakennuskohteen haku kmtkId-tunnisteella (KMTK:n pysyvä ID):
Muuttuneiden kohteiden haku buildings_versions tuotteesta:
Tietyn kohteen muutoshistorian haku buildings_versions tuotteesta:
Hakuparametreina käytettävissä olevat ominaisuudet on lueteltu kattavammin rajapinnan OpenAPI-kuvauksessa.
Versiohallinta
Tuotannollinen julkaisu 2023-12-18 - koordinaattijärjestelmien yhdenmukaistaminen ja koordinaattijärjestykset EPSG-standardin mukaisiksi
Tuotannollinen julkaisu 2020-02
BETA-julkaisu 2019-05 (tämä versio saatavilla vain Paikkatietoalustan kehitys- ja koulutusympäristöön käyttäjiksi liittyneille osoitteesta)