Kirjastohakemiston rajapinta v3

Vanhat dokumentaatiot: API V2, API V1

HUOM 2018-05-31:

1. Kirjastojen käyntiosoitteisiin on lisätty postitoimipaikka (kenttä area). Se on monikielinen tekstikenttä, johon voidaan syöttää tieto siitä, minkä postitoimipaikan alueella kirjasto sijaitsee.

2. Tunnistekentissä useamman arvon erottimena sallitaan nyt pilkun ohella myös välilyönti (ts. url-enkoodattuna + tai %20): ?id=123+456+789. Uudella merkintätavalla on sama merkitys kuin vanhalla. Tarkoitus on helpottaa rajapinnan käyttöä niissä tapauksissa, kun hakuehtoja luetaan html-attribuuteista, jolloin on luonnollista käyttää välilyöntiä arvojen erottimena.

HUOM 2017-01-31: Rajapintaan on tehty bugikorjaus. Organisation-tietueeseen upotetuissa palvelutiedoissa (services) ollut kenttä website on muutettu monikieliseksi, mikä sen on ollut tarkoituskin olla. Kenttä on aiemmin ollut kieletön, yksiarvoinen kenttä.

Johdanto

Kirjastot.fi tarjoaa ilmaisen ja julkisen rajapinnan Kirjastohakemiston tietojen käyttöön kolmannen osapuolen sovelluksissa. Kirjastohakemisto sisältää yleisten kirjastojen, kirjastoautojen sekä oppilaitos- ja muiden erikoiskirjastojen esittelyt ja yhteystiedot. Kirjastohakemiston julkisivu sijaitsee osoitteessa http://hakemisto.kirjastot.fi.

Rajapinnan kolmas versio korvaa kaikki aiemmat versiot, jotka tullaan sulkemaan myöhemmin tulevaisuudessa käytön vähennyttyä.

Teknisissä ongelmissa voi olla yhteydessä Kirjastot.fi'n tekniikkatiimiin: tekniikka@kirjastot.fi. Sisältöjä koskevista virheistä voi ilmoittaa osoitteeseen hakemisto@kirjastot.fi.

Käyttöehdot

Rajapinnan käyttö on ilmaista sekä kaupallisessa että ei-kaupallisessa tarkoituksessa. Yleisiä käyttörajoituksia ei ole, mutta Kirjastot.fi varaa oikeuden estää kohtuutonta rasitusta aiheuttavien osapuolten pääsyn rajapintaan.

Sisältöjen lisenssi

Rajapinnan avulla tuotetut tiedot ("teokset") on lisensoitu Creative Commons 4.0 Nimeä -lisenssillä, joka sallii tietojen muokkaamisen sekä jakamisen uudelleen eri medioissa. Tällöin täytyy mainita aineiston tarjoaja eli Kirjastot.fi, CC 4.0 -lisenssi sekä linkki rajapinnan etusivulle (tähän dokumentaatioon).

Rajapinnan kuvaus

Rajapinta noudattaa rest-periaatetta. Kutsut tehdään tavallisina http-pyyntöinä ja kyselyn parametrit välitetään osoitteen query-osassa eli tavallisina get-parametreina. Pyyntöihin vastataan asiakasohjelman määrittämässä muodossa, joka voi olla xml, json tai jsonp. Vastaukseen käytettävän tietotyypin voi asettaa http-protokollan mukaisesti Accept-otsakkeella tai get-parametrilla format, jolla on korkeampi prioriteetti.

Lisäksi 28.06.2016 alkaen vastauksen tietotyypin voi määrittää käyttämällä "tiedostopäätteitä". Tämä parantaa yhteensopivuutta joidenkin js-kirjastojen kanssa, jotka tunnistavat vastauksen tyypin ensisijaisesti www-osoitteen avulla.

Käytetty merkistö on utf-8. Oletusarvoisesti rajapinta palauttaa 50 tulosta kerrallaan, sivutusta voi hallita parametrein limit ja skip.

Jsonp-muotoa käyttäessä täytyy myös määrittää ns. callback-funktion nimi get-parametrilla callback. Tyypit json ja jsonp ovat 28.06.2016 alkaen aliaksia toisilleen. Ainoa ero on se, että jsonp-tyypin kanssa callback-parametrin puuttuminen aiheuttaa virheen.

Kyselyiden rakenne

Kutsuissa käytettävät polut myötäilevät rest-filosofiaa. Polku sisältää haettavan resurssin tyypin sekä mahdollisen id-tunnisteen. Muut parametrit määritetään pyyntöosoitteen query string -osassa. Suodinehdot on mahdollista muuttaa kieltäviksi eli not-muotoisiksi lisäämällä parametrin nimen perään miinusmerkki. Kyselyn parametrit yhdistetään AND-konjunktiolla, eli tulosjoukkoon sisältyvät ne tietueet, jotka täsmäävät kaikkiin hakuehtoihin. Mikäli yksittäiselle parametrille on annettu monta arvoa, riittää että tietue täsmää johonkin niistä.

Kutsujen rakenne on seuraavanlainen:

https://api.kirjastot.fi/v3/organisation?name=pasila&city.name=helsinki&format=jsonp&callback=foo
https://api.kirjastot.fi/v3/organisation/81371?format=jsonp&callback=foo
https://api.kirjastot.fi/v3/organisation/81371.json&callback=foo
 

Tietotyypit

Tähän on listattu rajapinnan tukemat tietotyypit. Kaikille tietotyypeille pätevät yllä mainitut kaksi kutsuvaihtoehtoa.

Sisältöjen kielet ja kielikoodit

Sisällöt tuotetaan pääsääntöisesti suomeksi ja aluekohtaisesti ruotsiksi. Kirjastot päättävät itsenäisesti, millä kielillä he tarjoavat tietojaan.

Yleiset parametrit

Kaikki kutsut tukevat tiettyjä parametreja, joilla voidaan vaikuttaa vastauksen tietotyyppiin ja palautettavien tietojen laajuuteen.

Hakuehdot ja järjestäminen

Useita hakuehtoja käytettäessä tulosjoukko sisältää ne tietueet, jotka täsmäävät kaikkiin hakuehtoihin. Mikäli yksittäinen parametri hyväksyy monta arvoa (pilkuilla erotettuna listana), tietueiden tulee täsmätä johonkin kyseisen joukon arvoista. Hakuehdot voi kääntää kielteisiksi lisäämällä parametrin nimen perään miinusmerkin. (?city.name-=helsinki)

Hakukyselyiden palauttamien tulosjoukkojen järjestämiseen voi käyttää pääsääntöisesti kaikkien suodinparametrien nimiä. Järjestäminen useamman kuin yhden parametrin avulla on sallittua. Järjestys on oletusarvoisesti pienimmästä suurimpaan, mutta sen voi kääntää ympäri parametrikohtaisesti liittämällä parametrin eteen miinusmerkin (?sort=city.name,-name).

Kieliriippuvaisten kenttien mukaan suotiessa ja järjestettäessä käytetään valittua kieltä. Mikäli kieltä ei ole valittu, tulosjoukko sisältää arvot kaikilla kielillä, mutta suotiminen ja järjestäminen tehdään suomenkielisten arvojen perusteella.

Kuvat

Tietueisiin lisätyistä kuvista luodaan automaattisesti eri kokoja. Rajapinta luo automaattisesti linkit kaikkiin saatavilla oleviin kokoihin. Kuvatietojen arvo on joko null, mikäli kuvaa ei ole saatavilla, tai avain-arvo-pareista muodostuva hash, jolloin avaimena toimii kuvakoon tunniste ja arvona täysi osoite kuvaan.

Ilmoitetut resoluutiot ovat enimmäisarvoja, eli mitat alittavia kuvia ei skaalata suuremmiksi. Pääsääntöisesti säilyttävät alkuperäiset mittasuhteensa kaikissa kokoluokissa.

Organisaatiot / kirjastot

Kutsun osoitteen muoto on seuraava:

https://api.kirjastot.fi/v3/organisation?parametrit
https://api.kirjastot.fi/v3/library?parametrit

Organisaation ja kirjaston (library) välinen ero type-parametrin oletusarvossa. Organisaatio on geneerinen tyyppi, joka kattaa toimipisteiden ohella osastot, kirjastoautojen pysäkit sekä erilaiset metatietueet jne. Library-tyyppi on oikopolku, jolla suoditaan pois muut kuin toimipisteet ja kirjastoautot.

M := hyväksyy monta valintaa kerralla pilkuin erotettuna listana (foo,bar,baz) S := kenttää voi käyttää järjestämiseen sort-parametrin arvona

Lisäksi tulokset voi järjestää ehdoilla modified sekä created, jotka ilmaisevat muokkaus- ja luontipäivämääriä.

Organisaatiotyypit (type)

Toimipisteiden alatyypit (branch_type)

Valinnaiset tiedot (with)

Siirrettävän tiedon optimoimiseksi organisaatiotietueet eivät oletuksena sisällä kaikkia vähemmän tarpeellisia tietolohkoja. Ne voidaan 'aktivoida' antamalla with-parametrille taulukossa esiteltyjä arvoja. Kyseiset arvot vastaavat tietueessa samannimistä kenttää, jonka arvona on joko assosiatiivinen taulukko tai lista.

Organisaatiokyselyn relaatiot (refs)

Refs-parametrilla voidaan asettaa rajapinta palauttamaan linkitetyt tietueet osana tulosjoukkoa. Nämä tietueet löytyvät tuloksen juuresta kentästä references. Se käsittää joukon avain-arvo-pareja, missä avain on alitietueen tyyppi (esim. city) ja arvo on vastaavalla tavalla rakenteistettu joukko avain-arvo-pareja.

Typistetty esimerkki

{
  "total": 2,
  "type": "organisation",
  "items": [{...}, {...}],
  "references": {
    "city": {
      "16094": {
        "id": 16094,
        "name": {
          "fi": "Salo"
        }
      },
      "16031": {
        "id": 16031,
        "name": {
          "fi": "Nurmes"
        }
      }
    }
  }
}

Kuvaustekstin muotoilut

Kirjastojen kuvausteksti (extra.description) on html-muotoiltu merkkijono. Vanhat rajapinnat palauttivat kuvaustekstin plaintext-muodossa, mutta uudessa Kirjastohakemistossa kyseinen kuvaus on muutettu rikastekstiksi. Kuvauksen syöttämiseen käytetään CKEditor-tekstieditoria ja sen oletusmuotoiluja. Teksti voi sisältää linkkejä, listoja ja taulukoita.

Kirjastokohtaiset palvelutiedot

Palveluiden nimet

Organisaatioon liitetyissä palvelutiedoissa on kaksi kenttää palvelun nimelle. Pääasiallinen nimi on name-kentässä ja sen arvo on aina sama kuin palvelulla, johon id-kentän arvo viittaa. Lisäksi on olemassa kenttä custom_name vaihtoehtoiselle nimelle. Kyseistä nimeä voidaan käyttää silloin, kun palvelulle on haluttu määrittää täsmällisempi, organisaatiokohtainen nimi. Oletusarvo on null.

Kirjastohakemistossa käyttötarkoitus custom_namelle on korvata palvelun alkuperäinen nimi kirjaston esittelysivulla. Yleisessä haussa palveluiden suotimiseen käytetään vain yleistä nimeä.

Muuta

Upotetut palvelutiedot eroavat yleisistä palvelutiedoista siten, että niissä on lisäkenttiä, jotka kertovat palvelun saatavuudesta kyseisessä organisaatiossa (kirjastossa). Myös palvelun kuvausteksti vaihtelee toimipisteittäin. Upotetuissa palvelutiedoissa ilmoitettu palvelun ID-tunniste on sama kuin samannimisen palvelun tunniste yleisissä palvelutiedoissa.

Esimerkkejä kyselyistä

Haetaan Oulussa ja Rovaniemellä sijaitsevia kirjastoja. (Kunnan ID-tunniste testiympäristössä.)

https://api.kirjastot.fi/v3/library?city=15404,15453
https://api.kirjastot.fi/v3/library?city.name=oulu,rovaniemi

Haetaan Uudenmaan ja Pohjois-Savon alueella sijaitsevia kirjastoja. (Maakunnan ID-tunniste testiympäristössä.)

https://api.kirjastot.fi/v3/library?region=963,974
https://api.kirjastot.fi/v3/library?region.name=uusimaa,pohjois-savo

Haetaan kirjastoja, jotka sijaitsevat 10 km:n säteellä Helsingin rautatieasemalta ja joista löytyy kopiokone. https://api.kirjastot.fi/v3/library?geo=60.171142,24.944387&distance=10&service.name=kopiokone

Kirjastot joilla on palvelut (id-tunnisteet) X ja Y. https://api.kirjastot.fi/v3/library?service=X,Y

Pasilan kirjaston tietue sisältäen aukioloajat marraskuulle 2015. https://api.kirjastot.fi/v3/library/81371?with=schedules&period.start=2015-11-01&period.end=2015-11-30

Aukioloajat (opening_time)

https://api.kirjastot.fi/v3/opening_time?parametrit

Aukiolotietoja voi hakea erikseen massahakuna. Huomaa, että sivutus pätee myös aikatauluhaussa, joten suurilla aikaväleillä tai kirjastojen määrillä kaikkia tuloksia ei välttämättä näytetä yhdellä kertaa.

Aukioloajat ilmoitetaan päiväkohtaisina tietueina. Yhdellä kyselyllä on mahdollista hakea monen organisaation aukiolotiedot samalla kertaa.

M := hyväksyy monta valintaa kerralla pilkuin erotettuna listana (foo,bar,baz) S := kenttää voi käyttää järjestämiseen sort-parametrin arvona

Aukiolokyselyn relaatiot (refs)

Kuten organisaatiokyselyissä, tässäkin refs-parametrilla voidaan käskeä rajapintaa sisällyttämään valituntyyppiset linkitetyt tietueet tulokseen kenttään references.

Suhteelliset aikavälit

Aikavälin rajoittamiseen voi käyttää myös suhteellisia arvoja. Referenssipisteenä käytetään aina kuluvaa päivää. Suhteellisen aikavälin määrittämiseen voi käyttää yksikköinä päiviä, viikkoja sekä kuukausia. Myös negatiiviset arvot sekä nollamääräiset arvot ('0d', '0w', '0m') ovat sallittuja.

Yksikön ja parametrin merkitys

Vaikka suhteellinen arvon lähtökohtana käytetään aina kuluvaa päivää, arvoa vastaava tarkka päivämäärä riippuu myös käytetystä yksiköstä sekä siitä, onko parametri alaraja (period.start) vai yläraja (period.end). Myös nolla-arvoa vastaava eksakti päivämäärä vaihtelee sen kanssa käytetyn yksikön mukaan. Suhteellisten aikavälien logiikka on ajateltu sellaiseksi, että ne palauttavat aina käytetyn yksikön mukaisesti täysiä "kalenterijaksoja" eli täysiä viikkoja tai kalenterikuukausia.

Esimerkkejä

Taulukon esimerkkiarvot on laskettu käyttäen referenssipäivänä perjantaita 6.11.2015.

Monta aukioloa per päivä

Jotkin kirjastoista voivat olla hetkellisesti suljettuna keskellä päivää, mutta yleisesti ottaen tämä on harvinaista. Tämän vuoksi rajapinnan palauttamissa tietueissa aukiolot ilmoitetaan kahdella eri tavalla.

1. Yksinkertaistettu muoto: aukiolotietueen juuressa kentät opens ja closes.
2. Täydellinen muoto: lista arvopareja opens ja closes kentässä times.

Molemmat esitysmuodot pätevät kaikissa tilanteissa. Niissä tapauksissa, missä kirjasto on päivän aikana auki pätkittäin, yksinkertaistettu muoto ilmoittaa päivän ensimmäisen aukeamisajan ja viimeisen sulkeutumisajan.

Katso myös seuraavasta kappaleesta lisähuomautus koskien omatoimikirjastojen aukioloja.

Osastokohtaiset aukiolot

Joillakin toimipisteillä voi olla normaalista poikkeavia aukioloaikoja eri osastoilla, tai kirjastot voivat toimia osan ajasta ns. omatoimikirjastoina, jolloin henkilökunta ei ole paikalla mutta kirjastoon pääsee sisälle esimerkiksi kirjastokortilla tunnistautumalla. Mikäli toimipisteen tietueelle on syötetty tällaisia aukiolotietoja, ne löytyvät päivätietueesta kentästä sections, joka on assosiatiivinen taulukko kaikista syötetyistä osastoista.

Osastotiedoissa omatoimikirjasto on erikoistapaus, jota tulisi pitää tavallisten aukioloaikojen laajennuksena. Omatoimikirjaston aukioloajat voivat syöttötavasta riippuen limittyä normaalien aukioloaikojen kanssa, jolloin omatoimikirjaston aukioloiksi tulisi ajatella ne ajanjaksot, jolloin normaalien aukiolotietojen mukaan kirjasto olisi suljettuna.

Valittavissa olevat osastot ovat kaikille kirjastoille samat. Toistaiseksi käytössä ovat seuraavat osastot:

Kirjastoautojen reitit

Kirjastohakemistossa kirjastoautojen pysäkit ovat itsenäisiä organisaatiotietueita. Niiden aukiolotiedot ovat siten haettavissa kuten kaikkien muidenkin organisaatiotietueiden. Useimmiten pysäkkien aukiolot kiinnostavat kuitenkin osana kirjastoauton kulkemaa reittiä. Tämän vuoksi kirjastoauton aukioloaikojen tietueissa on erikoistapauksena kenttä route, joka sisältää kyseisen päivän reittiin kuuluvat pysäkit kronologisessa järjestyksessä.

Tämän lisäksi tavallisista toimipisteistä tutut kentät opens ja closes ilmaisevat päivän ensimmäisen pysäkin saapumisajan ja viimeisen pysäkin lähtöajan. Jos kirjastoauto ei kierrä lainkaan, on päivätietueen closed-kentän arvo 'true' ja reittilista tyhjä.

Päiväkohtaiset reittitiedot sisältävät siis vain ne pysäkit, joiden kautta kirjastoauto kyseisenä päivänä kulkee. (Siis pysäkit, jotka ovat auki tuolloin.) Mikäli halutaan selvittää kaikki mahdolliset kirjastoauton kiertämät pysäkit, ne voidaan hakea erillisellä organisaatiokyselyllä määrittämällä parent-parametrin arvoksi kirjastoauton id.

Aukiolojaksot (period)

https://api.kirjastot.fi/v3/period?parametrit
https://api.kirjastot.fi/v3/period/<id>

Jaksotiedot ovat ikään kuin aukiolojen ryhmiä. Jokainen jakso määrää tietyn aikavälin aukiolot. Aikaväli voidaan määritellä joko suljetuksi tai loppupäästä avoimeksi (ns. oletusjakso), jolloin se on voimassa toistaiseksi. Jaksot voivat myös limittyä, jolloin korkein prioriteetti on 1) suljetulla jaksolla 2) myöhemmin alkavalla jaksolla.

Pääsääntöisesti aukiolojaksot syötetään niin, että voimassa oleva puoliavoin jakso kertoo kirjaston tavalliset aukioloajat (talviajat) ja suljetut jaksot ovat lyhyitä poikkeuksia normaaliin.

M := hyväksyy monta valintaa kerralla pilkuin erotettuna listana (foo,bar,baz) S := kenttää voi käyttää järjestämiseen sort-parametrin arvona

Yleiset palvelutiedot

https://api.kirjastot.fi/v3/service?parametrit
https://api.kirjastot.fi/v3/service/<id>

Tällä kyselyllä haettavat palvelutiedot ovat niin sanottuna yleispohjia. Palvelutietoja voidaan käyttää esimerkiksi kirjastojen hakulomakkeen palvelulistan muodostamiseksi. Nämä palvelutiedot eroavat kirjastojen tietueisiin upotetuista palveluista siten, että kirjastojen tiedoissa palveluilla on enemmän kenttiä (hinta, lainattavissa, jne.) ja lisäksi palvelun kuvaustieto (description) voi olla kirjastokohtaisesti eri.

M := hyväksyy monta valintaa kerralla pilkuin erotettuna listana (foo,bar,baz) S := kenttää voi käyttää järjestämiseen sort-parametrin arvona

Henkilökunta

https://api.kirjastot.fi/v3/person?parametrit
https://api.kirjastot.fi/v3/person/<id>

Henkilökuntatietojen kattavuus on vaihtelevaa. Pääsääntöisesti on toivottavaa, että vähintään avainhenkilöiden tiedot olisi syötetty.

M := hyväksyy monta valintaa kerralla pilkuin erotettuna listana (foo,bar,baz) S := kenttää voi käyttää järjestämiseen sort-parametrin arvona

Kirjastokimpat

https://api.kirjastot.fi/v3/consortium?parametrit
https://api.kirjastot.fi/v3/consortium/<id>

M := hyväksyy monta valintaa kerralla pilkuin erotettuna listana (foo,bar,baz) S := kenttää voi käyttää järjestämiseen sort-parametrin arvona

Kimppatietojen laajennukset (with)

Kuten organisaatioiden / kirjastojen kanssa, myös kirjastokimpat sisältävät lohkoja, joita ei oletusarvoisesti sisällytetä hakutuloksiin.

Kunnat

https://api.kirjastot.fi/v3/city?parametrit
https://api.kirjastot.fi/v3/city/<id>

M := hyväksyy monta valintaa kerralla pilkuin erotettuna listana (foo,bar,baz) S := kenttää voi käyttää järjestämiseen sort-parametrin arvona

Maakunnat

https://api.kirjastot.fi/v3/region?parametrit
https://api.kirjastot.fi/v3/region/<id>

M := hyväksyy monta valintaa kerralla pilkuin erotettuna listana (foo,bar,baz) S := kenttää voi käyttää järjestämiseen sort-parametrin arvona