API

Fingridin avoin data -palvelun tietoaineistoja voi ladata koneluettavassa muodossa avoimen REST API ohjelmointirajapinnan kautta. Tällä sivulla on kehittäjille tarkoitettuja ohjeita rekisteröitymiseen ja rajapinnan käyttöön.

Rekisteröityminen

Fingrid haluaa tarjota kaikille avoimen datan käyttäjille tasavertaista palvelua ja kehittää verkkopalvelua käyttäjien palautteen perusteella. Tämän vuoksi Fingridin ohjelmointirajapintojen käyttö vaatii API-avaimen.

  • API-avaimen saa rekisteröitymällä palvelun käyttäjäksi ja hyväksymällä palvelun käyttöehdot.
  • Ohjelmointirajapintojen käyttö on maksutonta ja rekisteröitymiseen riittää toimiva sähköpostiosoite. Henkilökohtainen API-avain toimitetaan ilmoitettuun sähköpostiosoitteeseen heti rekisteröitymisen jälkeen. Jos et saa avainta, tarkasta onko se päätynyt roskapostikansioon.
  • Rekisteröityneille käyttäjille voidaan myös käyttäjän suostumuksella lähettää sähköpostia rajapinnan käyttöön liittyvistä muutoksista tai muista käyttöön vaikuttavista asioista.
  • Voit halutessasi myös poistaa rekisteröimäsi tunnuksen.

Rajapinnan käyttö

Kehittäjille tarkoitettu rajapintojen tarkempi tekninen dokumentaatio löytyy osoitteesta https://data.fingrid.fi/open-data-api/

  • API vastaa osoitteessa https://api.fingrid.fi/
  • API:n kautta voi hakea yksittäisen muuttujan viimeisimmän arvon, tai yksittäisen muuttujan dataa määritellyltä aikaväliltä, tai määritellyn muuttujajoukon viimeisimmät arvot. JSON-muodon lisäksi tarjolla on XML ja CSV-muodot.
  • Voit myös tehdä hakuja haluamaasi dataan erillisen käyttöliittymän kautta. Löydät tietoaineistokohtaisen linkin hakukäyttöliittymään kunkin tietoaineiston kuvauksesta. 
  • API kutsuissa määritellään haluttu tietoaineisto VariableId -muuttujan numerolla. Jokaisen tietoaineiston yksilöllinen muuttujan ID-numero löytyy tietoaineiston kuvauksesta. 
  • Rekisteröitymisen yhteydessä saamasi API-key lisätään sellaisenaan http-kutsujen headeriin x-api-key. Avainta ei tule käyttää esimerkiksi selaimen URL-osoiterivillä. Jos haet dataa suoraan johonkin sovellukseen, voit tyypillisesti määritellä sovelluksessasi API:n URL-osoitteen yhteyteen muita parametrejä ja sijoittaa avaimen siihen.
  • Palvelussa on API-avainkohtaisia hakumäärärajoitteita: yhdellä API-avaimella saa tehdä palveluun enintään 10 000 kyselyä vuorokaudessa. Mikäli tarvitset laajempia käyttöoikeuksia, ota yhteyttä palvelun ylläpitäjään.
  • Tietoaineistoihin liittyvät aikaleimat on esitetty UTC (ent. GMT) aikajärjestelmässä ja kyselyissä käytettävä aikamuoto on YYYY-MM-ddTHH:mm:ssZ
  • Tietoaineistojen päivitysväli vaihtelee: useimmat tietoaineistot sisältävät tuntitason tietoja, mutta osa tietoaineistoista sisältää myös 3 tai 5 minuutin välein päivittyviä tietoja. Päivitysväli on ilmoitettu tietoaineiston kuvauksessa. Kolmen minuutin välein päivittyvät arvot ovat hetkellisiä mittaustietoja, joiden alku- ja päättymisaika on sama. Aikasarjadatasta saattaa joskus puuttua yksittäisiä mittaustietoja teknisistä syistä johtuen.
  • Mikäli haet tiheästi päivitettyä dataa pitkältä aikaväliltä, haku saattaa palauttaa virheilmoituksen joka johtuu suurimman mahdollisen hyötykuorman ylittymisestä. Lyhennä haettua aikaväliä ja hae mahdollisuuksien mukaan tulokset JSON-muodossa.
  • Huomioi Cross Origin Resource Sharing (CORS) -rajoitukset käyttäessäsi rajapintaa selainympäristössä. 

Palvelun käytettävyys ja huoltokatkot

Palvelu tähtää 100% käytettävyysaikaan, mutta sitä ei voida taata ja API:n toiminnassa voi olla käyttökatkoja.

  • Rekisteröinnin yhteydessä kannattaa tilata sähköposti-ilmoitukset, jotta voimme tiedottaa mahdollisista rajapinnan käyttöön liittyvistä muutoksista tai muista käyttöön vaikuttavista asioista. 
  • Huoltokatkoista pyritään tiedottamaan erikseen. Huoltokatkotieto välittyy myös API:n kautta huoltokatkojen aikana.

Kehityksessä kannattaa joka tapauksessa aina huomioida tilanteet, joissa API-kutsujen vastaus tulee hitaasti tai jää kokonaan puuttumaan joko yksittäisten tai kaikkien muuttujien osalta. Näissä tilanteissa korostuvat esimerkiksi sovelluksen välimuistin käyttöön ja virhetilanteiden hallintaan liittyvät ratkaisut.