Page History

Versions Compared

Key

This line was added.
This line was removed.
Formatting was changed.

...

29.1.2016 Ensimmäinen versio
5.2.2016 Lisätty tietoa osakohteiden käsittelystä
17.3.2016 Korjattu virheellinen URL kentän 'images' kuvauksessa.
22.6.2016 Lisätty esimerkkejä käytöstä
26.9.2016 Lisätty CORS-tuki
17.1.2017 Lisätty maininta Swagger UI:sta ja määrittelystä
17.1.2017 Rajapintaan lisätty subjectsExtended ja imagesExtended (ks. Swagger UI)
5.1.2018 Lisätty maksimitulosmäärä ja ohjeita suurempien tulosjoukkojen hakuun

Yleistä

Rajapinnan avulla voi kohdistaa hakuja Finna.fi:ssä mukana olevien organisaatioiden eli suomalaisten kirjastojen, arkistojen ja museoiden aineistoihin. Esimerkiksi Suomen kansallisbibliografia Fennica ja kansallisdiskografia Viola ovat mukana rajapinnan kautta tarjottavissa aineistoissa. Rajapinnan ylläpidosta ja kehittämisestä vastaa Kansalliskirjaston kirjastoverkkopalvelut. Rajapintaa koskevat tiedustelut ja palaute: finna-posti AT helsinki.fi

...

Rajapinta tukee myös CORS:ia, ja kaikki origin-osoitteet on sallittu.

Rajapintaa ei ole tarkoitettu suurten tietuejokkojen käsittelyyn (lisätietoa page-parametrin kohdalla).

Rajapinnan käyttöehdot

Tutustu rajapinnan käyttöehtoihin ja -suosituksiin.

...

Parametri

Tyyppi

Selite

Sallitut arvot

lookfor

Merkkijono

Hakusana

facet

Lista

Palautettavat fasetit

Lista Finnan hakuindeksin kentistä (sarake Core Fields), joita voi käyttää fasetoinnissa (Facet Field=Yes).

Hierarkisten fasettien (format, building, sector_str_mv, category_str_mv) tulokset palautetaan kokonaisuudessaan. Muiden fasettien osalta ensimmäiset 30.
Sisältää kentät:
- value: koodi
- translated: käännös
- count: tietueiden lukumäärä
- isApplied: 1 jos fasettia on käytetty kyselyn filter-parametrissa
- href: AND-rajaus päälle tai pois (riippuen siitä onko fasetin koodia käytetty kyselyn filter-parametrissa). Muut operaattorit, ks. filter-kentän ohje.
- children lista fasetin lapsista. Vain hierarkisille faseteille.

"facets": {
  "format": [
  {
    "value": "0\/MusicalScore\/",
    "translated": "Noter",
    "count": 96,
    "isApplied": false,
    "href": "?lookfor=notbok&amp;type=AllFields&amp;limit=2&amp;filter%5B%5D=building%3A%220%2FVaski%2F%22&amp;filter%5B%5D=format%3A%220%2FMusicalScore%2F%22"
  },

facetFilter

Lista

Lista palautettavien fasettiarvojen rajauksille

facetFilter[]=<fasetti>:"<säännöllinen lauseke>"

Mahdollistaa palautettavien fasettiarvojen rajaamisen sännöllisten lausekkeiden avulla, jotka kohdistetaan fasetin value-kenttään.
Huom: Rajattava fasetti tulee olla palautettavien fasettien joukossa.
Esimerkkejä:
- Sijainti-fasetin arvoista vain Jyväskylän yliopiston päätaso:
  - ```
  facetFilter[]=building:"0/JYU"
```
- Sijainti-fasetin arvoista vain Jyväskylän yliopistoon kuuluvat:
  - ```
  facetFilter[]=building:"\d/JYU"
```
- Aineistotyyppi-fasetin arvoista vain esnimmäiselle tasolle kuuluvat:
  - ```
  facetFilter[]=format:"^0/"
```
- Aineistotyyppi-fasetin arvoista vain e-kirjat ja CD-levyt:
  - ```
  facetFilter[]=format:"(1/Book/eBook/|1/Sound/CD)"
```

Mikäli säännöllinen lauseke kohdistuu hierakisen fasetin päätasoa alemmille tasoille, palautetaan kohdefasetin lisäksi hierarkiassa tätä edeltävät fasetit.
Esimerkiksi kun rajataan Aineistotyyppi-fasetista e-kirjat (facetFilter[]=format:"1/Book/eBook/"), tulos sisältää myös päätason fasetin Kirja (0/Book):

"facets": {
    "format": [
        {
            "value": "0\/Book\/",
            "translated": "Kirja",
            "count": 4893,
            "href": "?lookfor=sibelius&amp;type=AllFields&amp;filter%5B%5D=format%3A%220%2FBook%2F%22",
            "children": [
                {
                    "value": "1\/Book\/eBook\/",
                    "translated": "E-kirja",
                    "count": 237,
                    "href": "?lookfor=sibelius&amp;type=AllFields&amp;filter%5B%5D=format%3A%221%2FBook%2FeBook%2F%22"
                }
            ]
        }
    ]
}

filter

Lista

Rajaukset

```
<facet>="<arvo>"
```
Lista Finnan hakuindeksin fasettikentistä (sarake Core Fields), joita voi käyttää rajauksissa (Facet Field=Yes).
- Esimerkkejä:
  - format: Aineistotyyppi (kirja, kuva, esine...)
  - building: Materiaalin tarjoava organisaatio
  - online_boolean: Verkossa saatavilla oleva aineisto
  - usage_rights_str_mv: Materiaalin käyttöoikeus
  - search_daterange_mv: aikaväli
Fasettikenttien mahdolliset arvot saa selville tekemällä kyselyn ilman hakusanaa ja rajauksia. Esimerkki: listataan kaikki aineistotyypit:
- ```
https://api.finna.fi/v1/search?lookfor=&facet[]=format&prettyPrint=1&limit=0
```

Rajaukset ovat oletuksena AND-rajauksia. OR tai NOT-rajausta voi käyttää lisäämällä fasetin eteen '~' (OR) tai '-' (NOT).
Esimerkkejä:

Ei kirjoja:
- ```
filter[]=-format:"0:/Book"
```

Kirja tai CD-levy:

filter[]=~format:"0/Book/"&filter[]=~format:"1/Sound/CD/"

Info
Mikäli haluat käyttää rajauksessa muita kuin fasettikenttiä, ks. type-kentän ohje.

type

Merkkijono

Hakutyyppi

AllFields (perushaku, oletus)

Title (nimeke)
Author (tekijä)
Subject (asiasana)
year (vuosi)
JournalTitle (lehden nimeke)
CallNumber (kirjastoaineiston hyllypaikka).
publisher (julkasija)
Series (sarja)
toc (sisällysluettelo)
ISN (lehden ISN-numero)
Classification (luokitus)
- Esim:
  - ```
  Classification="ykl+35.6"
```

Info

Voit myös kohdistaa haun suoraan indeksin (ei-fasetti) kenttiin (ks. Finnan hakuindeksin kentät, sarake Core Fields, Facet Field=No) määrittelemällä kohdekentän hakulausekkeessa.
Esimerkki: kohdistetaan haku kenttään publication_place_txt_mv:

?lookfor=publication_place_txt_mv:pomarkku&field[]=id&field[]=publication_place_str_mv&field[]=placesOfPublication&field[]=publicationInfo&prettyPrint=1

Huom: laita fasettikenttiin kohdistuvat rajaukset filter-parametriin. Esimerkiksi:

?lookfor=format:0/Book/ (ei tuettu)

?lookfor=&filter[]=format:0/Book/ (tämä toimii)

sort

Merkkijono

Hakutulosten järjestys

Relevance (relevanssi, oletus)
title (nimeke)
author (tekijä)
- Jos tekijöitä on useita, lajitellaan päätekijän mukaan
last_indexed desc (viimeksi indeksoidut)
main_date_str desc (uusimmat ensin)
main_date_str asc (vanhimmat ensin)
callnumber (kirjastoaineiston hyllypaikka)
- Jos tietueessa on useita callnumbereita, lajittelu tehdään ensimmäisen perusteella.

page

Luku

Hakutulossivu

1-n (oletus 1). Huom! Rajapinta palauttaa korkeintaan 100 000 tulosta, eli jos limit=20, niin suurin mahdollinen page=5000. Jos on tarpeen käsitellä suurempaa joukkoa tietueita, on mahdollista rajata kerralla noudettava tietuejoukko esim. last_indexed-kentän perusteella.

limit

Luku

Tulosten lukumäärä

0-100 (oletus 20). limit=0 on hyödyllinen kun tarvitaan vain tulosten lukumäärä tai fasetoinnin tulokset.

lng

Merkkijono

Kieliversio

fi (suomi, oletus)
sv (ruotsi)
en-gb (englanti)
Info
Kieliversio vaikuttaa fasetteihin building ja format, sekä tietuekenttään institutions.

field

Lista

Palautettavat tietuekentät.

Ks. tuetut kentät allaolevassa taulukossa. Jos ei määritelty, palautetaan alla olevassa kenttäluettelossa korostetut kentät. Jos tyhjä, ei tietueita palauteta ollenkaan.

callback

Merkkijono

callback-funktio JSONP-tilassa

Oletuksena ei käytössä

prettyPrint

Luku

Tulostetaanko JSON rivinvaihtojen kera

0, 1 (oletus 0).

...

Content

Space Tools

Versions Compared

Old Version 54

New Version 55

Key

Yleistä

Rajapinnan käyttöehdot