Kirjastohakemiston rajapinta v3

Päiväys Rajapinnan versio Muutoksen kuvaus
10.12.2015 3.0.0 Rajapinta julkaistu
16.02.2016 3.0.1 Korjattu kuvalinkit palvelu- ja henkilötietoihin
17.03.2016 3.0.2 Uusi toimipistetyyppi school / koulukirjasto
25.04.2016 3.1.0 Lisätty aukiolojaksot (period) rajapintaan.
14.06.2016 3.1.1 Kimppatietoihin (consortium) Finna-laajennukset.
28.06.2016 3.1.2 Datatyypin määritys "tiedostopäätteillä" (.xml .json .jsonp)
17.08.2016 3.2.0 Organisaatioista tutut linkit kirjastokimppoihin; linkkiryhmät (link_groups)

Vanhat dokumentaatiot: API V2, API V1

HUOM 2016-08-17: Verkkosivulinkkejä voi nyt jakaa ryhmiin. Lisäksi linkit on tuotu consortium-tietotyyppiin. Linkkiryhmät sisällytetään hakutuloksin parametrilla ?with=link_groups. Muutoksen johdosta organisaatiohaun parametri ?with=links on deprekoitu.

HUOM 2016-03-17: Lisätty uusi toimipistetyyppi school / koulukirjasto.

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.

Tietotyyppi Mime-tyyppi Format-parametri
XML application/xml xml
JSON application/json json
JSONP application/javascript jsonp

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.

Tyyppi Kuvaus
organisation Organisaatio eli kirjasto, kirjastoauto, osasto, jne.
library Muuten sama kuin 'organisaatio', mutta sisältää vain kirjastojen toimipisteet ja kirjastoautot
city Kunta (Helsinki, Kuopio, Rovaniemi, ...)
consortium Kirjastokimppa (HelMet, Keski-kirjastot, Vaski-kirjastot, ...)
opening_time Kirjastojen aukioloajat
person Organisaation henkilökunta
provincial_library Maakuntakirjasto-alue
region Maakunta-alue (Uusimaa, Pohjois-Savo, Lappi, ...)
service Palvelu (esimerkiksi asiakaskäytössä oleva laite, lisäpalvelu tai tila)

Sisältöjen kielet ja kielikoodit

Kieli Koodi
Suomi fi
Englanti en
Ruotsi sv
Saame se
Venäjä ru

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.

Parametri Sallitut arvot Kuvaus
lang en, fi, ru, se, sv Palautettavan tietueen kieliversio [oletusarvo: kaikki kielet]
format xml, json, jsonp Vastauksen tietotyyppi [oletusarvo: json]
callback merkkijono Jsonp-formaattia käytettäessä callback-funktion nimi
limit numero Rajoittaa tulosten määrää per sivu [oletusarvo: 50]
skip numero Sivutettujen tulosten aloittaminen n:nnen tietueen kohdalta.
sort lista Tulosjoukon järjestämiseen käytetyt kentät

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.

Kuvakoko Resoluutio (max)
small 200 x 200 px
medium 1000 x 1000 px
large 1980 x 1980 px
huge 3840 x 3840 px

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

Parametri M S Kuvaus
with X Sisällyttää tietueisiin valinnaisia tietolohkoja (ks. listaus alempana)
refs X Valittujen alitietueiden palauttaminen osana tulosta
branch_type X X Kirjaston toimipiste -tyyppisten (branchlibrary) tietueiden alakategoria (ks. listaus alempana)
created.after Hakee tietueet, jotka on luotu myöhemmin kuin määrättynä pvm:nä
created.before Tietueiden viimeinen luonti-pvm
city X X Kunnan id-tunniste
city.name X X Kunnan täsmällinen nimi. Haettaessa ruotsin kielellä käytetään ruotsalaista nimeä
city.slug X X Kunnan nimestä johdettu tunniste
consortium X X Kirjastokimpan id-tunniste
distance X Määrittää koordinaattihaussa sallitun etäisyyden määrätystä pisteestä; arvo kilometreinä (1 = 1 km, 100 = 100 km)
geo Koordinaattiparilla hakeminen (käytetään yhdessä distance-parametrin kanssa) (24.3434,71.1235)
id X X Parametria voidaan käyttää, kun halutaan hakea monen tunnetun tietueen tiedot yhdellä kertaa
identificator X Kirjaston virallinen tunniste (kenttä extra.identificator)
modified.after X Hakee tietueet, joita muokattu myöhemmin kuin määrättynä pvm:nä
modified.before Tietueiden viimeinen muokkaus-pvm
name X Hakee kirjastot, joiden nimi alkaa määrätyllä merkkijonolla. Riippuu valitusta kielestä.
region X X Maakunta-alueen id-tunniste
region.name X X Maakunta-alueen täsmällinen nimi. Riippuu valitusta kielestä.
region.slug X X Maakunta-alueen nimestä johdettu tunniste
period.start Kun sisällytetään aukiolotiedot, voidaan määrittää haettava väli
period.end Kun sisällytetään aukiolotiedot, voidaan määrittää haettava väli
service X Organisaatioon liitetyn palvelun id-tunniste
service.name Hakee organisaatiot, joihin on liitetty palvelu, jonka (ei-täsmällinen) nimi alkaa määrätyllä merkkijonolla
service.slug X Palvelutietueen nimestä johdettu tunniste
short_name X Tietueen nimen mahdollinen lyhyempi muoto. Riippuu valitusta kielestä.
type X X Tietuiden päätason tyyppi (ks. listaus alempana)

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

Organisaatiotyypit (type)

Tunniste Tunniste (api-v2) Kuvaus
library branchlibrary Kirjaston toimipiste ("kirjasto")
centralized_service unit Keskitetty palvelu
department department Osasto
facility library Kirjastolaitos
mobile_stop mobile_stop Kirjastoauton pysäkki
other organisation Muu organisaatio

Toimipisteiden alatyypit (branch_type)

Tunniste Tunniste (api-v2) Kuvaus
children childrens_library Lasten kirjasto
home_service home_service Kotipalvelu
institutional institution_library Laitoskirjasto
library default Kirjasto (yleinen kirjaston toimipiste)
main_library main_library Pääkirjasto
mobile mobile Kirjastoauto
music music_library Musiikkikirjasto
other other Muu kirjastoalan organisaatio
polytechnic polytechnic_library Ammattikorkeakoulukirjasto
regional regional Aluekirjasto
school - Koulukirjasto
special special_library Erikoiskirjasto
university university_library Yliopistokirjasto
vocational_college vocational_college_library Ammattioppilaitoskirjasto

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.

Tunniste Kuvaus
accessibility Esteettömyystiedot
extra Sekalaisia tietoja, jotka on siirrettävän datan määrän optimoimiseksi siirretty miljoonalaatikkoon
links Linkkejä ulkoisiin palveluihin kuten some-palveluihin (deprecated)
link_groups Sama kuin yllä mutta linkit on jaoteltu ryhmiin.
mail_address Mahdollinen toimipisteen sijainnista poikkeava postiosoite
persons Lista organisaation tietueeseen liitetyistä työntekijöistä
phone_numbers Lista puhelinnumeroista
pictures Lista valokuvista
services Lista palveluista
schedules Aukiolotiedot määrätylle ajanjaksolle. Aikaväli määritetään lisäparametrein period.start ja period.end

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.

Tunniste Kuvaus
city Kunnat, joihin tulosjoukon organisaatiotietueet viittaavat.
region Maakunnat (kuten yllä)
provincial_library Maakuntakirjastoalueet (kuten yllä)
consortium Kirjastokimpat (kuten yllä)
period Käytetään parametrin ?with=schedules kanssa; hakee aukioloihin liittyvät jaksotiedot.

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

Parametri M S Kuvaus
organisation X X Organisaation tietueen id-tunniste
period.start Aikavälin ensimmäinen päivä
period.end Aikavälin viimeinen päivä

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.

Tunniste Kuvaus
period Aukiolojaksojen tiedot

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.

Yksikkö Koodi
kuluva päivä today
päivä d
viikko w
kuukausi m

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.

Yksikkö Parametri Esim. Tarkka arvo
week period.start -2w kyseisen viikon maanantai
week period.end 4w kyseisen viikon sunnuntai
month period.start 2m kuukauden ensimmäinen päivä
month period.end 3m kuukauden viimeinen päivä

Esimerkkejä

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

Alaraja Yläraja Aikaväli
0d 0d 2015-11-06 – 2015-11-06
0w 0w 2015-11-02 – 2015-11-08
0m 0m 2015-11-01 – 2015-11-30
0m 2m 2015-11-01 – 2016-01-31 (täysiä kuukausia)
0d 2m 2015-11-06 – 2016-01-31 (kuluva päivä – kuun loppu)
0w 2m 2015-11-02 – 2016-01-31 (maanantai – kuun loppu)
0m 2w 2015-11-01 – 2015-11-22 (kuun alku – sunnuntai)
-2d 3d 2015-11-04 – 2015-11-09 (ke-ma)
-2w 2w 2015-10-19 – 2015-11-22 (täysiä viikkoja ma-su)
-1m 1m 2015-10-01 – 2016-12-31 (täysiä kuukausia)

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:

Tunniste Kuvaus
magazines Lehtisali
selfservice Omatoimikirjasto

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

Parametri M S Kuvaus
id X X Parametria voidaan käyttää, kun halutaan hakea monen tunnetun tietueen tiedot yhdellä kertaa
name X Hakee tietueet, joiden nimi alkaa määrätyllä merkkijonolla. Arvo riippuu kielestä.
organisation X X Organisaatio, jonka aukiolot tietue määrittää
valid_from X X Tarkka jakson alkamispäivä
valid_until X X Tarkka jakson päättymispäivä

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

Parametri M S Kuvaus
id X X Parametria voidaan käyttää, kun halutaan hakea monen tunnetun tietueen tiedot yhdellä kertaa
created.after Hakee tietueet, jotka on luotu myöhemmin kuin määrättynä pvm:nä
created.before Viimeinen luonti-pvm
modified.after Hakee tietueet, joita muokattu myöhemmin kuin määrättynä pvm:nä
modified.before Viimeinen muokkaus-pvm
name X Hakee tietueet, joiden nimi alkaa määrätyllä merkkijonolla. Arvo riippuu kielestä.
type X X Palvelun tyypin tunnisteella suotiminen

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

Parametri M S Kuvaus
id X X Voi käyttää tunnettujen henkilötietueiden hakemiseen yhdellä kyselyllä
first_name X Etunimihaku
last_name X Sukunimihaku
name Koko nimellä hakeminen
organisation X X Sen organisaation id, johon henkilöt liitetty

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

Parametri M S Kuvaus
id X X Voi käyttää tunnettujen kuntien tietueiden hakemiseen yhdellä kyselyllä
slug X X Kirjastokimpan url-tunniste
name X Hakee kimpat, joiden nimi alkaa määrätyllä merkkijonolla (kieliriippuvainen)
special Boolean. False-arvo suotii pois ei-kirjastoalan kimpat, True-arvo toisin päin.
finna:id X Finna-palvelussa käytetty tunniste

Kimppatietojen laajennukset (with)

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

Tunniste Kuvaus
finna Finna-laajennukset
link_groups Vapaasti määriteltäviä linkkejä ulkoisiin verkkosivustoihin.

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

Parametri M S Kuvaus
id X X Voi käyttää tunnettujen kuntien tietueiden hakemiseen yhdellä kyselyllä
name X Hakee kunnat, joiden nimi alkaa määrätyllä merkkijonolla (kieliriippuvainen)
consortium X X Kirjastokimpan id-tunniste
region X X Maakunnan id-tunniste
provincial_library X X Maakuntakirjastoalueen id-tunniste

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

Parametri M S Kuvaus
id X X Voi käyttää tunnettujen kuntien tietueiden hakemiseen yhdellä kyselyllä
name X Hakee maakunnat, joiden nimi alkaa määrätyllä merkkijonolla (kieliriippuvainen)