JHS 180 Paikkatiedon sisältöpalvelut

Liite 5. Paikkatietopeitteen kyselypalvelu

  • Versio: 1.0
  • Julkaistu: 6.9.2019
  • Voimassaoloaika: toistaiseksi

    1 Johdanto

Paikkatietopeitteen kyselypalvelulla tarkoitetaan rajapintapalvelua, joka mahdollistaa peitemuotoisen paikkatiedon kopioimisen käyttäjän tietovälineelle. Palvelu on samanluonteinen kuin suosituksen liitteessä 2 kuvattu paikkatiedon kyselypalvelu, mutta tarkoitettu erityisesti peiteaineistoille. Tämä liite sisältää suositukset paikkatietopeitteen kyselypalvelun toteuttamisesta. Peitedatan lataamiseen tiedostoina pätevät liitteessä 3 selostetut tiedostopalvelua koskevat suositukset.

Paikkatietopeitteen kyselypalvelu mahdollistaa sen, että käyttäjän sovellus tai palvelu hakee peitemuotoista paikkatietoa suoraan sen tallennuspaikasta kyselyn avulla (Geoinformatiikan sanasto). Nimensä mukaisesti palvelua käytetään paikkatietopeitteille eli alueen kattaviin paikkatietoaineistoihin. Peitteitä ovat esimerkiksi korkeusmalli tai lämpötilajakauma. Peitteellä voi olla yksi tai useampia ulottuvuuksia (esimerkiksi korkeusprofiili viivan suhteen (1D), ortoilmakuva (2D), ilmamassan lämpötilajakauma myös korkeussuunnassa (3D), samalta alueelta eri ajan hetkinä otetut satelliittikuvat (2D + aika).

Tässä suosituksessa käsiteltävä paikkatietopeitteen kyselypalvelu pohjautuu interaktiivisen, OGC:n määrittämän Web Coverage Service (WCS) -standardin mukaisen palvelurajapinnan käyttöön.

Tyypillinen prosessi paikkatietojen hakemiseksi kyselypalvelun WCS-palvelurajapinnasta koostuu seuraavista vaiheista (silloin, kun asiakassovellus ei etukäteen tunne palvelun yksityiskohtia):

  1. Asiakassovellus kysyy rajapintapalvelun metatietoja (GetCapabilities -kysely).
    Vastauksesta käy ilmi mm. tarjolla olevien paikkatietopeitteiden nimet ja palvelun tukemat WCS-standardin laajennukset.
  1. Asiakassovellus kysyy valitsemansa peitteen tarkemmat tiedot (DescribeCoverage-kysely).
    Vastauksesta selviää mm. kysytyn peitteen luontainen koordinaattijärjestelmä ja tiedostomuoto, alueellinen ja ajallinen kattavuus sekä kanavien määrä ja nimet.
  1. Saamiensa palvelun ja peitteen tietojen perusteella asiakassovellus pystyy muodostamaan paikkatietokyselyn ja lähettämään sen rajapintapalveluun (GetCoverage -kysely).
    Rajapintapalvelu prosessoi kyselyn ja palauttaa vastauksen (peitemuotoinen data) tai mahdollisen virheviestin, jos prosessointi epäonnistui.

Tiedonsiirrossa sovellettava kohdemalli on tämän suosituksen mukaan ensisijaisesti GeoTIFF. Mikäli GeoTIFF ei tietyn aineiston välittämiseen sovellu, niin voidaan käyttää myös netCDF-muotoa.

Keskeisimmät paikkatiedon kyselypalvelua koskevat suositukset ovat:

  • Palvelun perusstandardina käytetään Web Coverage Service (WCS) -versiota 2.0.
  • Palvelun palauttaman paikkatiedon koodaustapa on oletusarvoisesti GeoTIFF, ja jos se ei palautettavalle tiedolle sovellu, niin netCDF.
  • Palvelun on tuettava käyttökohteesta riippuen erilaisia koordinaattijärjestelmiä. Suositeltavat järjestelmät on lueteltu tämän suosituksen luvussa 2.
  • Aikaa suositellaan käsiteltäväksi omana ulottuvuutenaan.
  • Palvelun on tuettava WCS-standardin mukaisia GetCapabilities, DescribeCoverage sekä GetCoverage -kyselyjä HTTP GET -muodossa.
  • Palvelun on tuettava kaikkia WCS 2.0.1 Core -standardin sekä KVP Protocol Binding -laajennuksen toiminnallisuuksia. (Huom! KVP standardi ei ole ajan tasalla, sisältää toimimattomia esimerkkejä).
  • Lisäksi suositellaan, että myös seuraavia WCS-standardin laajennuksia tuetaan
  • CRS Extension
  • Scaling Extension
  • Range Subsetting Extension
  • Interpolation Extension.

    2 Koordinaattijärjestelmät

Kansallisissa WCS-palvelurajapinnassa tulisi käyttää ensisijaisesti ETRS89 / TM35-FIN (EPSG:3067) -koordinaattijärjestelmää. Kansainvälistä yhteensopivuutta vaativissa rajapintapalveluissa voi käyttää WGS84 (EPSG:4326) -koordinaattijärjestelmää.

    3 WCS-palvelut

WCS-palvelurajapinnasta tulisi käyttää versiota 2.0.

      3.1 Kysely

WCS-palvelurajapinta koostuu kolmesta kyselystä:

  • GetCapabilities
    Tämä kysely tarjoaa tiedot palvelun yleisistä ominaisuuksista sekä luettelon palvelusta saatavilla olevista paikkatietopeitteistä.
  • DescribeCoverage
    Tämä kysely tarjoaa yksityiskohtaista tietoa yhdestä tai useammasta valitusta paikkatietopeitteestä.
  • GetCoverage
    Tällä kyselyllä voidaan ladata valittu paikkatietopeite jossain palvelun tukemassa tiedostomuodossa. Peite voidaan ladata joko kokonaisuudessaan tai sijainnin, ajan tai muun paikkatietopeitteen ulottuvuuden perusteella rajattuna.

Suosituksen mukaisten palvelujen on tuettava ainakin avain-arvoparien (KVP, key value pair) perusteella tehtäviä HTTP GET -protokollaa käyttäviä kyselyitä. Lisäksi palvelu voi tukea myös muita protokollia. Jos käytetään XML/POST- tai XML/SOAP-prokollia, niin se on tehtävä hyväksyttyjen WCS-standardien mukaisesti.

GET-metodin mukainen viesti koostuu palvelimen web-osoitteesta, jonka perään asiakasohjelma liittää kyselyn parametrit avain-arvopareina. GET-metodin yleisen syntaksin mukaisesti avain-arvoparilista erotetaan palvelimen osoitteesta symbolilla ”?” ja kukin avain-arvopari erotetaan toisistaan symbolilla ”&”. Näin esimerkiksi GetCapabilities-kysely voisi näyttää seuraavalta:

http://kartta.org.fi/wcs?SERVICE=WCS&ACCEPTVERSIONS=2.0.1&REQUEST=GetCapabilities

Avaimen nimi voidaan vapaasti kirjoittaa suurilla tai pienillä kirjaimilla, mutta avaimen arvossa kirjainkoko on merkitsevä. Siten COVERAGEID=ortokuva ja CoverageId=ortokuva ovat palvelun kannalta sama kysely, mutta COVERAGEID=ortokuva ja COVERAGEID=Ortokuva merkitsevät eri asiaa. Avain-arvoparien järjestyksellä kyselyviestissä ei ole merkitystä.

Tietyillä avaimilla arvona voi olla arvoluettelo, jolloin arvot annetaan pilkulla erotettuna. Esimerkki: COVERAGEID=ortokuva,korkeusmalli.

WCS-palvelu vastaa viestiin palauttamalla asianmukaisen tiedoston; joko XML-muotoisen tekstin (GetCapabilities-kyselyn ja DescribeCoverage-kyselyn vastaukset ja mahdolliset virheviestit) tai datatiedoston, joka lähetetään vastauksena GetCoverage-kyselyyn.

        3.1.1 Palvelun metatietojen kysely (GetCapabilities)

GetCapabilities-kysely on palvelun metatietojen pyytämiseen tarkoitettu kysely. Asiakassovelluksen täytyy selvittää palvelun keskeiset metatiedot, ennen kuin se pystyy muotoilemaan järkeviä, lopulta paikkatietopeitteen lataamiseen tähtääviä jatkokyselyjä. Tällaisia perustietoja ovat mm. palvelimen tarjoama tietosisältö, palvelun mahdollisesti tukemat WCS-standardin laajennukset, tuetut tiedostomuodot ja koordinaattijärjestelmät jne. Kaikki nämä tiedot löytyvät GetCapabilities-kyselyn avulla.

Esimerkki 3. WCS GetCapabilities-kysely

http://kartta.org.fi/wcs?SERVICE=WCS&ACCEPTVERSIONS=2.0.1&REQUEST=GetCapabilities

GetCapabilities-kyselyn vastaus saattaa olla pitkä, mutta sitä voidaan lyhentää lisäämällä pyyntöön avain &SECTIONS= ja sille yksi tai useampia, pilkulla erotettua osion nimeä. Mahdolliset nimet ovat: ServiceIdentification (palvelun tyyppi ja sen tukemat WCS-laajennukset), ServiceProvider (tietoja palvelun ylläpitäjästä), OperationsMetadata (luettelo tuetuista WCS-pyynnöistä), ServiceMetadata (tuetut formaatit ja koordinaattijärjestelmät) ja Contents (luettelo palvelussa olevista paikkatietopeitteistä).

JHS-suosituksen mukaisen WCS-palvelun on lueteltava GetCapabilities-vastauksessa kaikki julkisesti saataville tarkoitetut paikkatietopeitteet, vaikka WCS-standardi ei tätä vaadikaan.

        3.1.2 Paikkatietopeitteen kuvauksen kysely (DescribeCoverage)

DescribeCoverage-kysely palauttaa tiedon valitun paikkatietopeitteen käyttämästä koordinaattijärjestelmästä, sekä tiedot, joiden avulla palvelusta saatavat datapisteet voidaan kiinnittää tähän koordinaattijärjestelmään. Vastaus sisältää myös tiedot, joita tarvitaan GetCoverage-pyynnön rajaamiseen peiteaineiston ulottuvuuksien perusteella (SUBSET), rajatun kanavamäärän valitsemiseksi (RANGESUBSET) tai palautettavan peiteaineiston resoluution muuttamiseksi WCS Scaling -laajennuksen mukaisesti.

http://kartta.org.fi/wcs?SERVICE=WCS&VERSION=2.0.1&REQUEST=DescribeCoverage&COVERAGEID=ortokuva

Huom! CoverageId on WCS 2.0.1 standardin mukaan XML-tyyppiä "NCName" ( non-colonized name). Peitteen nimi saa alkaa vain kirjaimella tai alaviivalla ja se saa sisältää vain kirjaimia, numeroita, väli- ja alaviivoja sekä pisteitä.

        3.1.3 Paikkatietopeitteen lataus (GetCoverage)

GetCoverage-kyselyssä on vain muutama pakollinen avain-arvopari ja yksinkertaisin mahdollinen kysely on tämän esimerkin mukainen:

http://kartta.org.fi/wcs?SERVICE=WCS&VERSION=2.0.1&REQUEST=GETCOVERAGE&COVERAGEID=peite1

Koko palvelimella olevan paikkatietopeiton hakua yhdellä kyselyllä voidaan pitää poikkeustapauksena, koska esimerkiksi Suomen laajuisen ortokuvapeiton koko on noin 2 teratavua. Jokainen WCS 2.0.1 -palvelin kuitenkin tukee peiton leikkaamista sekä sijainnin että muiden mahdollisten ulottuvuuksien, kuten ajan perusteella. Kysely, jolla valitaan alue itä- ja pohjoiskoordinaattien avulla sekä pyydetään vastaus tiff-muotoisena kuvana, voisi olla esimerkiksi tällainen

http://kartta.org.fi/wcs?SERVICE=WCS&VERSION=2.0.1&REQUEST=GETCOVERAGE&COVERAGEID=peite1&SUBSET=E(496000,496200)&SUBSET=N(7181000,7181200)&FORMAT=image/tiff

GetCoverage-kyselyn avain-arvoparit

Pakolliset avain-arvoparit:

SERVICE

aina ”WCS”

VERSION

aina “2.0.1”

REQUEST

aina ”GetCoverage”

COVERAGEID

jonkin palvelusta saatavilla olevan peiteaineiston ID

WCS 2.0.1 Core-standardin vapaaehtoiset avaimet, joita jokainen palvelin tukee

SUBSET

peitteen ulottuvuuden eli dimension tunnus ja sen perusteella valittavan arvoalueen ala- ja ylärajat; voidaan toistaa eri dimensioille

FORMAT

jokin palvelun tukema tiedostomuoto

MEDIATYPE

avaimen arvo ”multipart/related” tuottaa vastauksen ”multipart”-muotoisena

Avaimet, joita tuetaan jos palvelin tukee niitä vastaavaa WCS-laajennusta.

CRS-laajennus eli koordinaattijärjestelmätuki

OUTPUTCRS (vaatii CRS-laajennuksen)

SUBSETTINGCRS (vaatii CRS-laajennuksen)

Scaling-laajennus eli tuki alkuperäisen hilarakenteen muutoksille

SCALEFACTOR

SCALEAXES

SCALESIZE

SCALEEXTENT

Range subsetting –laajennus eli tuki vapaalle kanavien poimimiselle

RANGESUBSET

Interpolation-laajennus eli datapisteiden välille osuvien arvojen laskentamenetelmät

INTERPOLATION

GeoTIFF-laajennus eli GeoTIFF-tiedostomuotoon liittyvät muotoilumahdollisuudet

GEOTIFF:COMPRESSION

GEOTIFF:JPEG_QUALITY

GEOTIFF:PREDICTOR

GEOTIFF:INTERLEAVE

GEOTIFF:TILING

GEOTIFF:TILEHEIGHT

GEOTIFF:TILEWIDTH

      3.2 Ajan käsittely

Aikaa suositellaan käsiteltäväksi omana ulottuvuutenaan sekä niin, että jos peitteessä aika ei merkitse tarkkaa ajanhetkeä vaan ajanjaksoa, kuten tunnittaista tai vuosittaista kertymää, niin ajaksi merkitään ajanjakson loppuhetki.

Palvelun tarjoaman paikkatietopeitteen aikaulottuvuuden olemassaolo ilmenee DescribeCoverage-vastauksen axisLabels-attribuutista, jossa listataan myös aika-akselista käytettävä nimi.

<gml:EnvelopeWithTimePeriod srsName="http://www.opengis.net/def/crs/EPSG/0/3067" axisLabels="E N time " uomLabels="m m s" srsDimension="2">

Aikaulottuvuuden rajat eli peitteen kattaman ajanjakson alku- ja loppuhetket ilmoitetaan gml:beginPosition- ja gml:endPosition-elementtien avulla.

<gml:lowerCorner>61254.6580619824 6623749.72946716</gml:lowerCorner>
<gml:upperCorner>735433.573091962 7782000.0</gml:upperCorner>
<gml:beginPosition> 1985-12-31T00:00:00.000Z</gml:beginPosition>
<gml:endPosition> 2018-12-31T00:00:00.000Z</gml:endPosition>
</gml:EnvelopeWithTimePeriod>

Vaihtoehtoisesti voidaan käyttää EnvelopeWithTimePeriod:in sijasta Envelope:a. joka sisältää kaikki ulottuvuudet. Tätä tapaa voidaan käyttää myös muille ulottuvuuksille kuin ajalle. Esimerkkinä peitteen, jolla on myös aika- ja korkeusakselit ”ansi” ja ”elev”, kaikki ulottuvuuden voidaan ilmoittaa näin:

<Envelope axisLabels="Lat Long ansi elev" srsDimension="4" srsName="http://ows.rasdaman.org/def/crs-compound?1=http://ows.rasdaman.org/def/crs/EPSG/0/4326&2=http://ows.rasdaman.org/def/crs/OGC/0/AnsiDate&3=http://ows.rasdaman.org/def/crs/OGC/0/Index1D?axis-label="elev"" uomLabels="degree degree d GridSpacing">
<lowerCorner>-90 -180 "
2013-12-17T00:00:00.000Z " 0</lowerCorner>
<upperCorner>90 180 "
2015-01-11T00:00:00.000Z " 1500</upperCorner>
</Envelope>

Tässä tapauksessa ajanjakson alku- ja loppuhetket saadaan lowerCorner- ja upperCorner-elementtien aika-akselin arvoista.

Jos peitteen aikaulottuvuus ei ole jatkuva, niin myös ajanhetket, joilta on olemassa dataa luetellaan timePosition-attribuuttien avulla. Tällaisia ovat esimerkiksi tasatunnein tehdyt ilmanpaineen mittaukset, joille annetaan timePosition-arvoksi mittaushetken kellonaika.

Joskus peitteen sisältämä tieto ei ole kytketty tiettyyn ajanhetkeen vaan aikajaksoon, esimerkiksi tunnin aikana kello 14:00-15:00 välillä kertynyt sademäärä. Tässä tapauksessa suositellaan, että timePosition-arvona käytetään aikajakson loppuhetkeä, eli esimerkkitapauksessa mittauksen edustaman tunnin viimeistä sekuntia.

<gml:timePosition>2018-09-28T14:59:59Z</gml:timePosition>

Ajat ilmoitetaan ISO 8601 –standardin mukaisesti. Kellonajoille suositellaan käytettäväksi täsmällistä esitysmuotoa, joka sisältää myös tiedon aikavyöhykkeestä.

2018-12-31T23:59:59Z - Joulukuun 31. päivän viimeinen sekunti vuonna 2018 UTC-ajan mukaan, jolloin Suomen aikavyöhykkeen mukainen aika on tammikuun 1. päivä vuonna 2019 kello 01:59:59.

2018-12-31T23:59:59+02:00 - Joulukuun 31. päivän viimeinen sekunti vuonna 2018 Suomen aikavyöhykkeellä, joka on 2 tuntia UTC-aikaa edellä.

Kun aika on yhtenä peitteen ulottuvuutena, niin sitä käytetään GetCoverage-pyynnön SUBSET-avaimen arvona samalla tavalla kuin paikkaan liittyviä ulottuvuuksiakin. Esimerkkinä pyyntö, jolla haetaan sademääräkertymä 31.12.1985 kello 14 Suomen paikallista aikaa päättyvältä ajanjaksolta.

http://kartta.org.fi/wcs/service/ows?
service=WCS&
version=2.0.1&
request=GetCoverage&
CoverageID=ortokuva__ortokuva&
SUBSET=E(393450,393650)&
SUBSET=N(7495450,7495650)&
format=image/tiff&
SUBSET=
time("1985-12-31T13:59:59+02:00")

Datan hakeminen tietyltä ajanjaksolta tehdään antamalla alku- ja loppuhetket pilkulla erotettuna. Esimerkiksi haetaan iltapäivän (klo 12-18) väliset sademäärän kertymät:

SUBSET= time("1985-12-31T12:00:00.000Z","2000-12-31T17:59:59.000Z")

Vain harvat tulostiedostomuodot tukevat aikaulottuvuutta muuten kuin yhden ajanhetken datan osalta. Esimerkiksi yksi GeoTIFF-tiedosto ei voi sisältää monta samasta paikasta mutta eri aikoina otettua ortokuvaa.

      3.3 Tiedostoformaatit

WCS-palvelurajapintojen tuottamien palvelujen tiedostomuotona tulisi käyttää GeoTIFF-tiedostoformaattia. Käyttötarpeen vaatiessa voidaan käyttää myös netCDF-tiedostoformaattia.

    4 INSPIRE-vaatimukset

Paikkatietopeitteet on mainittu seuraavissa INSPIREn tietotuotemäärittelyissä:

Liite II: tietotuotteet

  • Korkeussijainti / Elevation (EL)
  • Maanpeite / Land Cover (LC)
  • Ortokuvat / Orthoimagery (OI)
  • Geologia / Geology (GE)

Liite III: tietotuotteet

  • Maannos / Soil (SO)
  • Energiavarat / Energy resources (ER)
  • Lajien levinneisyys / Species distribution (SD)
  • Luonnonriskialueet / Natural risk zones (NZ)

Ajantasaiset INSPIREn vaatimukset voi tarkistaa Maanmittauslaitoksen INSPIRE sihteeristöstä (inspire@maanmittauslaitos.fi) tai Euroopaan komission sivuilta (https://inspire.ec.europa.eu/).