Sähkön hintatieto-API

Mikä tämä API on

Tämä rajapinta yhdistää useamman sähkön hintatoimittajan tiedot, jotta käytössäsi on aina luotettava lähde sähkön hinnalle. Lisäksi se tarjoaa avaimet käteen -ratkaisun esimerkisi halvimpien tuntien saamiselle kotiautomatiikkaa varten. Rajapintaa käytetään muodossa:

GET https://elec.kasperikoski.fi/api/?parametrit

Tämä API palauttaa toistaiseksi aina vähintään kokonaisen vuorokauden hintatiedon ISO 8601 -standardin mukaisesti datetime-muodossa. Kyselyiden määrä on rajattu enintään 200 pyyntöön vuorokaudessa. Huomaa myös Telegram-botti @WattiRobot

Tähän mennessä rajapintaa on kutsuttu yhteensä 24 655 kertaa.

Parametrit

Parametri Pakollinen Kuvaus
start Kyllä Alkamispäivä YYYY-MM-DD
end Ei Päättymispäivä YYYY-MM-DD (oletus on start)
cheapest Ei Halvimpien aikayksiköiden määrä (esim. 25). Mikäli sekä kokonaisia tunteja että quarter-tietoa löytyy, jokainen aikayksikkö käsitellään itsenäisenä.
interval Ei hour tai quarter (oletus on quarter). Jos käytetään hour, mahdolliset quarter‐tiedot aggregoidaan tunnin keskiarvoksi (yksi tunti muodostuu yhdestä arvosta). Quarter-dataa tallennetaan ainoastaan 1.10.2025 alkaen ja ennen sitä käytetään vain kokonaisia tunteja.
format Ei Tulostusmuoto: csv tai json (oletus on JSON)

Interval-parametri on hyödyllinen niille, joiden sähkömittari ei tue quarter-tason lukemista – tällöin voidaan käyttää tunnin keskiarvoa. Käyttämällä hour aggregoidaan kaikki saman tunnin quarter-tiedot yhdeksi arvoksi, jolloin aikayksikkönä on aina yksi tunti. Jos taas halutaan saada mahdollisimman tarkka dataa, käytä quarter (oletus), jolloin saat yksittäiset quarter-tason lukemat silloin kun niitä on saatavilla.

Halvimmat aikayksiköt

GET https://elec.kasperikoski.fi/api/?start=2025-02-10&cheapest=8&interval=hour

Hakee 8 halvinta aikayksikköä (tunnin keskiarvona) päivämäärälle 10.2.2025. Quarter-tiedot yhdistetään, jolloin esimerkiksi yksi tunti muodostuu yhdestä keskiarvosta.

GET https://elec.kasperikoski.fi/api/?start=2024-05-01&end=2024-05-07&cheapest=25&interval=quarter

Hakee 25 halvinta aikayksikköä. Jos haetulla aikavälillä löytyy sekä kokonaisia tunteja (ennen 1.10.2025) että quarter-tason lukemia (1.10.2025 alkaen), niitä käsitellään erikseen: kokonaiset tunnit palautetaan sellaisenaan ja quarter-tiedot yksittäisinä lukemina. Cheapest-parametri valitsee sen jälkeen halvimmat yksiköt riippumatta siitä, ovatko ne tunteja vai quarterja.

JSON-vastaus

JSON-vastaus voi näyttää tältä

{
    "start": "2024-05-20T00:00:00+02:00",
    "end": "2024-05-22T23:59:59+02:00",
    "results": 3,
    "cheapest_requested": 3,
    "warning": "Data fetched from the latest available date (2024-05-20)",
    "data": [
        {
            "datetime": "2024-05-20T04:00:00+02:00",
            "price": 2.14567,
            "hour": 4
        },
        {
            "datetime": "2024-05-20T05:00:00+02:00",
            "price": 2.34521,
            "hour": 5
        },
        {
            "datetime": "2024-05-21T03:00:00+02:00",
            "price": 3.01234,
            "hour": 3
        }
    ]
}

Huomaa, että parametrilla cheapest tulokset järjestetään aikajärjestykseen vanhimmasta uusimpaan.

Home Assistant ja Halvimmat tunnit -integraatio

Kopioi alla oleva koodi configuration.yaml-tiedostoosi. Liukusäädin (1-24h) määrittää kuinka monta halvinta tuntia binäärisensori (binary_sensor.halvin_tunti) aktivoi. Esim. arvolla 8 sensori on päällä päivän 8 halvimman tunnin ajan. Voit käyttää sensorin tilaa laitteiden ohjaukseen energiatehokkuuden parantamiseksi.

############################################################
# 1. Liukusäädin halvimpien tuntien määrälle.
############################################################

input_number:
  cheapest_hours_amount:
    name: "Halvimpien tuntien määrä"
    min: 1
    max: 24
    step: 1
    mode: slider
    unit_of_measurement: "h"

############################################################
# 2. REST-sensori hakee API:sta halvimmat tunnit
#    tunnin välein.
############################################################

sensor:
  - platform: template
    sensors:
      halvimmat_tunnit_api_url:
        friendly_name: "API-kyselyn URL"
        value_template: >-
          https://elec.kasperikoski.fi/api/?start={{ now().date() }}&cheapest={{ states('input_number.cheapest_hours_amount') | int }}

  - platform: rest
    name: halvimmat_tunnit
    resource_template: "{{ states('sensor.halvimmat_tunnit_api_url') }}"
    value_template: "{{ value_json.data | count }}"
    json_attributes:
      - data
    scan_interval: 3600

  - platform: template
    sensors:
      halvimmat_tunnit_lista:
        friendly_name: "Haetut halvimmat tunnit"
        value_template: >-
          {% set raw_data = state_attr('sensor.halvimmat_tunnit', 'data') %}
          {% if raw_data is iterable and raw_data | count > 0 %}
            {% set hours = raw_data | map(attribute='datetime') | map('string') | map('regex_replace', '^.*T(\\d{2}):.*$', '\\1') | list %}
            {{ hours | join(', ') }}
          {% else %}
            "Ei tietoa saatavilla"
          {% endif %}

############################################################
# 3. Binary-sensory kertoo, onko nyt halvin tunti.
############################################################

binary_sensor:
  - platform: template
    sensors:
      halvin_tunti:
        friendly_name: "Halvin tunti aktiivinen"
        device_class: power
        value_template: >-
          {% set data = state_attr('sensor.halvimmat_tunnit', 'data') | default([]) %}
          {% if not data %}
            false
          {% else %}
            {% set current_time = now().replace(minute=0, second=0, microsecond=0) %}
            {% set datetime_list = data | map(attribute='datetime') | map('as_datetime') | list %}
            {{ current_time in datetime_list }}
          {% endif %}
  

Tämä koodi integroi API:sta haetut halvimmat tunnit Home Assistant -järjestelmään. Sensori halvimmat_tunnit, hakee API:sta päivän halvimmat tunnit ja laskee niiden lukumäärän. Sensori halvimmat_tunnit_lista listaa haetut tunnit Home Assistantille parempaan muotoon. Lopuksi binary_sensor.halvin_tunti tarkistaa, onko juuri nyt käynnissä se tunti, jonka hinta on API:n mukaan alimman n tunnin joukossa kyseisenä vuorokautena.

CSV-muoto

GET https://elec.kasperikoski.fi/api/?start=2024-05-20&format=csv
Timestamp;Price (c/kWh);Hour
2024-05-20 00:00:00;5,24300;0
2024-05-20 01:00:00;4,87600;1
...

Telegram-botti @WattiRobot

Käytössäsi on myös Telegram-botti, joka kertoo sinulle paljon hyödyllisiä asioita sähkön hinnasta. Voit esimerkiksi kysyä siltä mitä sähkö maksoi 04.02.2014 taikka saada hälytyksen, kun sähkön hinta ylittää haluamasi rajan. Botti löytyy Telegramista nimellä @WattiRobot

Komento Toiminto
/today Näytä tämän päivän hinnat tunnin tarkkuudella
/tomorrow Ennustetut hinnat huomiselle (jos saatavilla)
/hintavahti Aseta hintavahti ja kynnyshinta hälytysten saamiseksi
/average Laskee päivän keskihinnan
/volatility Näyttää päivän hintavaihtelun (volatiliteetti)
/lowest Näyttää kuluvan päivän halvimman tuntihinnan
/highest Näyttää kuluvan päivän kalleimman tuntihinnan
/stat Näytä historialliset ääriarvot ja tilastot
/start Käynnistää botin
/help Listaa kaikki komennot ja ohjeet
DD.MM.YYYY Hae hinnat mille tahansa päivälle (2013 alkaen)
Ominaisuudet
  • Inline-näppäimistö hallintaan
  • Tehokas muistutus esimerkiksi 15 minuuttia ennen kalliin hinnan alkamista.
  • Kysely hyväksyy päivämäärän myös ilman etunollia
© Kasperi Koski 2025