Liputuspäivien rajapinta

Kotiseurannan liputuspäivärajapinta palauttaa JSONia ilman kirjautumista. Vuosittaiset päivät lasketaan ilman tietokantaa; yksittäiset RSS-tiedotteet haetaan tietokannasta. Selain voi kutsua rajapintaa myös toisesta originista (CORS *). Julkinen osoite on https://app.kotiseuranta.fi/api/flag-days.

API-avain

Kirjautunut käyttäjä voi luoda avaimen Käyttäjätili-sivulla. Avain näytetään vain kerran, ja uuden luonti mitätöi vanhan. Samalta sivulta voi poistaa avaimen. Avaimen voi antaa HTTPS-pyynnön Authorization-otsakkeessa:

curl -H 'Authorization: Bearer ksfd_OMA_AVAIN' 'https://app.kotiseuranta.fi/api/flag-days?from=2026-10-20&days=7'

Avain tunnistaa integraation, mutta sitä ei tarvita julkisen liputusrajapinnan käyttämiseen eikä se nosta käyttörajaa. Älä sijoita avainta URL-osoitteeseen tai julkiseen selainkoodiin. Virheellinen tai poistettu avain palauttaa HTTP 401 ja INVALID_API_KEY. Tilin poisto poistaa myös sen avaimen.

Käyttöraja

Raja on 60 kysely-yksikköä minuutissa IP-osoitetta kohti ja 600 yksikköä minuutissa koko palvelulle. Yhden päivän kysely maksaa yhden yksikön. Aikavälikysely maksaa yhden yksikön alkavaa 31 päivää kohti: esimerkiksi 7 päivän jakso maksaa yhden ja 366 päivän jakso 12 yksikköä. Sama raja koskee avaimellisia ja avaimettomia pyyntöjä. HTTP 429 ja RATE_LIMITED kertovat rajan täyttymisestä; Retry-After ilmoittaa sekunnit seuraavaan minuuttiin.

Tee vain tarvitsemasi kyselyt, käytä mahdollisuuksien mukaan aikavälikyselyä yksittäisten päivien sijaan ja välimuistita vastaukset omassa palvelussasi. Älä kierrä rajoitusta vaihtamalla osoitetta tai kuormita rajapintaa automaattisella toistolla. Rajapinta on tarkoitettu liputuspäivien näyttämiseen ja integraatioihin ilman saatavuustakuuta; tiedot ja rajat voivat muuttua. Vuosittaisten päivien vastaukset voidaan välimuistittaa tunniksi, mutta yksittäiset uudet tiedotteet tulevat näkyviin vasta synkronoinnin jälkeen. Käyttörajan tilan tallennuksen tai API-avaimen tarkistuksen häiriö palauttaa HTTP 503.

Kysy päivää

GET /api/flag-days/2026-12-06

Vastaus sisältää data.date, data.is_recurring_flag_day, data.flag_days ja data.coverage. flag_days voi sisältää useamman merkinnän samalle päivälle. is_recurring_flag_day kertoo, onko ainakin yksi päivän merkintä vuosittainen. Tyhjä lista kertoo vain, ettei päivä ole rajapinnan tiedossa oleva liputuspäivä.

Kysy aikaväliä

GET /api/flag-days?from=2026-05-09&days=7

from on ISO-päivämäärä ja sisältyy jaksoon. days on päivien määrä 1–366 (oletus 7). Päivämäärät 2026–2100 hyväksytään. Vastaus sisältää data.from, data.days, data.coverage ja data.flag_days. Päivät ovat aikajärjestyksessä. Virheellinen parametri palauttaa HTTP 422 ja VALIDATION_ERROR.

Auringonlasku ja lipun lasku

Lisää molemmat desimaaliasteina ilmaistut koordinaatit lat ja lon, esimerkiksi:

GET /api/flag-days/2026-08-29?lat=60.17&lon=24.94

Jokainen palautettu päivä saa Suomen paikallisen ajan kenttiin sunset_at ja flag_lower_at muodossa HH:mm. lower_rule ilmaisee laskuajan perusteen: sunset, summer_limit, midsummer, independence_day, election_day, recommendation tai no_sunset. Jos aurinko ei laske kyseisenä päivänä, sunset_at on null; tavalliselle päivälle myös flag_lower_at on null. Yksittäisen suosituksen laskuaikaa ei arvata, jos sitä ei ole vahvistettu. Lasku on likiarvo eikä huomioi paikallista maastoa tai rakennuksia.

Kattavuus ja lähteet

coverage on published_days_and_listed_recommendations. Merkinnässä on category (official, established, regional tai recommendation), scope (esim. finland, aland, sami, helsinki), recurring ja alkuperäinen source-osoite. Mukana ovat vuosittaiset Suomen, Ahvenanmaan ja saamelaisten liputuspäivät, erikseen vahvistetut vaalipäivät sekä tiedossa olevat sisäministeriön liputussuositukset. Saamelaisten ja Ahvenanmaan merkinnät koskevat omia lippujaan. Vaalien ehdollista toista kierrosta, presidentin mahdollista virkaanastumista, ennen synkronoinnin käyttöönottoa julkaistuja muita suosituksia tai vasta ilmoittamattomia poikkeuspäiviä ei ennakoida.

Tiedotteiden synkronointi

Aja ensin migraatio 020_create_flag_day_announcements.sql. Ajoita sen jälkeen esimerkiksi cPanel-croniin päivittäin php /polku/backend/bin/sync_flag_days.php. Komento hakee valtioneuvoston virallisen RSS-syötteen, poimii vain sisäministeriön selvästi päivätyt yleiset liputussuositukset ja tallentaa päivän, otsikon, alueen sekä tiedotteen URL:n flag_day_announcements-tauluun. Samat tiedotteet voi käsitellä uudelleen ilman duplikaatteja. Syötteen ulkopuoliset tai epäselvästi päivätyt tiedotteet on tarkistettava ja lisättävä erikseen; lähteen epäonnistuessa vanhat tiedot säilyvät. Julkinen kysely lukee tallennetut merkinnät kannasta; kantavirhe kirjataan palvelimen lokiin ja vuosittaiset päivät ovat silti käytettävissä.

Lähteet: Sisäministeriön liputuspäivät ja Yliopiston almanakkatoimiston vuosittainen luettelo. Tarkista muutokset kalenteriin ja liputussääntöihin vuosittain.