Latauspalvelun pikaohje

Avoimen datan latauspalvelu toimii osoitteessa http://opendata.fmi.fi/wfs, joka ei vaadi rekisteröitymistä. Latauspalvelun käyttäminen osoitteen http://data.fmi.fi/fmi-apikey/AVAIN/wfs kautta edellyttää fmi-apikey:tä, jonka saa rekisteröitymällä palveluun.

Palvelu on WFS 2.0-palvelu ja toteuttaa WFS Simple Profile:n. Tämä tarkoittaa, että kyselyt tulee tehdä tallennettujen kyselyiden avulla.

Tärkeimmät WFS latauspalvelun operaatiot

Alla on lueteltu pakolliset WFS 2.0 standardin määrittelemät operaatiot, jotka Simple WFS profiilin toteuttavan latauspalvelun on pakko toteuttaa.

Edellä mainituista DescribeStoredQueries ja GetFeature ovat WFS Simple profiilin keskeisimmät operaatiot, kun tietoaineistoja ladataan käsin kirjoitetuilla kyselyillä. Voit tarkistaa GetCapabilities-kyselyn vastauksesta mitä profiilia WFS latauspalvelu tukee. Vastauksessa ImplementsBasicWFS (ows:Constraint elementissä) on määritely arvoon FALSE, jos latauspalvelu tukee vain WFS Simple profiilia. Paikkatieto-ohjelmaa käytettäessä kannattaa huomioida ettei se siinä tapauksessa välttämättä osaa ladata tietoaineistoja.

Tallennetuista kyselyistä

WFS latauspalvelussa on ladattavissa tietoaineistoja, kuten esimerkiksi pintasäähavaintoja ja piste-ennusteita. Yksitäisen tietoaineiston dataa voi ladata käyttämällä tallennettua kyselyä. Tallennettu kysely on käytännössä vain tunniste, jonka avulla yksittäinen tietoaineisto voidaan ladata helposti. Esimerkiksi tunnisteeseen fmi::forecast::hirlam::surface::point::multipointcoverage on sidottu HIRLAM maanpinnan tason sääennuste, jonka ennustedataa voi hakea haluamaansa paikkatietokohteeseen (piste kartalla) multipointcoverage-tyyppisenä vastauksena. Tallennettujen kyselyiden tunnisteet saa haettua latauspalvelun ListStoredQueries tai DescribeStoredQueries kyselyillä.

Ilmatieteen laitoksen avoin data latauspalvelussa tällä hetkellä olevien tallennettujen kyselyjen tietoja voi selata omalta sivulta, jos DescribeStoredQueries-kyselyn palauttama XML-vastaus tuntuu hankalalta lukea.

Useimpia tietoaineistoja voi hakea useamman tyyppisenä vastauksena. Aiemmin mainitulla tallennetun kyselyn tunnisteella fmi::forecast::hirlam::surface::point::multipointcoverage saatiin haettua ennuste 

  • multipointcoverage-tyyppisenä vastauksena. 

Tunnisteella fmi::forecast::hirlam::surface::point::timevaluepair saadaan haettua sama ennuste

  • timevaluepair-tyyppisenä vastauksena.

Multipointcoverage on tiiviimpi vastausmuoto kuin timevaluepair, joka on taas täysin INSPIRE-yhteensopiva, ja uusimmat Excel-ohjelmat tukee myös sitä.

Jokainen tallennettu kysely tuottaa aina jonkin vastauksen. Joissakin tapauksissa vastauksena on tallennetun kyselyn oletusasetuksien mukainen vastaus, mutta osa edellyttää, että käyttäjä antaa rajaavia hakuehtoja eli kyselyparametreja.

Lisäparametreista tallennetuissa kyselyissä

GetFeature-kyselyyn voidaan antaa erilaisia lisäparametreja, joilla voidaan valita ja rajata mitä tallennettu kysely palauttaa tietoaineistosta. Kaikkien tallennettujen kyselyjen lisäparametrit saa haettua DescribeStoredQueries-kyselyllä.
http://opendata.fmi.fi/wfs?service=WFS&version=2.0.0&request=describeStoredQueries&

DescribeStoredQueries-kyselyn vastausta voi rajata lisäämällä kyselyyn storedquery_id-kyselyparametrin. Seuraavan esimerkkikyselyn vastaukseen tulee vain fmi::observations::weather::multipointcoverage tallennetun kyselyn tiedot:
http://opendata.fmi.fi/wfs?service=WFS&version=2.0.0&request=describeStoredQueries&
storedquery_id=fmi::observations::weather::multipointcoverage&

Tallennetun kyselyn fmi::observations::weather::multipointcoverage muokattavia kyselyparametreja ovat muun muassa:

  • bbox (esim. &bbox=22,64,24,68&)
  • timestep (esim. &timestep=40&, minuutteina )
  • parameters (esim. &parameters=temperature,windspeedms&, katso mahdolliset suureparametrit hakemalla ensin dataa ilman rajausta)
  • crs (esim. &crs=EPSG::3067&, katso tuetut projektiot getCapabilities-vastauksesta)
  • starttime (esim. &starttime=2013-02-26T20:00:00Z&)
  • endtime (esim. &endtime=2013-02-28T20:00:00Z&)
  • maxlocations (kuinka monta asemaa etsitään kysyttyjen pisteiden läheisyydestä)
  • place (esim. &place=kumpula,Helsinki&place=kirkkonummi&)

Tallennetun kyselyn tukemien kyselyparametrien avulla voidaan rajata mitä GetFeature-kysely palauttaa tallennettuun kyselyyn sidotusta tietoaineistosta. Esimerkiksi seuraavalla kyselyllä saadaan vuoden 2018 kesäkuun 24. päivän pintasäätiedot Kuopiosta kuuden tunnin välein:
http://opendata.fmi.fi/wfs?service=WFS&version=2.0.0&request=GetFeature&
storedquery_id=fmi::observations::weather::multipointcoverage&
place=Kuopio&timestep=360&starttime=2018-06-24T00:00:00Z&
endtime=2018-06-24T23:59:59Z&

Esimerkkikyselyitä

Aluerajauksella haettu lämpötila- ja tuulennopeushavainto EPSG::3067-projektiossa aika-arvolistana:

Tunnuksen fmi::observations::weather::timevaluepair tiedoissa mainitaan teksti "Hetkelliset säähavaintoarvot". Huomataan tallennetun kyselyn abstraktista, että kyselyssä on ainakin yksi paikanmääre annettava.

Vastauksessa on havaintoja yli kymmeneltä eri suureelta, mutta olemme kiinnostuneita vain lämpötilasta ja tuulen nopeudesta. Selvitämme suureparametrien nimet jokaisen wfs:member elementtilohkon sisällä olevan om:observedProperty elementin attribuuttina olevan linkin kautta. Tuulen nopeutta palauttaa suureparametri windspeedms ja lämpötilaa temperature.

Haluamme kuitenkin havaintoja useammalta kuin yhdeltä havaintoasemalta, ja niiden sijainnit ETRS-TM35FIN tasokoordinaatteina.

Automaattiset säähavaintoasemat Heinolassa tällä hetkellä ja niiden havainnot:

Etsitään DescribeStoredQueries-kyselyn vastauksesta tallennettu kysely, joka palauttaa EnvironmentalMonitorinNetwork kohde tyypin (feature type) mukaisen vastauksen. Löydämme tallennetun kyselyn, jonka tunnus on fmi::ef::networks. Sen tiedoissa kerrotaan, että se palauttaa ympäristön tilaa monitoroivien mittausverkkojen tietoja.

Vastauksessa on useiden mittausverkkojen tietoja. Joukossa on myös "Automaattinen sääasema" -mittausverkko, jonka tiedoissa on (ef:contains elementissä) linkki mittausverkon sisältämien havaintoasemien tietoihin.

Vastauksessa on suuri joukko havaintoasemia ja niiden tietoja. Koska olemme kiinnostuneita Heinolan automaattisista havaintoasemista, löydämme asemien joukosta yhden havaintoaseman "Heinola Asemantaus". Aseman tiedoista saamme selville sen koordinaatit, fmisid arvon ja onko se tällä hetkellä toiminnassa sekä muita tietoja. Aseman fmisid arvo on erityisen hyödyllinen, koska sen avulla voimme kohdistaa havaintohaun juuri siihen havaintoasemaan.

Jaalan lähimmän havaintoaseman kaikki tiedot 30 minuutin aika-askeleella aika-arvolistana:

http://opendata.fmi.fi/wfs?service=WFS&version=2.0.0&request=getFeature&
storedquery_id=fmi::observations::weather::timevaluepair&
place=jaala&timestep=30&

Aika-askelen kanssa on huomattava, että aika-askelet lasketaan aina edellisestä tasatunnista alkaen. Esimerkiksi kello 12:17 timestep=15 tarjoaa viimeiseksi aika-askeleeksi 12:15. Havaintoja tehdään kuitenkin useimmilla asemilla kymmenen minuutin välein, joten tämä aika-askel jäisi puuttuvaksi.

Piste-ennuste Jaalaan ja Ahvenanmaalle aika-arvolistana:

Tutkimme DescribeStoredQueries-kyselyn vastausta ja huomaamme, että fmi::forecast::hirlam::surface::point::timevaluepair tallennettuun kyselyyn on sidottu HIRLAM sääennustemallin tuottama tietoaineisto. Vastauksesta saamme selville myös tuetut kyselyparametrit. Käytämme paikkaa rajaavia kyselyparametreja place ja latlon.

Havaintoasemilla 24. kesäkuuta 2018 mitattu auringon kokonaissäteily kello 12 UTC aikaan:

Huomataan vastauksesta fmi::observations::radiation::timevaluepair tallennetun kyselyn Title-elementissä mainittavan teksti "Auringon säteilyhavaintoaineisto".

Vastauksessa on useiden säteilysuureiden dataa useilta asemilta. Koska olemme kiinnostuneista kokonaissäteilystä, tutkimme mikä suureparametri palauttaa juuri sitä dataa. Elementin om:observationProperty attribuuttina olevan linkin kautta saamme selville, että suureparametri "GLOB_1MIN" palauttaa kokonaissäteilydataa.

DescribeStoredQueries-kyselyn vastauksesta näemme, että parameters-kyselyparametrin avulla voidaan tehdä rajauksia palautettaviin meteorologisiin suureisiin ja starttime- sekä endtime-parametreilla aikarajaus.

Tietomalleista ja niiden käytöstä

Latauspalvelu tarjoaa tietoa INSPIRE-yhteensopivassa muodossa. Tietomalli on optimoitu tiedon vaihtoon. Tämä näkyy muun muassa siten, että vastaukset ovat suunniteltu mahdollisimman itsensä selittäviksi. Tietomallin etuna on myös korkea yhteensopivuus muiden Eurooppalaisten ilmatieteen laitosten ja muiden paikkatietoa tuottavien viranomaisten kanssa.

Tulemme julkaisemaan kirjaston käyttöä helpottamaan. Ensimmäisenä tulee JavaScript-tuki. Pyrimme jatkossa myös tukemaan getFeatureById-kyselyä siten, että palvelusta voi hakea pelkän data-osion ilman meta-tietoja.

Sääsymbolien selitykset

Sääennustemallista voidaan kysyä vallitsevaa säätilaa WeatherSymbol3-parametrina. Numerokoodin selitykset ovat seuraavat:

1 selkeää
2 puolipilvistä
21 heikkoja sadekuuroja
22 sadekuuroja
23 voimakkaita sadekuuroja
3 pilvistä
31 heikkoa vesisadetta
32 vesisadetta
33 voimakasta vesisadetta
41 heikkoja lumikuuroja
42 lumikuuroja
43 voimakkaita lumikuuroja
51 heikkoa lumisadetta
52 lumisadetta
53 voimakasta lumisadetta
61 ukkoskuuroja
62 voimakkaita ukkoskuuroja
63 ukkosta
64 voimakasta ukkosta
71 heikkoja räntäkuuroja
72 räntäkuuroja
73 voimakkaita räntäkuuroja
81 heikkoa räntäsadetta
82 räntäsadetta
83 voimakasta räntäsadetta
91 utua
92 sumua

Katso myös: http://ilmatieteenlaitos.fi/saamerkkien-selitykset sekä
vapaasti käytettävissä olevat sääsymbolit GitHUBissa

20.11.2018

Palvelun käyttöehdot

Käyttääkseen rajapintoja käyttäjän on hyväksyttävä Creative Commons -lisenssi. Palveluissa on käyttäjäkohtaisia hakumäärärajoitteita.

  • Latauspalveluun saa tehdä enintään 20 000 kyselyä vuorokaudessa.
  • Katselupalveluun saa tehdä enintään 10 000 kyselyä vuorokaudessa.
  • Molempiin palveluihin saa tehdä yhteensä enintään 600 kyselyä viidessä minuutissa.

Tutkadata

WMS-palvelu

Tutkadataa on ladattavissa wms-palvelun kautta osoitteesta: 
http://openwms.fmi.fi/geoserver/Radar/wms?service=WMS&version=1.3.0&request=GetCapabilities&

Tarjolla on seuraavat parametrit Suomen yhdistelminä:

  • tutkaheijastuvuus (dbz)
  • sateen intensiteetti (rr)
  • tunnin sademäärä (rr1h)
  • 12 tunnin sademäärä (rr12h)
  • 24 tunnin sademäärä (rr24h)

Sekä yksittäisiltä tutkilta:

  • tutkaheijastuvuus (dbz)
  • säteisnopeus (vrad)
  • sateen olomuoto (hclass)
  • pilvenkorkeus (etop_20)

Tarjolla on kaksi eri tyyliä. Oletuksena palautetaan väritetty kuva mutta mikäli haluaa datan ilman hävikkiä, tulee kuvat ladata raster-tyylisenä. 

Yhdistelmille on annettavana parametrina aika (time). Yksittäisille tutkille tulee antaa parametreina haluttu aika (time) ja skannauskulma (elevation).

WMS-palvelu tukee useita eri tiedostoformaatteja. On kuitenkin huomattava, että ainoastaan geotiff lasketaan latauspalveluksi. Näin geotiff-muotoisille latauksille on eri käyttörajoitukset kuin muille formaateille. Mikäli siis haluat käyttää tutkakuvia sovelluksessasi, tulee kuvat ladata ensin omalle palvelimelle geotiff-muodossa ja tarjota wms-palvelu sitä kautta.

Datan sisällöstä

Mustavalkoisissa kuvissa pikselin harmaasävyarvo kertoo kyseisen paikan parametrin arvon. Tutkaheijastuvuuden osalta arvo on suhteellinen heijastuvuuskerroin. Se on saatu kaavalla: p = dbz*2+64, missä p on pikselinSateen intensiteetin osalta yksi harmaasävyarvo vastaa 0.01 mm/h sadetta ja kertymäkuvissa 0.01 mm sadetta. 

WFS-palvelu

Tietoa saatavissa olevista tutkakuvista sekä niiden meta-tiedoista saa myös WFS-palvelun kautta. Esimerkiksi kysely 
http://opendata.fmi.fi/wfs?service=WFS&version=2.0.0&request=GetFeature&
storedquery_id=fmi::radar::composite::dbz&

palauttaa kaikki saatavissa olevat Suomen yhdistelmät tutkaheijastuvuus-parametrista. Vastaus sisältää tietoja palautettavista datoista sekä linkin varsinaiseen binääridataan (wms-palveluun):

<gml:fileReference>
http://openwms.fmi.fi/geoserver/ows?service=WMS&version=1.1.0&request=GetMap&layers=Radar:suomi_dbz_eureffin& styles=raster&bbox=-118331.366,6335621.167,875567.732,7907751.537& width=3400&height=5000&srs=EPSG:3067&format=image%2Fgeotiff& time=2013-04-09T09:50:00Z
</gml:fileReference>
 

Nämä linkit palauttavat datan alkuperäiskoossa mustavalkoisina kuvina.

Ennustemallit ja muu hiladata

Binäärimuotoista dataa on ladattavissa osoitteessa: http://opendata.fmi.fi/download. Data palautetaan grib-muodossa sekä versioissa 1 että 2. Tällä hetkellä palvelusta on ladattavissa kansallisen HIRLAM sääennustusmallin viimeinen malliajo.

Tietoa saatavissa olevista aineistoista ja niiden meta-tiedoista saa WFS-palvelun kautta. Esimerkiksi kysely 
http://opendata.fmi.fi/wfs?service=WFS&version=2.0.0&request=GetFeature&
storedquery_id=fmi::forecast::hirlam::surface::finland::grid&

 palauttaa kaikki saatavissa olevat HIRLAM mallin ajot. Vastaus sisältää tietoja palautettavista datoista sekä linkin varsinaiseen binääridataan:

<gml:fileReference>
http://opendata.fmi.fi/download?producer=hirlam&param=Pressure,GeopHeight,Temperature, DewPoint,Humidity,WindUMS,WindVMS,PrecipitationAmount, TotalCloudCover,LowCloudCover,MediumCloudCover,HighCloudCover, RadiationNetTopAtmLW,RadiationLW,RadiationGlobal,Precipitation1h, MaximumWind,WindGust&bbox=-180,25.6476611861807, 180,89.9999445853145&origintime=2013-07-01T18:00:00Z&starttime=2013-07-01T18:00:00Z&endtime=2013-07-04T00:00:00Z&format=grib2&projection=epsg:4326
</gml:fileReference>
 

Kannattaa huomata, että tiedostot ovat erittäin suuria ja WFS-kyselyä tai varsinaista data-kyselyä kannattaa rajata vielä erikseen alueellisesti ja ajallisesti.