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.

Näin pääset alkuun

Yksi rajapinta kolmeen käyttötarkoitukseen

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.

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

ParametriPakollinenOletusKuvaus
startKyllä*–Alkupäivä muodossa YYYY-MM-DD.
endEistartLoppupäivä. Jos cheapest annetaan ilman loppupäivää, haku ulottuu uusimpaan saatavilla olevaan dataan.
intervalEiquarterquarter palauttaa raakadatan ja hour tuntikeskiarvot. Ei vaikuta cheapest-haussa.
cheapestEi–Palauttaa N halvinta raakaa aikayksikköä kronologisessa järjestyksessä.
formatEijsonjson tai ladattava csv.
with_contextEi0Arvo 1 lisää nykyistä hetkeä ympäröivän tuntikontekstin.
presetEi–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 v1

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/v1?operation=day&start=2026-01-15&cheapest=8&segment=6&min_on=1&max_on=2
ParametriOletusKuvaus
startPakollinenOptimoitava päivä muodossa YYYY-MM-DD.
cheapest8Tavoiteltu päälläolotuntien määrä, 1–25. Tavoitetta voidaan nostaa, jotta rajoitteet voidaan toteuttaa.
segment6Liukuvan aikaikkunan pituus tunteina, 1–24.
min_on / max_on1 / 2Päälläolotuntien vähimmäis- ja enimmäismäärä jokaisessa aikaikkunassa.
prev_maskNolliaEdellisen jakson tila binäärijonona, jonka pituus on segment - 1.

operation=day poistaa start + cheapest -yhdistelmän tulkintaepäselvyyden. Päiväoptimoinnin omat parametrit tunnistetaan myös ilman valitsinta. Vastaus sisältää valitut tunnit, kokonaiskustannuksen, keskihinnat, käytetyt parametrit ja mahdollisen seuraavan päivän next_prev_mask-arvon.

API v1

Tulevien tuntien optimointi

Valitsee kaikesta saatavilla olevasta yhtenäisestä 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/v1?operation=future&cheapest=8&max_off=5&prev_off=0
ParametriOletusKuvaus
cheapest8Valittavien päälläolotuntien määrä.
max_off5Pisin sallittu yhtäjaksoinen pois päältä olo tunteina.
prev_off0Ennen hakujaksoa kertyneiden peräkkäisten pois päältä -tuntien määrä.

Horisontti alkaa nykyisestä täydestä Suomen ajan tunnista ja päättyy viimeiseen yhtäjaksoisesti hinnoiteltuun tuntiin. Vastaus sisältää horisontin rajat, valitut tunnit, hintojen summan ja käytetyt parametrit.

Jos pyydetty tuntimäärä ei mahdu horisonttiin tai ei täytä max_off-rajoitetta, rajapinta palauttaa tilan 422, virhekoodin sekä fallback-kentässä lähimmän toteuttamiskelpoisen valinnan. Puuttuvan tulevaisuuden hintadatan tila on 404.

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. Optimoinnin toteuttamiskelpoisuusvirheissä mukana ovat myös koneellisesti luettava code, käytettävissä oleva horisontti, toteuttamiskelpoiset tuntimäärät ja mahdollinen fallback. Historiallisia vastauksia voidaan välimuistittaa vuorokauden ajan ja muuttuvaa dataa viiden minuutin ajan.