Tekninen kuvaus - Maastotietokannan kyselypalvelu (OGC API Features)

Palvelu tarjoaa OGC API Features -kyselyrajapinnan Maastotietokannan maastotiedoille.

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/maastotiedot/features/v1/.  

Palvelu tukee GeoJSON-tiedostomuotoa.

Oletuskoordinaatisto on OGC API Features- ja GeoJSON-spesifikaatioiden mukaisesti WGS 84 maantieteelliset koordinaatit (CRS:84). Palvelu tukee myös ETRS-TM35FIN, ETRS-TM34..36 ja ETRS-GK19..31FIN projisoituja koordinaatistoja sekä ETRS89 maantieteellistä koordinaatistoa. Toistaiseksi suositellaan käytettäväksi joko oletuskoordinaatistoa tai ETRS-TM35FIN (EPSG:3067) koordinaatistoa, koska standardin koordinaattijärjestelmälaajennusta ei ole vielä hyväksytty ja siihen voi tulla muutoksia.

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.

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:

https://avoin-paikkatieto.maanmittauslaitos.fi/maastotiedot/features/v1/collections/tieviiva/items?kohdeluokka=12111&bbox=25.69,60.4,25.7,60.5

Esim. kohdeluokka 42211 (Asuinrakennus, 1-2 krs) rakennus-maastotietokohteessa:

https://avoin-paikkatieto.maanmittauslaitos.fi/maastotiedot/features/v1/collections/rakennus/items?kohdeluokka=42211&bbox=25.695,60.495,25.7,60.5

 

 

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, vielä virallisesti hyväksymättömiä standardin laajennuksia:

  • laajennettu koordinaatistotuki bbox-suorakaiderajauksissa (crs-bbox-parametri) ja vastauksien geometrioissa (crs-parametri)
  • cql - kyselyparametrit

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

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

Maastotietokohteiden (tässä tieviiva-kohteeseen) haku BBOX-rajauksella (ETRS-TM35FIN) siten että myös vastauksessa geometriat palautetaan ETRS-TM35FIN-koordinaatistossa:

https://avoin-paikkatieto.maanmittauslaitos.fi/maastotiedot/features/v1/collections/tieviiva/items?bbox=327000,6822000,327300,6822300&bbox-crs=http://www.opengis.net/def/crs/EPSG/0/3067&crs=http://www.opengis.net/def/crs/EPSG/0/3067

Vastaava BBOX-haku ominaisuustietorajauksella lisättynä (vaaditaan että kohdeluokka on 12122 tai 12314):

https://avoin-paikkatieto.maanmittauslaitos.fi/maastotiedot/features/v1/collections/tieviiva/items?kohdeluokka=12122,12314&bbox=327000,6822000,327300,6822300&bbox-crs=http://www.opengis.net/def/crs/EPSG/0/3067&crs=http://www.opengis.net/def/crs/EPSG/0/3067

Esimerkki tieviivaluokkien 12111 ja 12122 valitsemisesta filter-parametrin avulla:

https://avoin-paikkatieto.maanmittauslaitos.fi/maastotiedot/features/v1/collections/tieviiva/items?limit=100&filter-lang=json-filter-expr&filter=["all",[">=",["get","kohdeluokka"],12111],["<=",["get","kohdeluokka"],12122]]

Maastotietokohteen haku mtk_id-tunnisteella (tässä puisto-kohteesta):

https://avoin-paikkatieto.maanmittauslaitos.fi/maastotiedot/features/v1/collections/puisto/items?mtk_id=1299520678

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

Tuotannollinen julkaisu 2020-06

BETA-julkaisu 2019-05