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

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

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

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

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 2023-12-18 - koordinaattijärjestelmien yhdenmukaistaminen ja koordinaattijärjestykset EPSG-standardin mukaisiksi 

Tuotannollinen julkaisu 2020-06

BETA-julkaisu 2019-05