Citobs-kansalaishavaintojärjestelmä on Suomen ympäristökeskuksen ylläpitämä tietojärjestelmä kansalaishavaintojen keräämiseen, tallentamiseen ja hyödyntämiseen. Se koostuu CitobsDB-tietokannasta sekä avoimista rajapinnoista havaintojen tallentamiseen ja lukemiseen. Kysymykset voidaan myös helposti asentaa näkymään mille tahansa verkkosivulle yksinkertaisella kartan sisältävällä lomakkeella. Sen avulla havaintotietoja voidaan lähettää ilman, että sivulta pitäisi poistua muihin järjestelmiin.
SYKE avoimen paikkatiedon standardienmukaisilla rajapinnoilla on kansalaishavainnot –aineisto, mistä voi löytää käyttökelpoisina pidetyt havaintojen tyypit, paikat ja ajat. Havainnon tarkempi sisältö on luettavissa Open311 rajapinnan kautta. Kansalaishavaintotarkoituksiin GeoReport v2 API on laajennettu Citobs järjestelmän käytössä tarpeellisin lisätoiminnoin, kuten ’locale’ tuella eri kielille tai kansalaishavaintokyselyiden ohjeiden ja varoitusten tarjonta, mutta myös standardinmukainen Open311 palvelu toimii.
Citobs-järjestelmän Open311 rajapinnasta voi lukea myös muiden palveluntarjoajien järjestelmiin eri kansalaishavaintoaiheiden havaintoilmoitusten kysymyspattereita, ja tiedonsyöttöön oikeuttavilla API-avaimilla havaintoja voi myös lähettää muista järjestelmistä. Avoimeen käyttöön tarkoitetut järjestelyt on nimenomaan suunniteltu siten, että kaikki palveluntarjoajat voisivat liittää ja käyttää SYKE:n Citobs-palveluita osana palveluntarjontaansa.
CitobsDB tietokanta
SYKE:n Citobs-järjestelmässä keräämät kansalaishavainnot kerätään CitobsDB –nimiseen järjestelmään. Microsoft SQL-palvelinteknologialla tuotetun palvelujärjestelmän määrittelevä koodi on avoimesti julkaistuEUPL-lisenssillä, mutta varsinaisesti sen käyttämistä tuetaan vain SYKEn tarjoamina rajapintapalveluina. CitobsDB järjestelmään on SYKEn sisäisesti käytettävissä CitobsUI -niminen mobiilioptimoitu selainpohjainen hallinta- ja ylläpitokäyttöliittymä. CitobsUI avulla SYKE voi hallinnoida eri kysymyspattereiden näkymistä palveluissa ja uusien Open311 rajapintapalveluiden määrittelyä uudenlaisten kansalaishavaintojen keräämiseksi. CitobsUI avulla voidaan myös hallinnoida yksittäisten havaintojen näkymistä avoimena tietona rajapintapalveluissa näkyvissä aineistoissa.
SYKE kansalaishavaintojen CitobsDB-järjestelmä on pohjimmiltaan avointa tietoa tallentava järjestelmä, joten siihen lähtökohtaisesti ei tallenneta esim. henkilötietoja. Ei-avointa tietoa sisältävät havaintotiedot lähtökohtaisesti poistetaan avoimena jaettavista rajapinta-aineistoista saatavilta.
Kansalaishavaintojen paikkatietorajapinta
SYKE:n avoimen tiedon palveluissa on julkaistuna paikkatietona myös pisteaineisto kansalaishavaintojen ilmoitetuista havaintopaikoista. Se on saatavissa JSON, SOAP, WMS ja WFS rajapintapalveluina sitä hyödyntävien järjestelmien käyttöön. Aineistoa voi tarkastella myös karttaselaimella.
Aineistosta voi nähdä kansalaishavainnon tyypin (Open311 service_code), havaintotapahtuman tunnisteen (Open311 service_request_id), havainnon tallennusajan, havaintoajan (mahdollisesti alku- ja loppuajat eriteltyinä, mikäli se on havaintotyypille ominaista) sekä havainnon hashtag-tunnisteet. Havainnon tarkempi sisältö on noudettavissa Open311 rajapinnasta.
Open311-rajapinta
CitObs:ssa on käytössä rajapinta, jonka avulla sovellukset voivat tallentaa ja hakea kansalaishavaintoja. Rajapinta perustuu Open311 GeoReport API v2 -standardiin, jota on laajennettu kansalaishavaintojen tarpeen näkökulmasta. Laajennukset on suunniteltu niin, että rajapinnan peruskäyttö on mahdollista kaikilla standardia noudattavilla päätelaitteilla. Laajennukset saa käyttöön kutsumalla rajapintaa "&extension=true" -parametrilla.
CitobsDB järjestelmän API-avaimen haltijat voivat saada pääsyn myös SYKE vetämän kansalaishavaintojen yhteistyöryhmän yhteiseen työtilaan, jossa sovelluskehittäjille on tarjolla jatkuvasti päivittyvää tarkempaa dokumentaatiota CitobsDB järjestelmässä käytetyistä menettelyistä.
Tarkempi kuvaus Citobs-kansalaishavaintojärjestelmän Open311-rajapinnasta, sen kyselyistä ja rajapinnan laajennuksista on viimeistelyssä, ja se julkaistaan 2019 keväällä. Lisätoimintojen käytöstä kiinnostuneet voivat olla yhteydessä sivun vaikkapa sivun kohdassa API-avain näkyvään kansalaishavainnot -osoitteeseen.
- Laajennukset vaikuttavat lähinnä havaintolomakkeiden luontiin API-avaimen avulla
- Vain open -tilassa olevat havainnot ovat palautettavissa hakutuloksina GET Service Request(s) -toiminnoilla ilman voimassaolevaa API-avainta, ja closed -tilassakin olevista vain samalla API-avaimella syötetyt havainnot saa rajapinnasta haettua.
- Tärkeimpänä yhteensopimattomana piirteenä todettakoon multivaluelist -tyyppisten attribuuttien käsittely: rajapinta palauttaa vain yhden arvon, joka on Unix/Linux -tyyppinen summa valittujen vaihtoehtojen järjestysnumeroista k -1 kahden potensseina.
- Tyypillisesti "&extension=false" -parametrivalinnalla järjestelmä muuten toimii Open311 V2 määrittelyjen mukaisesti.
Lisätietoja rajapinnan käytöstä yhdistämään eri tietojärjestelmiä kerrotaan sivulla CitobsDB ja kansalaishavaintojen keräämisjärjestelmien välinen yhteistyö
Citobs Widget
Jos ei halua tehdä omaa sovellusta kansalaishavaintojen keräämiseen, voi hyödyntää Citobs:in valmiita upotettavia liitännäisiä (widget). Oman Citobs Widgetin olemassa olevista kyselyistä voi määritellä täällä.
Tietylle kysymyspatterille tuotetun Citobs Open311 widget –koodin avulla verkkosivullasi ajetaan jarviwiki.fi –palvelimella oleva ohjelmakoodi. Sen avulla sivulle muodostuu määritellyn kyselyn kartta viimeaikaisista havainnoista, havaintojen syöttämiseen käytetty kysely ohjeineen ja otsikoineen, tai kaikki tässä mainitut elementit. Näin Citobs-järjestelmän kysymyspatterit saadaan näkymään kartalla varustettuina kyselylomakkeina esimerkiksi Järviwikin havaintojenlähetyssivuilla. Tällaisen karttakyselylomakkeen avulla havaitsija voi kännykällä tai verkkoselaimella ilmoittaa havaintonsa. Eri sivustoilla näkyvät saman kysymyspatterin karttakyselyt tallentavat tiedot samaan paikkaan SYKE:n kansalaishavaintojärjestelmään. Tästä järjestelmästä kaikki nämä sivustot voivat lukea kaikki tarjolla olevat SYKE:n kansalaishavaintojen kysymyspatterit tällaisia karttakyselylomakkeita varten. Widget on tarjolla myös HTML-tiedostona tallennettavassa muodossa, jolloin sen voi lähettää myös esimerkiksi sähköpostiliitteenä.
API-avain
Rajapinnan lukeminen on kaikille avointa eikä edellytä rekisteröitymistä. Rajapintaan kirjoittaminen eli havaintojen tallentaminen tietojärjestelmään vaatii sen sijaan sovelluskohtaisen API-avaimen hankkimista. Citobs järjestelmän käyttämisestä osana muualla kehitettyjä verkko- ja mobiilipalveluita voi tiedustella Kansalaishavaintojen yhteistyöryhmästä ja API-avaimen tilata sähköpostilla osoitteesta:
Yhteys- ja neuvontaosoite havaitsijoille
Havaitsijoiden neuvonnan ja opastuksen järjestää lähtökohtaisesti kunkin kansalaishavaintokampanjan järjestäjätaho, jolle kysymykset ensisijaisesti tulisi ohjata.
Mikäli neuvontaa muuten ei ole saatavilla, vilkkaimpina havaintoaikoina virka-aikaan havaitsijoiden kysymyksiin vastaa myös: