Tekninen kuvaus - Maastotietokannan kyselypalvelu (OGC API Features)
Palvelu tarjoaa OGC API Features -kyselyrajapinnan Maastotietokannan maastotiedoille.
Rajapintapalvelu tarjotaan maksuttomana avoimena rajapintana sekä maksullisena sopimusrajapintana.
Avoin rajapinta tarjotaan 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. Avoin rajapintapalvelu on saatavilla osoitteesta: https://avoin-paikkatieto.maanmittauslaitos.fi/maastotiedot/features/v1/.
Sopimusrajapinta vaatii käyttäjätunnukset. Jos teet sopimuksen avoimien paikkatietojen kyselypalvelusta, saat samalla sopimuksella mahdollisuuden käyttää muitakin avoimien paikkatietojen kyselypalveluita. Jos olet kiinnostunut palvelusta, ota yhteyttä verkkopalveluiden asiakastukeen osoitteeseen: verkkopalvelut@maanmittauslaitos.fi.
Sopimusrajapintapalvelu on saatavilla osoitteesta: https://sopimus-paikkatieto.maanmittauslaitos.fi/maastotiedot/features/v1/.
Palvelu tukee GeoJSON-tiedostomuotoa.
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. Palvelun tietotuotteet perustuvat nykyisen Maastotietokannan aineistoon.
Rajapintapalvelu perustuu vahvistettuun OGC API - Features - Part 1: Core -standardiin. Palvelu tukee myös luonnosvaiheessa olevia standardin laajennuksia ”Coordinate Reference Systems by Reference” ja ”Common Query Language” joihin voi tutustua GitHub-kehitysympäristössä. Rajapinnan tekninen kuvaus on julkaistu Open API 3.0 spesifikaation mukaisena. Linkki kuvaukseen osiossa 'Kyselyt ja esimerkit'.
Paikkatietokohteet voidaan valita seuraavien ehtojen perusteella: id-tunniste, suorakaiderajaus (bbox), aikarajaus (datetime), attribuuttikysely (filter).
Vihjeitä Maanmittauslaitoksen Maastotietokannan OGC API Features -palvelun käyttäjille (pdf).
Aineistot ja tuotteet
Aineistolähteet ja käsitemallit
Kyselypalvelun aineistolähteenä on Maanmittauslaitoksen Maastotietokannan aineistot, jotka kuuluvat avoimen datan lisenssin piiriin. Palvelun aineistoa ajantasaistetaan jatkuvasti.
Em. linkin kautta löytyy myös kuvaukset Maastotietokannan kohdemallista, jonka luokituksessa on kuvattu mm. paikkatietokohteiden kohderyhmät ja kohdeluokat.
GeoJSON-skeemat
Kyselypalvelua varten Maastotietokannan kohteiden GeoJSON-skeemat tuotetaan ohjelmallisesti karttapalveluiden tietopalvelua varten rakennetun tietopalvelutietokannan tietomallista, joka on hyvin lähellä Maastotietokannan kohdemallia, mutta ei kuitenkaan täysin identtinen.
Palvelun tuottamat maastotietokohteiden GeoJSON-skeemat ovat ns. simple feature -tyyppisiä, eli tietorakenteissa ei ole sisäkkäisiä alikohteiden rakenteita, vaan ominaisuustiedot (attribuutit) löytyvät suoraan Feature-elementin alta. Yhteiset ominaisuudet kaikille palvelun tuottamille maastotietokohteille:
- id-attribuutti on palvelukohtainen tunniste (integer-tyyppiä)
- geometry : maastotietokohteen kohdeluokasta ja kohdetyypistä riippuen soveltuva geometria (esim. 'Point', 'LineString', 'Polygon')
- yhteiset ominaisuudet suoraan Feature-elementin alla
- mtk_id
- sijaintitarkkuus
- korkeustarkkuus
- aineistolahde
- alkupvm
- kohderyhma
- kohdeluokka
Lisäksi maastotietokohteesta riippuen kohteilla voi olla myös muita ominaisuustietoja suoraan Feature-elementin alla.
Kohteiden ominaisuuksien tietosisällön tarkempi kuvaus löytyy Maastotietokannan kohdemallista.
Rajapinnan kyselypalvelutuotteet
Kyselypalvelutuotteet (collections) maastotietokohteittain:
https://avoin-paikkatieto.maanmittauslaitos.fi/maastotiedot/features/v1/collections
Tarkempi kuvaus esim. tieviiva- tai rakennus-maastotietokohteista (muut kohteet vastaavilla pyynnöillä):
https://avoin-paikkatieto.maanmittauslaitos.fi/maastotiedot/features/v1/collections/tieviiva
https://avoin-paikkatieto.maanmittauslaitos.fi/maastotiedot/features/v1/collections/rakennus
Eri maastotietokohteille sallitut kohdeluokat on julkaistu palvelun Open API-kuvauksessa (https://avoin-paikkatieto.maanmittauslaitos.fi/maastotiedot/features/v1/api). Esimerkiksi tieviiva-maastotietokohteelle tämä tieto löytyy palvelupyyntöjen (/paths) kuvauksen alta kohdasta "/collections/tieviiva/items", jossa määritelty sallitut kohdeluokat:
{ "name" : "kohdeluokka", "in" : "query", "description" : "Filter the collection by kohdeluokka", "required" : false, "style" : "form", "explode" : false, "schema" : { "type" : "integer", "format" : "int32", "enum" : [ 12131, 12132, 12141, 12111, 12112, 12151, 12312, 12152, 12313, 12121, 12122, 12314, 12316 ] }
Sallitut kohdeluokat lueteltu enumeraatiossa ja sisältö maastotietokohteittain perustuu Maastotietokannan kohdemalliin.
Skeemarakenne käy ilmi hakemalla esimerkkikohteita tiettyyn maastotietokohteeseen kuuluvalla kohdeluokalla (tässä esimerkkiaineisto haettu BBOX-lisärajauksella).
Esim. kohdeluokka 12111 (Autotie Ia) tieviiva-maastotietokohteessa:
Esim. kohdeluokka 42211 (Asuinrakennus, 1-2 krs) rakennus-maastotietokohteessa:
Kyselyt ja esimerkit
Yhteensopivuus ja tuotteet
Kehitettäessä OGC API Features -asiakassovelluksia kannattaa ensin tutustua viralliseen standardiin.
Maastotietokannan OGC API Features -palvelu on standardin Core-osan mukainen. Lisäksi se tukee seuraavia standardin laajennuksia:
- laajennettu koordinaatistotuki bbox-suorakaiderajauksissa (bbox-crs -parametri) ja vastauksien geometrioissa (crs-parametri)
- cql - kyselyparametrit (standardin laajennus vielä luonnosvaiheessa)
Tuetut yhteensopivuusluokat (conformance classes):
https://avoin-paikkatieto.maanmittauslaitos.fi/maastotiedot/features/v1/conformance
Palvelun tarjoamat tuotteet (collections) ja tuetut koordinaatistot:
https://avoin-paikkatieto.maanmittauslaitos.fi/maastotiedot/features/v1/collections
Open API kuvaukset
Open API 3.0 kuvauksessa on kerrottu tarkemmin kuinka palvelusta voidaan hakea metatietoa ja Maastotietokannan mukaisia paikkatietokohteita OGC API Features -standardin mukaisilla palvelupyynnöillä:
https://avoin-paikkatieto.maanmittauslaitos.fi/maastotiedot/features/v1/api
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 Maastotiedot OGC API Features -palveluun, toki kohdeluokat skeemoineen ja hakuparametrit ovat tuotekohtaisia.
Alla muutama esimerkkihaku Maastotiedot OGC API Features -palveluun.
Yhden (määrittelemättömän) paikkatietokohteen haku tietystä tuotteesta (kts. collections tunnisteen jälkeen sallitut tuotetunnisteet pyynnöllä https://avoin-paikkatieto.maanmittauslaitos.fi/maastotiedot/features/v1/collections):
Maastotietokohteiden (tässä tieviiva-kohteeseen) haku BBOX-rajauksella (ETRS-TM35FIN) siten että myös vastauksessa geometriat palautetaan ETRS-TM35FIN-koordinaatistossa:
Vastaava BBOX-haku ominaisuustietorajauksella lisättynä (vaaditaan että kohdeluokka on 12122 tai 12314):
Maastotietokohteen haku mtk_id-tunnisteella (tässä puisto-kohteesta):
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-06
BETA-julkaisu 2019-05