Helsingin seudun ympäristöpalvelut
eRaportin tilastorajapinta

Rajapinta tarjoaa ohjelmalisen väylän jäte- ja vesikulutustietojen hyödyntämiseksi muissa järjestelmissä. Tietoja voi hakea rajapinnasta eRaportissa muodostetuilla koontiraporttitunnuksilla. Raporttitunnusten kanssa tulee huomioida, että tuotanto- ja tuotantotesti-ympäristöihin on kuhunkin omat koontiraporttitunnuksensa. Tuotantotesti-ympäristön koontiraporttien hallinta tapahtuu samaan tapaan eRaportti-sovelluksen kautta kuin tuotantoympäristössä.

Halutut kohteet lisätään ensin eRaportissa koontiraportille ja tämän jälkeen koontiraportin API-osiosta voidaan noutaa oikeat REST-osoitteet, joilla tiedot voi noutaa JSON-muodossa.

Siirry tästä tuotantotesti-ympäristön eRaportti sovellukseen

1 - Rajapinnan käyttöehdot

Rajapinnan käyttö on sallittu sekä ei-kaupalliselle että kaupalliselle käytölle, eikä sen käytöstä peritä maksua. Käyttöehto on voimassa toistaiseksi ja HSY varaa oikeuden muuttaa sitä ennalta ilmoittamatta. Testiympäristön käyttö on vapaata ja tällä sivulla esitetystä esimerkkisanomasta löytyy testiympäristön Api-avain. Tuotantokäyttöä varten järjestelmäkohtainen avain on saatavissa sähköpostitse osoitteesta timo.vakkilainen@hsy.fi.

2 - Julkaisuhistoria

3 - Rajapinnan tarjoamat palvelut

3.1 - Rajapinnan tila

Palvelu palauttaa rajapinnan tilan esim. automaattista valvontaa tai virheen etsintää varten. Kun palvelu toimii normaalisti, rajapinta palauttaa sanoman runko-osassa tekstin OK. Virhetilanteen yhteydessä sanoman vastauksen runko-osa alkaa tekstillä WARN tai FAIL ja runko-osan loppu sisältää vapaana tekstinä hieman tarkempaa tietoa virhetilanteesta.

3.1.1 - Rajapinnan kutsuminen

Kutsun lähettäminen
Osoite
  • TESTI: https://raportit.hsy.fi:8443/report/rest/v1/status/
  • TUOTANTO: https://raportit.hsy.fi/report/rest/v1/status/
  • (Suora linkki viimeisimpään versioon ilman versionumeroa: .../rest/status/)
Metodi GET

3.1.4 - Esimerkkisanoma tilakyselyn testaamiseksi.

3.2 - Rajapinnan versio

Palvelu palauttaa rajapinnan version.

3.2.1 - Rajapinnan kutsuminen

Kutsun lähettäminen
Osoite
  • TESTI: https://raportit.hsy.fi:8443/report/rest/v1/version/
  • TUOTANTO: https://raportit.hsy.fi/report/rest/v1/version/
  • (Suora linkki viimeisimpään versioon ilman versionumeroa: .../rest/version/)
Metodi GET

3.2.4 - Esimerkkisanoma versiokyselyn testaamiseksi.

3.3 - Kulutustietorajapinta

Kulutustiedot voidaan noutaa rajapinnasta kuukausittain tai vuosittain jaksotettuna. Sanoma voi sisältää kerrallaan yhden kohteen tai kaikkien kohteiden kulutustiedot. Lisäksi voidaan valita sisällytetäänkö sanomaan pelkästään jäte- tai vesitiedot vai haetaanko kerralla kaikki tiedot.

Jätetiedot: Rajapinnassa esitetyt jätetiedot päivittyvät raporttikohteen laskutusrytmin mukaisesti, eli raportilla esitetyt jätetiedot perustuvat laskutuksen tietoihin. Näin ollen kohteiden tiedot päivittyvät rajapinnassa 1,2,4,6 tai 12 kuukauden jaksoissa.

Vesitiedot:Raportilla esiintyvät vesitiedot perustuvat laskutukseen ilmoitettuihin vesimittarilukemiin ja lukemien tarkkuus riippuu kunkin kohteen lukemienilmoitusrytmistä. Useissa kohteissa lukema ilmoitetaan ainoastaan kerran vuodessa. Lukemat on mahdollista ilmoittaa myös sähköisen rajapinnan kautta, jolloin ilmoitusrytmi voi olla kerran kuukaudessa.

Vesitilastoissa on vuodenvaihteeseen liittyvä poikkeuskäsittely, joka vuoden vaihtumisen jälkeen täydentää tilastot edellisvuoden lopun osalta arvioidulla kulutuksella. Tämä toiminto suoritetaan, jotta täydet vuodet olisivat heti vuoden vaihtumisen jälkeen keskenään vertailtavissa, eikä vasta sitten kun käyttöpaikalle saapuu seuraava ilmoitettu lukema. Eli esimerkiksi käyttöpaikalle, jolla viimeisin lukema on kesäkuulta:

Tämä menettely varmistaa sen, että täydet vuodet ovat keskenään vertailtavissa. Arvioitu kulutus täsmää pääsääntöisesti hyvin todellisen kulutuksen kanssa, ellei käyttöpaikassa ole esim. tehty remonttia tai käyttö on hyvin vaihtelevaa.

3.3.1 - Rajapinnan kutsuminen

Taulukoissa on esitetty erillään rest-kutsun perustiedot sekä varsinaiset kyselyosat yhden kohteen tai yhden koontilistan kohteiden tiedoille.

Kutsun tiedot

Kutsun lähettäminen
Osoite
  • TESTI: https://raportit.hsy.fi:8443/report/rest/<kyselyosa>
  • TUOTANTO: https://raportit.hsy.fi/report/rest/<kyselyosa>
Metodi GET
Headers
  • Content-type: application/json;charset=UTF-8
  • X-API-KEY: HSYTEST51_9NOOzOv77pD4Mhx2Kgol86NFSdl9rpOPGNzlQ0A7
  • (Huom. X-API-KEY tulee olla isoilla kirjaimilla)
Api-avain
  • TESTI: HSYTEST51_9NOOzOv77pD4Mhx2Kgol86NFSdl9rpOPGNzlQ0A7
  • TUOTANTO: Katso kohta Rajapinnan käyttöehdot
Rajoitukset
  • Vesitiedot raportoidaan tällä hetkellä vain vuositasolla.
  • Jätetiedot raportoidaan kohteen laskutusrytmin tarkkuudella, eli kohteesta riippuen 1,2,4,6 tai 12 kuukauden jaksoissa.
  • Rajapinnan samanaikaisen liikenteen määrä on rajattu, joten palvelun saatavuus saattaa vaihdella kuormitustilanteen mukaan.
  • Testiympäristön tiedot vastaavat melko pitkälti tuotannon tietoja ja päivittyvät pääosin päivittäin. Täydelliset tiedot päivitetään tuotannosta testiympäristöön pari kertaa vuodessa.
  • Raporttitunnusten kanssa tulee huomioida, että tuotanto- ja tuotantotesti-ympäristöihin on kuhunkin omat raporttitunnuksensa. Listojen hallinta tuotantotestin eRaportti-sovelluksessa.

Kutsun osoiteen loppu yksittäiselle kohteelle

Yksittäisen kohteen tietojen noutaminen
Esimerkki https://raportit.hsy.fi:8443/report/rest/v1/reporting/both/WT-MOCK-WATER-ID/WS-MOCK-WASTE-ID/YEARLY/fi
Jätetiedot <osoite>/v1/reporting/waste/{wasteServiceNumber}/{period}/{language}
Vesitiedot <osoite>/v1/reporting/water/{waterServiceNumber}/{period}/{language}
Jäte- sekä vesitiedot <osoite>/v1/reporting/both/{waterServiceNumber}/{wasteServiceNumber}/{period}/{language}

Kutsun osoiteen loppu koontilistalle

Koontilistan kohteiden tietojen noutaminen
Esimerkki https://raportit.hsy.fi:8443/report/rest/v1/reporting/both/list/MOCK-LIST-ID/YEARLY/fi/strict-fail
Jätetiedot <osoite>/v1/reporting/waste/list/{listId}/{period}/{language}
Vesitiedot <osoite>/v1/reporting/water/list/{listId}/{period}/{language}
Jäte- sekä vesitiedot <osoite>/v1/reporting/both/list/{listId}/{period}/{language}

Poikkeuskäsittelyt

Kyselyille yhteiset poikkeuskäsittelyt
Esimerkki https://raportit.hsy.fi:8443/report/rest/v1/reporting/both/list/MOCK-LIST-ID/YEARLY/fi/mode-strict
Kaikki kyselyt <osoite>/<kyselyosa>/{mode}

3.3.2 - Kyselyosan parametrit

Kenttä sanomassa Kentän nimi Muoto Esimerkki Kuvaus
X-API-KEY Api-avain (Header) HSYTEST01_1...7 GET-sanoman otsikkotiedoissa X-API-KEY-kenttässä välitettävä tieto. Rajapinnan käyttöön vaadittava järjestelmäkohtainen tunnus. Katso lisätietoja kohdasta Rajapinnan käyttöehdot.
wasteServiceNumber Jätepalvelun tunniste Merkkijono WSpjh7d...6fSf Koontiraportilta poimittu jätepalvelun tunnus. Tunnus on muodostettu kohteen koontiraportille lisäämisen yhteydessä, esimerkiksi jätelaskulta löytyvien tunnisteiden avulla. Tunnus ei näin ollen ole suoraan pääteltävissä laskulla esiintyvistä tunnisteista. Raportoitavat kohteet tulee siis ensin lisätä eRaporttipalvelun käyttöliittymässä koontilistalle, jotta niille saadaan raportointirajapinnassa käytettävät tunnisteet. Kohteiden tunnukset löydät koontiraportin API-osiosta.
waterServiceNumber Vesisopimuksen tunniste Merkkijono WTsdfsK...6sr0 Koontiraportilta poimittu vesisopimuksen tunnus. Tunnus on muodostettu kohteen koontiraportille lisäämisen yhteydessä, esimerkiksi vesilaskulta löytyvien tunnisteiden avulla. Tunnus ei näin ollen ole suoraan pääteltävissä laskulla esiintyvistä tunnisteista. Raportoitavat kohteet tulee siis ensin lisätä eRaporttipalvelun käyttöliittymässä koontilistalle, jotta niille saadaan raportointirajapinnassa käytettävät tunnisteet. Kohteiden tunnukset löydät koontiraportin API-osiosta.
listId Koontiraportin tunniste Merkkijono 896Ws7j7...qd73 Koontiraportin tunnisteen saa eRaportti-palvelun käyttöliittymästä. Se muodostetaan lisäämällä halutut kohteet koontiraportille.
period Raportointi jakso Merkkijono YEARLY Muodostettavan raportointijakson pituus MONTHLY = kuukausittainen tai YEARLY = vuosittainen. Tällä hetkellä ainoastaan jätetiedot noudattelevat jaksotusta. Vesitiedot raportoidaan aina vuositasolla.
language Kieli Merkkijonovakio fi Rajapinnan palauttammisssa koodistoarvoissa ja virheilmoituksissa käytettävä kieli. Tuetut kielet ovat fi=suomi sekä sv=ruotsi.
mode Poikkeuskäsittely Merkkijonovakio mode-strict Parametrillä mahdollistetaan poikkeuskäsittelyiden lisääminen rajapintaan.
  • mode-strict Tässä tilassa vastaussanoman virhelistassa (messages) olevat varoitukset puutteellisista jäte- tai vesitunnuksista aiheuttaa koko kyselyn merkkaamisen epäonnistuneeksi, jolloin moments-lista jää tyhjäksi ja viestin success-kentän arvoksi tulee false.

3.3.3 - Paluusanoman kentät

Esimerkkisanoma:

KENTTÄESIMERKKIARVO, KUVAUS
{ }

Sanoman kentät:

Kenttä sanomassa Kentän nimi Muoto Esimerkki Kuvaus
success Kutsun onnistuminen Totuusarvo true Sanoman muodostusta pidetään aina onnistuneena, jos kutsussa ei tapahdu järjestelmävirhettä. Jos annetuilla tunnuksilla ei löydy raporttikohdetta,
  • success=true,
  • messages-kenttä sisältää ilmoituksen siitä, ettei kohdetta löytynyt ja
  • moments-lista on tyhjä - ellei kyseessä ole koontilista ja muilla koontilistan tunnuksilla löytyi tilastoja.
Sivun alalaidasta löytyy esimerkki järjestelmävirheestä, jossa success=false.
messages Virheilmoitukset Merkkijonolista - Sanoma sisältää listan virheilmoituksia, jotka ovat muodostuneet yhden kohteen tai listan kohteiden tietojen haun yhteydessä. Virheilmoituksissa esiintyviä raporttitunnuksia vastaavien kohteiden tarkemmat tunnistetiedot voi käydä tarkistamassa käyttöliittymän API-osiosta, jotta tunnistaa mihin kohteeseen virhe liittyi.
moments Raporttijaksot Lista Tietue Raporttijaksot sisältää listanana vuosi- tai kuukausikohtaiset tilastot kaikille raporttikohteille, joille löytyy tilastoja kyseisellä jaksolla. Näin ollen kaikille jaksoille ei todennäköisesti löydy tilastoja kaikille kohteille. Lisäksi lista sisältää vain ne raporttijaksot, joille sisältyy tilastoja. Näin ollen esimerkiksi kuukausikohtaisissa tilastoissa on raporttijakso vain joka toiselle kuukaudelle, kun kohteiden laskutusjakso on 2kk.
moment Jakso Merkkijono "2003" tai
"2003-01"
Raporttijakso on vuosi tai vuosi sekä viivalla erotettuna kuukausi. Vesitilastot ovat tällä hetkellä saatavilla vain vuosittain tilastoituna, joten vaikka tilastointijaksoksi olisi valittu kuukausi, vesitilastojen raporttijakso on esim. 2013, vaikka sama vastaussanoma sisältäisi jätetilastoja jaksoille "2012-12", "2013-01", jne.
customers Raporttikohde Tietue - Jäte- ja vesikohteen yhdistelmän muodostama raportointikohde. Raportointikohde voi sisältää molempien sopimusten tiedot tai vain jäte- tai vesisopimuksen tiedot. Pääosin kuhunkin kiinteistöön liittyy yksi jätepalvelusopimus ja yksi vesisopimuskokonaisuus. Joissain tapauksissa kiinteistöön voi liittyä useampi vesi- tai jätesopimus, mutta näiden linkittäminen yhdeksi raportointikohteeksi ei ole palvelussa mahdollista.
address Kohteen nimi Merkkijono Esimerkkitie 1, 00100, Helsinki (55555 / BB111111111) Koontiraportilla kohteen nimenä käytettävä osoite, joka on yhdistelmä jäte- ja vesisopimuksen osoitteesta. Osoitteen perään on lisätty sulkeisiin vedenkäyttöpaikan tunnus sekä jätepalvelutunnus, tai viiva jos parista puuttuu toinen sopimus.
wasteContractNumber Jätepalvelutunnus Merkkijono BB111111111 Laskulla esiintyvä jätesopimuksen jätepalvelutunnus. Tunnusta voidaan käyttää raportoitavan tiedon kohdistamiseen kutsuvassa järjestelmässä. Tunnuksen käyttäminen kohdistamiseen on suositeltavampaa kuin osoitteen käyttäminen. Jätepalvelutunnuksella on muutama eri esitysmuoto, joten kutsuvassa järjestelmässä voidaan joutua tekemään triviaalimuunnos esitysmuotojen välillä.
waterUsageLocationNumber Käyttöpaikan numero Merkkijono 55555 Laskulla esiintyvä vesisopimuksen vedenkäyttöpaikan numero. Tunnusta voidaan käyttää raportoitavan tiedon kohdistamiseen kutsuvassa järjestelmässä. Tunnuksen käyttäminen kohdistamiseen on suositeltavampaa kuin osoitteen käyttäminen.
waterUsageLocationAddress Käyttöpaikan osoite Merkkijono Esimerkkitie 1 Vedenkäyttöpaikan osoite kuvastaa päävesimittarin sijaintia, ja näin ollen saattaa olla eri osoite kuin kiinteistön osoite tai jätteiden nouto-osoite. Tällä hetkellä käyttöpaikan osoite sisältää vain katuosoitteen ilman postinumeroa ja kaupunkia.
wasteCollectionAddress Nouto-osoite Merkkijono Esimerkkitie 1, 00100, Helsinki Jätteiden nouto-osoite kuvastaa jätepisteen sijaintia, ja näin ollen saattaa olla eri osoite kuin kiinteistön osoite tai vedenkäyttöpaikan osoite.
waste Jätetilastot Tietue - Lista jaksossa kerätyistä jätteistä. Jätetilastot sisältävät omina tietueinaan kerätyt "varsinaiset" jätelajit sekä Muut-jätelajin, johon koostetaan kertaluontoiset jätteet, kuten astian vierestä kerätyt jätesäkit. Jätelajien nimet tulevat koodistosta ja täsmäävät kodien nykyhetken arvoon. Näin ollen jätelajien nimet voivat muuttua tulevaisuudessa ja muutokset saattavat vaikuttaa myös aiempien vuosien jätelajien nimiin. Muutoksia koodistoarvoissa tapahtuu hyvin harvoin, jos koskaan. Uusien jätelajien lisääminen koodistoon on tavallisempaa.

Varsinaisia jätelajeja ovat:
  • Biojäte,
  • Biologinen jäte,
  • Energiajäte,
  • Kartonki,
  • Lasi,
  • Metalli,
  • Muovi,
  • Pahvi sekä
  • Sekajäte
Lisäksi muut sekalaiset jätelajit yhdistettynä jätelajiin:
  • Muut
water Vesitilastot Tietue - Lista vedenkulutuksen tiedoista. Tällä hetkellä saatavilla ainoastaan tieto "Vedenkulutus vuosittain".
type Tyyppi/Nimi Merkkijono Sekajäte Tilastoidun tiedon nimi, kuten sekajäte tai vedenkulutus vuodessa.
amount Määrä Merkkijono 1000 Merkkijonona esitetty kokonaisluku. Määrään liittyvä yksikkö löytyy omasta kentästään.
cost Kustannus Merkkijono 1000 Merkkijonona esitetty kokonaisluku. Kustannukseen liittyvä yksikkö löytyy omasta kentästään. Tällä hetkellä vesitilastoille ei ole saatavilla kustannustietoa.
amountUnit Määrän yksikkö Merkkijono Kg Määrän yksikkö. Tällä hetkellä mahdollisia yksiköitä ovat Kg (kilogrammaa), t (tonnia), m³ (kuutiometriä) sekä kpl (kappaletta).
costUnit Kustannuksen yksikkö Merkkijono 1000 Kustannuksen yksikkö. Tällä hetkellä ainoa mahdollinen yksikkö on EUR (euroa).

3.3.4 - Esimerkkisanomat joilla voi testata tilastorajapintaa. Tuotantokäyttöä varten ole yhteydessä HSY:hyn. Katso lisätietoja kohdasta Rajapinnan käyttöehdot.