Avoin rajapinta

Sähkön hintatieto-API

Nouda Suomen pörssisähkön hintatietoja tai optimoi laitteen edulliset käyttötunnit. Rajapinnat palauttavat UTF-8-koodattua JSON-dataa.

Tutustu rajapintoihin Hintahistoriaan

Näin pääset alkuun

Kolme rajapintaa eri käyttötarkoituksiin

Kaikki kutsut tehdään HTTP GET -pyyntöinä. Päivämäärät annetaan Suomen ajassa muodossa YYYY-MM-DD, ja vastausten aikaleimat sisältävät aikavyöhyke-eron. Hinnat ovat senttiä kilowattitunnilta ilman arvonlisäveroa.

Perusosoitehttps://elec.kasperikoski.fi/api/

API v1

Hintatietojen haku

Hae yhden tai useamman päivän tunti- tai varttihinnat sekä tarvittaessa jakson halvimmat aikayksiköt.

Avaa rajapinta

GEThttps://elec.kasperikoski.fi/api/v1?start=2026-01-15&interval=hour

Parametrit

Parametri	Pakollinen	Oletus	Kuvaus
`start`	Kyllä*	–	Alkupäivä muodossa `YYYY-MM-DD`.
`end`	Ei	`start`	Loppupäivä. Jos `cheapest` annetaan ilman loppupäivää, haku ulottuu uusimpaan saatavilla olevaan dataan.
`interval`	Ei	`quarter`	`quarter` palauttaa raakadatan ja `hour` tuntikeskiarvot. Ei vaikuta `cheapest`-haussa.
`cheapest`	Ei	–	Palauttaa N halvinta raakaa aikayksikköä kronologisessa järjestyksessä.
`format`	Ei	`json`	`json` tai ladattava `csv`.
`with_context`	Ei	`0`	Arvo `1` lisää nykyistä hetkeä ympäröivän tuntikontekstin.
`preset`	Ei	–	`utc_midnight_to_now` muodostaa aikavälin UTC-keskiyöstä nykyhetkeen.

* start voidaan jättää pois, kun käytetään preset=utc_midnight_to_now.

8 halvinta aikayksikköäGET /api/v1?start=2026-01-15&cheapest=8

Valitsee halvimmat raakayksiköt annetulta aikaväliltä. Anna myös end, jos et halua haun ulottuvan uusimpaan dataan.

CSV-tiedostoGET /api/v1?start=2026-01-15&format=csv

Palauttaa puolipisteellä erotellun tiedoston sarakkeilla Timestamp ja Price.

JSON-vastauksen esimerkki

{
  "start": "2026-01-15T00:00:00+02:00",
  "end": "2026-01-15T23:59:59+02:00",
  "results": 24,
  "data": [
    { "datetime": "2026-01-15T00:00:00+02:00", "price": 5.4321 }
  ]
}

API v2

Päivän rajoitettu optimointi

Valitsee päivän edulliset päälläolotunnit niin, että jokaisessa liukuvassa aikaikkunassa toteutuvat määritetyt rajat.

GEThttps://elec.kasperikoski.fi/api/v2?start=2026-01-15&cheapest=8&segment=6&min_on=1&max_on=2

Parametri	Oletus	Kuvaus
`start`	Pakollinen	Optimoitava päivä muodossa `YYYY-MM-DD`.
`cheapest`	`8`	Tavoiteltu päälläolotuntien määrä, 1–24. Tavoitetta voidaan nostaa, jotta rajoitteet voidaan toteuttaa.
`segment`	`6`	Liukuvan aikaikkunan pituus tunteina, 1–24.
`min_on` / `max_on`	`1` / `2`	Päälläolotuntien vähimmäis- ja enimmäismäärä jokaisessa aikaikkunassa.
`prev_mask`	Nollia	Edellisen jakson tila binäärijonona, jonka pituus on `segment - 1`.

Vastaus sisältää valitut tunnit, kokonaiskustannuksen, keskihinnat, käytetyt parametrit ja mahdollisen seuraavan päivän next_prev_mask-arvon.

API v3

Tulevien tuntien optimointi

Valitsee kaikesta saatavilla olevasta tulevasta hintadatasta täsmälleen halutun määrän käyttötunteja ja rajoittaa yhtäjaksoista pois päältä oloa.

GEThttps://elec.kasperikoski.fi/api/v3?cheapest=8&max_off=5&prev_off=0

Parametri	Oletus	Kuvaus
`cheapest`	`8`	Valittavien päälläolotuntien määrä.
`max_off`	`5`	Pisin sallittu yhtäjaksoinen pois päältä olo tunteina.
`prev_off`	`0`	Ennen hakujaksoa kertyneiden peräkkäisten pois päältä -tuntien määrä.

Horisontti alkaa nykyisestä täydestä Suomen ajan tunnista. Vastaus sisältää horisontin rajat, valitut tunnit, kokonaiskustannuksen ja käytetyt parametrit.

Kotiautomaatio

Home Assistant

V1-rajapinnan halvimpien aikayksiköiden haku sopii REST-sensorin tietolähteeksi. Dynaaminen URL voidaan muodostaa esimerkiksi näin:

sensor:
  - platform: rest
    name: halvimmat_tunnit
    resource_template: >-
      https://elec.kasperikoski.fi/api/v1?start={{ now().date() }}&end={{ now().date() }}&cheapest=8
    value_template: "{{ value_json.data | count }}"
    json_attributes:
      - data
    scan_interval: 3600

Esimerkissä end annetaan tietoisesti, jotta haku rajautuu tähän päivään.

Virheet ja välimuisti

Virhe palautetaan JSON-objektina, jossa ovat error ja HTTP-tilaa vastaava status. Historiallisia vastauksia voidaan välimuistittaa vuorokauden ajan ja muuttuvaa dataa viiden minuutin ajan.