Hyppää pääsisältöön

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 (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 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.

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. 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):

TuoteEsimerkkikohteitaFeatureCollection tunniste (OGC API Features)FeatureType
RakennuksetGeoJSONbuildingsBuilding
Rakennuksen osatGeoJSONbuilding_partsBuildingPart
Rakennukset (historia)GeoJSONbuildings_versionsBuilding
Rakennuksen osat (historia)GeoJSONbuilding_parts_versionsBuildingPart

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 suomeksiLiitty attribuuttiinKoodilistat
Elinkaaren tilalifecycleStatusfin, eng
Käyttötarkoitusfunctionfin, eng
Käyttötarkoituksen tarkennefunctionSpecifierfin, eng
Suhde maanpintaanrelationToGroundfin, eng
LämmitystapaheatingTypefin, eng
LämmityspolttoaineheatingFuelfin, eng

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: 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 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)