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

Rajapinnan käyttöehdot

Tutustu rajapinnan käyttöehtoihin ja -suosituksiin.

Esimerkkejä käytöstä

Ajantasainen dokumentaatio

Pääasiallinen ja ajantasainen dokumentaatio löytyy Swagger UI:sta.

OpenAPI-määrittely on ladattavissa osoitteesta https://api.finna.fi/v1?swagger.

Toiminnot

HUOM! Allaoleva dokumentaatio sisältää vain osan rajapinnan toiminnallisuudesta. Kattava ajantasainen dokumentaatio löytyy Swagger UI:sta.

Rajapinnan kutsut noudattavat muotoa:

https://api.finna.fi/v1/<toiminto>?<parametrit>

Oletuksena tulokset palautetaan json-muodossa. jsonp-muotoa käytetään mikäli kutsussa on mukana callback-parametri

https://api.finna.fi/v1/<toiminto>?callback=process

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).

https://api.finna.fi/v1/search?<parametrit>

Haku Finnan indeksistä.

filter-kentän mahdollisia arvoja saa selville tekemällä kyselyn ilman hakusanaa ja rajauksia:

ParametriTyyppiSeliteSallitut arvot
lookforMerkkijonoHakusana
facetListaPalautettavat 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"
},
facetFilterListaLista 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"
                }
            ]
        }
    ]
}
filterListaRajaukset

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/"



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

typeMerkkijonoHakutyyppi
  • 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"

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)

sortMerkkijonoHakutulosten 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.
pageLukuHakutulossivu1-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.
limitLukuTulosten lukumäärä

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

lngMerkkijonoKieliversio
  • fi (suomi, oletus)
  • sv (ruotsi)
  • en-gb (englanti)

    Kieliversio vaikuttaa fasetteihin building ja format, sekä tietuekenttään institutions.

fieldListaPalautettavat 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.

callbackMerkkijonocallback-funktio JSONP-tilassaOletuksena ei käytössä
prettyPrintLukuTulostetaanko JSON rivinvaihtojen kera0, 1 (oletus 0).

Eri lähteistä tulevat samanlaiset tietueet (pääosin kirjoja) yhdistetään (deduplikoidaan) haun aikana ja hakutuloksessa näytetään ainoastaan korkeimmalle priorisoitu tietue. Käytä building-rajausta palauttaaksesi tietueita ainoastaan halutuista lähteistä.

Deduplikoidun tietueen kenttä dedupIds sisältää kaikkien samanlaisten tietueiden tunnisteet, joiden avulla voidaan tarvittaessa palauttaa halutun lähteen versio tietueesta (ks. Record-toiminto).

Hakutuloksessa esiintyvän deduplikoidun tietueen kaikkien lähteiden tietueet vaikuttavat faseteissa näkyviin arvoihin. Esimerkiksi building-fasetissa näytetään kaikkien deduplikoitujen tietueiden sijainnit. Tämän voi halutessaan estää rajaamalla palautettavien fasettien arvot facetFilter-parametrilla.

Esimerkki:


{
"resultCount": 42,
"records": [
        {
            "id": "fikka.3405646",
            "title": "Uimaveden puhdistus",
            "dedupIds": [
                "jykdok.156629",
                "fikka.3405646",
                "oy.992300443906252",
                "utu.992192965405971"
            ]
        },
        ...
]
}

Lisätietoja deduplikointi-algoritmista.

Record

https://api.finna.fi/v1/record?<parametrit>

Tietueiden nouto ID:llä

ParametriTyyppiSeliteSallitut arvot
idMerkkijono tai listaTietueen ID tai tietueiden ID:t

id tietuekenttä

  • Esimerkiksi: jykdok.922403
fieldListaPalautettavat 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.

callbackMerkkijonocallback-funktio JSONP-tilassaOletuksena ei käytössä
prettyPrintLukuTulostetaanko JSON rivinvaihtojen kera0, 1 (oletus 0).

Tuetut kentät

Seuraavia kenttiä voidaan käyttää field-parametrissa:

Tietuekenttien tiedot riippuvat metadatan laadusta. Suurta osaa kenttien sisällöistä ei ole yhtenäistetty tietueiden välillä, mistä johtuen esimerkiksi tekijöiden nimet voidaan esittää eri tavoin. Kentät voivat myös sisältää kääntämätöntä tekstiä.

Mikäli pyydetty kenttä ei sisälly vastaukseen, sitä ei ole määritelty tietueelle.

KenttäTyyppiSelite
accessRestrictions

Lista

Aineiston käyttörajoitukset, mikäli tiedossa.

Esimerkkejä:

"accessRestrictions": [
    "University of Turku local network, remote access with Univ. of Turku username",
    "Turun yliopiston verkossa, et\u00e4k\u00e4ytt\u00f6 TY:n tunnuksilla"
]

"accessRestrictions": [

    "ELEKTRA-lisenssi"
]

"accessRestrictions": [

    "K11"
]
alternativeTitlesLista

Vaihtoehtoiset nimekkeet

"alternativeTitles": [
    "Miehet mustissa",
    "MIB"
]
authorsLista

Kaikki tekijät

  • main: päätekijä
  • corporate: yhteisötekijä
  • secondary: muut tekijät
"authors": {
    "main": "Bowie, David",
    "secondary": [
        "Spiders from Mars"
    ]
}


"authors": {
    "main": "Ozric Tentacles",
    "corporate": "Ozric Tentacles,"
}
awardsLista

Palkinnot.

"awards": [
    "Tieto-Finlandia-palkinto 2013."
]
bibliographicLevelMerkkijono

Julkaisun tyyppi, esimerkiksi Monograph (monografia), MonographPart (monografian osa), Serial (sarjajulkaisu), SerialPart (sarjajulkaisun osa) ja Unknown (tuntematon).

"bibliographicLevel": "Monograph"
buildingsLista

Sijainti (hierarkkinen). Sisältää kentät:

  • value: sijainnin koodi, käytetään fasetoinnissa
  • translated: sijainnin käännös
"buildings": [
    {
        "value": "0\/TAIY\/",
        "translated": "Taideyliopisto"
    },
    {
        "value": "1\/TAIY\/tea\/",
        "translated": "Teatterikorkeakoulun kirjasto"
    },
    {
        "value": "2\/TAIY\/tea\/1\/",
        "translated": "Lainattavat"
    }
]
callNumbersLista

Kirjastoaineiston hyllypaikat. Merkintätapa vaihtelee kirjastoittain.

"callNumbers": [
    "84.5",
    "KAUHU"
]
childRecordCountLuku

Tietueen lapsitietueiden lukumäärä. Tämän tiedon pyytäminen voi kasvattaa vasteaikaa merkittävästi.

"childRecordCount": 0
classificationsLista

Luokitukset eri luokitusjärjestelmissä.

"classifications": {
"udk": [
"001.81",
"001.818",
],
"ykl": [
"16.7",
"38.3",
]
}
cleanIsbnMerkkijono

Pelkkä ISBN-tunnus ilman ulkoasua tms. Katso myös isbns

"cleanIsbn": "1402087179"
cleanIssnMerkkijono

Pelkkä ISSN-tunnus. Katso myös issns.

"cleanIssn": "0065-2164"
collectionsLista

Kokoelmat. Käytössä esimerkiksi museoaineistossa.

"collections": [
    "Riuttalan talonpoikaismuseo"
]
containerIssueMerkkijono

Sisältävän julkaisun numero

"containerIssue": "4"
containerReferenceMerkkijono

Viite sisältävään julkaisuun

"containerReference": "s. 191-201"
containerStartPageMerkkijono

Alkusivu sisältävässä julkaisussa

"containerStartPage": "191"
containerTitleMerkkijono

Sisältävän julkaisun nimeke

"containerTitle": "Finland : an introduction"
containerVolumeMerkkijono

Sisältävän julkaisun volyymi (vuosikerta / kirjasarjan osa)

"containerVolume": "25"
corporateAuthorMerkkijono

Yhteisötekijä

"corporateAuthor": "Valtiontalouden tarkastusvirasto."
dedupIdsLista

Muista lähteistä tulleiden samaa sisältöä edustavien tietueiden id:t

"dedupIds": [
    "alma.678448",
    "oula.894534",
    "tamcat.399614"
]
dissertationNoteMerkkijono

Opinnäytteen huomautus

"dissertationNote": "Pro gradu -ty\u00f6 : Tampereen yliopisto, historiatieteen laitos, yleinen historia."
editionMerkkijono

Painos, laitos tai versio

"edition": "10. osin uud. laitos"


"edition": "Pidennetty versio"
embeddedComponentPartsLista

Tietueeseen sisältyvät osakohteet. Käytössä esimerkiksi äänitteissä. Tämän tiedon pyytäminen voi kasvattaa vastauksen kokoa ja vasteaikaa merkittävästi.

"embeddedComponentParts": [
    {
        "id": "fikka.4450004",
        "title": "Juppihippipunkkari",
        "authors": [
            "Koistinen, Petteri, s\u00e4velt\u00e4j\u00e4",
            "Alanko, Ilkka, sanoittaja",
            "Nelj\u00e4 Ruusua, esitt\u00e4j\u00e4"
        ],
        "otherAuthors": [
            "Koistinen, Petteri, s\u00e4velt\u00e4j\u00e4",
            "Alanko, Ilkka, sanoittaja",
            "Nelj\u00e4 Ruusua, esitt\u00e4j\u00e4"
        ]
    },
...
eventsLista

Tietueeseen liittyvät tapahtumat, kuten valmistus, käyttö, muotoilu ja näyttely (museoaineisto)

"events": {
    "valmistus": [
        {
            "type": "valmistus",
            "date": "800 - 1050, viikinkiaika, rautakausi",
            "materials": [
                "metalli",
                "hopea"
            ]
        }
    ],
    "n\u00e4yttely": [
        {
            "type": "n\u00e4yttely",
            "name": "Raision museo -ja kulttuurikeskus Harkon arkeologinen n\u00e4yttely",
            "description": "26.5.2004 - 31.12.2006"
        }
    ]
}
formatsLista

Tietueen aineistotyypit (hierarkkinen).

  • value: aineistotyypin koodi, käytetään fasetoinnissa
  • translated: aineistotyypin käännös

Esimerkki: e-kirja on kirjan alalaji. Rajapinta palauttaa koko hierarkian ylhäältä alas:

"formats": [
    {
        "value": "0\/Book\/",
        "translated": "Kirja"
    },
    {
        "value": "1\/Book\/eBook\/",
        "translated": "E-kirja"
    }
]
fullRecordMerkkijonoTietueen alkuperäinen metadata (MARC, EAD, LIDO, DC, QDC).
generalNotesLista

Yleiset huomautukset.

"generalNotes": [
    "Ainoastaan verkkolehden vuoden viimeinen numero ilmestyy painettuna.",
    "Ei ilmestynyt lainkaan painettuna 2005."
]
genresLista

Aineiston "genret". Teoksen teema tai tyylilaji kuvaillaan kohdassa subjects.

"genres": [
    "Electronic books",
    "Conference proceedings"
]


"genres": [
    "DVD-levyt"
]


"genres": [
    "kirja-arvostelut"
]
hierarchyParentIdLista

Emotietueen ID. Käytössä esimerkiksi arkistoaineistoss (EAD).

"hierarchyParentId": [
    "narc.VAKKA-192941.KA_VAKKA-62641.KA"
]
hierarchyParentTitleLista

Emotietueen nimeke. Käytössä esimerkiksi arkistoaineistoss (EAD).

"hierarchyParentTitle": [
    "Aa Diaarit"
]


"hierarchyParentTitle": [
    "The rise and fall of Ziggy Stardust and the spiders from Mars"
]
hierarchyTopIdLista

Hierarkian päätietueen ID. Käytössä ainakin arkistoaineistossa.

"hierarchyTopId": [
    "narc.VAKKA-192941.KA"
]
hierarchyTopTitleLista

Hierarkian päätietueen nimeke. Käytössä ainakin arkistoaineistossa.

"hierarchyTopTitle": [
    "Viipurin provinssikanslian arkisto"
]
humanReadablePublicationDatesLista

Julkaisuajankohdat ihmisen luettavassa muodossa.

"humanReadablePublicationDates": [
    "1983-2006."
]
idMerkkijono

Tietueen yksilöivä tunniste Finnassa

"id": "alma.757000"
identifierString

Merkkijono

 

Tietueen tunniste, ei yksilöivä. Katso myös id.

Esimerkkejä:

Museoaineistossa inventaarionumero:

"identifierString": "201190a20"

Tietokannoissa tunniste:

"identifierString": "FSD"
imageRightsLista

Kuvien käyttöoikeudet:

  • copyright: Käyttöoikeus lyhyessä muodossa

  • link: Linkki lisenssiin

  • description: Käyttöoikeuden mahdollinen pidempi kuvaus ja/tai lisätietoja

"imageRights": {
    "copyright": "CC BY 4.0",
    "link": "http:\/\/creativecommons.org\/licenses\/by\/4.0\/deed.fi",
        "description": [
            "Finna-palvelussa julkaistuja Helsingin kaupunginmuseon kuvia voi k\u00e4ytt\u00e4\u00e4 vapaasti, my\u00f6s kaupallisessa k\u00e4yt\u00f6ss\u00e4.
             Kuvaa ei saa muunnella ilman lupaa ja kuvan yhteydess\u00e4 on mainittava kuvaaja(jos tiedossa) ja Helsingin kaupunginmuseo.
             Finnassa n\u00e4ytett\u00e4v\u00e4t kuvat lisensoidaan Nime\u00e4 4.0 Kansainv\u00e4linen (CC BY 4.0) -lisenssill\u00e4.
             Palvelussa n\u00e4ytett\u00e4v\u00e4t kuvat eiv\u00e4t ole painolaatuisia. Jos tarvitset painolaatuisen kuvan tai sinulla on muuta kysytt\u00e4v\u00e4\u00e4,
             ota yhteytt\u00e4 Helsingin kaupunginmuseon kuva-arkistoon: http:\/\/www.helsinginkaupunginmuseo.fi\/kuva-arkisto"
        ]
}
imagesLista

Tieteen kuvien osoitteet.

"images": [
    "\/Cover\/Show?id=hkm.HKMS000005%3Akm002w3s&fullres=1&index=0"
]

Kuvaa luettaessa osoitteen alkuun tulee lisätä https://api.finna.fi, esimerkiksi:

https://api.finna.fi/Cover/Show?id=hkm.HKMS000005%3Akm002w3s&fullres=1&index=0

Kirjojen tietuekuvan linkki palauttaa 10x10 pikselin kokoisen läpinäkyvän .gif-kuvan mikäli oikeaa kuvaa ei löydy.

institutionsLista

Organisaatio. Katso myös buildings

  • value: organisaation koodi
  • translated: organisaation nimi käännettynä
"institutions": [
    {
        "value": "LUC",
        "translated": "Lapin korkeakoulukirjasto"
    }
]
isbnsLista

ISBN-tunnukset. Katso myös cleanIsbn.

"isbns": [
    "951-0-31435-8 (sid.)",
    "978-951-0-31435-7 (sid.)"
]
isCollectionTotuusarvo

Onko tietue kokoelma (arkistoaineisto)

"isCollection": true
isPartOfArchiveSeriesTotuusarvo

Onko tietue osa arkistosarjaa (arkistoaineisto)

"isPartOfArchiveSeries": true
issnsLista

ISSN-tunnukset. Katso myös cleanIssn.

"issns": [
    "1913-4711"
]
languagesLista

Aineiston kielet. Katso myös originalLanguages.

"languages": [
    "fin",
    "swe"
]
lccnMerkkijono

Library of Congress Control Number

"lccn": "2010252176"
manufacturerMerkkijono

Valmistaja

"manufacturer": "([Myllykoski] : Myllykosken kirjap.)"
measurementsLista

Kuvailun kohteen fyysiset mitat

"measurements": [
    "Pituus: 42 cm",
    "Leveys: helma 22 cm; rinta 34 cm; olka+hiha 14,5+32,5 cm",
    "Lis\u00e4mitta: Koko 110"
]
nonPresenterAuthorsLista

Tekijät ilman esittäjiä. Katso myös presenters.

  • name: tekijän nimi
  • role: tekijän rooli
"nonPresenterAuthors": [
    {
        "name": "Doyle, Arthur Conan",
    },
    {
        "name": "Attwood, David",
        "role": "ohj."
    }
]
onlineUrlsLista

Online-linkit (kirjastoaineisto). Sisältää kentät:

  • url: linkin URL
  • text: linkin teksti (ei käännetty)
  • source: tietueen tietolähde (organisaatio)
    • value: organisaation koodi
    • translated: nimi käännettynä
"onlineUrls": [
    {
        "url": "http:\/\/eca.europa.eu\/portal\/page\/portal\/publications\/Journal",
        "text": "Elektroninen julkaisu (PDF)",
        "source": {
            "value": "selma",
            "translated": "Eduskunnan kirjasto - Selma"
        }
    }
]
openUrlMerkkijono

OpenURL (kirjastoaineisto).

originalLanguagesLista

Aineiston alkuperäiskielet. Katso myös languages.

"originalLanguages": [
    "jpn"
]
otherLinksLista

Muut tietueen linkit. Käytetään ainakin arvosteltujen teosten merkitsemiseen.

"otherLinks": [
    {
        "heading": "Arvosteltu teos",
        "title": "Viimeiset runonlaulajat",
        "author": "Martti Haavio"
    }
]
physicalDescriptionsLista

Aineiston fyysinen kuvaus.

"physicalDescriptions": [
    "0,01 hyllmeter",
    "1 arkivenheter"
]
physicalLocationsLista

Arkistomateriaalin fyysiset sijainnit.

"physicalLocations": [
    "Historiska och litteraturhistoriska arkivet",
    "Helsingfors, Nationalbiblioteket"
]
placesOfPublication

Lista

Julkaisupaikka

"placesOfPublication": [
    "New York, NY  :"
]
playingTimesLista

Toistoaika. Käytetään ainakin äänitteiden yksittäisissä kappaleissa ja äänikirjoissa.

"playingTimes": [
    "00:06:42"
]
presenters

Esittäjät (ks. myös nonPresenterAuthors).

  • presenters (lista)
    • name: esittäjän nimi
    • role: esittäjän rooli
  • details (lista): Lisätietoja. Esittäjät saattavat merkintätavasta riippuen olla myös olla tässä kentässä.
"presenters": {
    "presenters": [
        {
            "name": "Carola",
            "role": "esitt."
        },
        {
            "name": "Sarmanto, Heikki",
            "role": "esitt."
        },
        {
            "name": "Heikki Sarmanto Trio",
            "role": "esitt."
        }
    ],
    "details": [
        "Carola (voc), Heikki Sarmanto Trio: Heikki Sarmanto (p), Tapani Tamminen (b), Reino Laine (dr), Esa Pethman (fl, ts)"
    ]
}
productionCreditsLista

Tuotannon tekijätiedot. Käytetään ainakin joissakin äänitteissä.

"productionCredits": [
    "Miikka Huttunen (\u00e4\u00e4nitt\u00e4j\u00e4, miksaaja), Jukkis Uotila (tuottaja), Klaus Suonsaari (tuottaja), Svante Forsb\u00e4ck (masteroija)."
]
projectedPublicationDateMerkkijono

Arvioitu julkaisuajankohta

"projectedPublicationDate": "12\/2015"
publicationDatesLista

Julkaisuajankohta

"publicationDates": [
    "1972"
]
publicationEndDateMerkkijono

Viimeinen julkaisuajankohta (kausijulkaisuissa) tai ensi-illan ajankohta (elokuvissa).

"publicationEndDate": "2003"

Edelleen jatkuva julkaisu merkitään usein vuotena 9999:

"publicationEndDate": "9999"
publicationFrequencyLista

Julkaisutiheys. Ilmoitettu yleensä sanallisesti suomeksi.

"publicationFrequency": [
    "Kerran kuukaudessa."
]
publicationInfoLista

Tietoa julkaisusta. Saattaa sisltää julkaisupaikan.

"publicationInfo": [
    "Dortmund"
]
publishers

Lista


Julkaisijat

"publishers": [
    "Published by E. & F.N. Spon for the Royal Institute of British Architects"
]
previousTitles / newerTitles
Tieto voi sisältyä myös kenttään recordLinks
ratingLista

Käyttäjien julkaisulle antamien arvostelujen keskiarvo ja lukumäärä. Käytössä seuraavissa aineistotyypeissä: 0/Book/, 0/Journal/, 0/Sound/ ja 0/Video/.

  • average: keskiarvo, 0-5.

  • count: arvostelujen lukumäärä

"rating": {
    "average": 2.5,
    "count": 3
}
rawDataLista

Tietueen kaikkien indeksikenttien sisältö, pois lukien fullRecord.

recordLinksLista

Tietueiden väliset linkit. Linkki voidaan muodostaa ainakin nimekkeen tai isn:n perusteella.

  • value
  • link
    • type: linkin muodostamisperuste, kuten title tai isn
    • value: tieto linkin muodostamiseksi
    • exclude
  • translated: käännetty kuvaus tietueen suhteesta linkitettyyn tietueeseen


"recordLinks": [
    {
        "value": "Baskervillen koira",
        "link": {
            "type": "isn",
            "value": "978-951-1-22851-6",
            "exclude": "arto.1567282"
        },
        "translated": "Muu suhde"
    }
]


"recordLinks": [
    {
        "value": "Julkisuuden salaisuudet : pakinoita ja satiireja journalismin ja julkisuuden kiehtovasta maailmasta",
        "link": {
            "type": "title",
            "value": "Julkisuuden salaisuudet : pakinoita ja satiireja journalismin ja julkisuuden kiehtovasta maailmasta"
        },
        "translated": "Muu suhde"
    }
]
recordPageMerkkijonoRelatiivinen linkki tietueen sivulle Finnassa. Lisää linkin alkuun https://www.finna.fi
sectorsLista

Sektori (kirjasto, museo tai arkisto).

  • value: sektorin koodi
  • translated: sektorin nimi käännettynä
"sectors": [
    {
        "value": "0/mus/",
        "translated": "Museo"
    }
]
seriesLista

Sarjatiedot

  • name: sarjan nimi
  • additional (valinnainen)
  • number: järjestysluku (valinnainen)
  • issn: issn-numero (valinnainen)


"series": [
    {
        "name": "Ursan julkaisuja",
        "additional": "0357-7937;",
        "number": "28",
        "issn": "0357-7937"
    }
]


"series": [
    {
        "name": "Laatukirjasto"
    }
]
sfxObjectIdMerkkijono

SFX-tietueen tunniste

"sfxObjectId": "1000000000310928"
shortTitleMerkkijono

Päänimeke. Katso myös title ja subTitle.

"shortTitle": "Parhaat ruokasienet"
source

Lista

Tietueen lähde

  • value: organisaation koodi
  • translated: organisaation käännetty nimi
"source": [
    {
        "value": "keski",
        "translated": "Keski-kirjastot"
    }
]
subjectsLista

Asiasanat/aiheet. Lista koostuu listoista, joissa on ensimmäisenä yläkäsite ja sen jälkeen mahdolliset alakäsitteet. Esim:

"subjects": [
    [
        "Holmes, Sherlock,",
        "fikt."
    ],
    [
        "elokuvat",
        "Iso-Britannia",
        "2000-2009"
    ],
    [
        "j\u00e4nnityselokuvat"
    ],
    [
        "rikoselokuvat"
    ]
]
subTitleMerkkijono

Alanimeke. Katso myös title ja shortTitle.

"subTitle": "sieniopas"
summaryLista

Yhteenveto/tiivistelmä.

"summary": [
    "Provides essential ideas of the new science of nanotechnology and mathematics. Covers contemporary topics in the areas of the environment, food safety, medicine and healthcare, consumer goods, agriculture, homeland security, and energy supply."
]
systemDetailsLista

Aineiston käyttöön tarvittava järjestelmä.

"systemDetails": [
    "Internet-yhteys; www-selain."
]
titleMerkkijono

Koko nimeke. Katso myös shortTitle ja subTitle

"title": "Parhaat ruokasienet : sieniopas"
titleSectionMerkkijono

Nimekkeeseen liittyvä osan numero, jos nimeke kuuluu sarjaan. Katso myös series.

"titleSection": "3."
titleStatementMerkkijono

Nimekkeeseen liittyvää lisätietoa. Sisältää usein tietoja tekijöistä.

"titleStatement": "directed by Ridley Scott ; screenplay by Hampton Fancher and  David Peoples"
tocLista

Sisällysluettelo. Sisältää usein sisällysluettelon lisäksi tai sijasta muutakin kuvailutietoa ja jopa tiivistelmiä.

"toc": [
    "1 CD-\u00e4\u00e4nilevy + esiteliite",
    "Kappale Midnight in a perfect world sis. selke\u00e4n s\u00e4mplen Pekka Pohjolan kappaleesta Sekoilu seestyy",
    "Best foot forward. Building steam with a grain of salt. The number song. Changeling. What does your soul look like (part 4). Stem\/Long stem. Mutual slump. Organ donor. Why hip hop sucks in '96. Midnight in a perfect world. Napalm brain\/Scatter brain. What does your soul look like (part 1 - Blue sky revisit)",
    "DJ Shadow",
    "englanti"
]
uniformTitlesLista

Yhtenäistetyt nimekkeet (kirjastoaineisto).

"uniformTitles": [
    "On the origin of species"
]
unitIdMerkkijono

Arkistoyksikön tunniste. Katso myös id.

"unitId": "Aa:6"
urlsLista

Tietueeseen liittyvät resurssit ja toiminnot ulkoisissa järjestelmissä. Sisältää kentät:

  • url: linkin URL
  • desc: kuvaus käännettynä (jos on)
"urls": [
    {
        "url": "http:\/\/www.makupalat.fi\/",
        "desc": "Tietokannan k\u00e4ytt\u00f6liittym\u00e4"
    },
    {
        "url": "http:\/\/www.makupalat.fi\/fi-FI\/Info\/",
        "desc": "Tietokantaopas"
    }
]
yearMerkkijono

Vuosi (esimerkiksi julkaisuvuosi, valmistusvuosi). Käytetään myös main_date_str-fasetissa.

"year": "1761"

Esimerkkikyselyjä



Tietueet hakusanalla "sibelius":
https://api.finna.fi/v1/search?lookfor=sibelius
CD-levyt hakusanalla "sibelius":
https://api.finna.fi/v1/search?lookfor=sibelius&filter[]=format:"1/Sound/CD/"
Verkossa saatavilla olevat kuvat hakusanalla "sibelius"
https://api.finna.fi/v1/search?lookfor=sibelius&filter[]=online_boolean:"1"&filter[]=format:"0/Image/"
Verkossa saatavilla olevat kuvat hakusanalla "sibelius", hakutulokset ja fasetointi organisaation mukaan
https://api.finna.fi/v1/search?lookfor=sibelius&filter[]=online_boolean:"1"&filter[]=format:"0/Image/"&facet[]=building
Tietueet vuosilta 1870-1890
https://api.finna.fi/v1/search?lookfor=&filter[]=search_daterange_mv:"[1870%20TO%201890]"
Kaikkien tietueiden aineistotyypit
https://api.finna.fi/v1/search?lookfor=&facet[]=format
Kaikki verkossa saatavilla olevat kuvat
https://api.finna.fi/v1/search?lookfor=&filter[]=online_boolean:"1"&filter[]=format:"0/Image/"
Tietueet sallitun käyttötavan mukaan (esimerkiksi "Saa muokata, myös kaupallinen")
https://api.finna.fi/v1/search?lookfor=&filter[]=usage_rights_str_mv:usage_B
Mukana olevat organisaatiot, nimet ruotsiksi
https://api.finna.fi/v1/search?lookfor=&limit=0&facet[]=building&lng=sv
Tietueet, joissa tekijänä "sibelius"
https://api.finna.fi/v1/search?lookfor=sibelius&type=Author
Yksittäisen tietueen noutaminen ID:n perusteella
https://api.finna.fi/v1/record?id=fikka.123
Kahden tietueen noutaminen ID:n perusteella
https://api.finna.fi/v1/record?id[]=fikka.123&id[]=fikka.124

Hakusana voi sisältää monimutkaisemman hakulausekkeen, esimerkiksi kohdistuksen tiettyyn indeksikenttään tai loogisen hakuoperaattorin:



Haku hakusanoilla "sibelius" ja "festival"
https://api.finna.fi/v1/search?lookfor=sibelius+AND+festival

Osakohteiden käsittely

Joissakin Finnasta löytyvistä MARC-tietueista on emokohteeseen yhdistettyjä osakohteita. Tällaisia ovat esim. lehtien artikkelit ja kappaleet musiikki-CD:llä. Finnan käyttöliittymässä tällaiset osakohteet näytetään emokohteen tietuenäytön Sisältö/kappaleet-välilehdellä, ja listassa näytettävä metadata näkyy emokohteen MARC tietueen 979-kentissä. Rajapinnassa 979-kentät on typistetty yhdeksi kentäksi, joka sisältää vain osakohteiden ID:t toistetussa a-osakentässä. Osakohteiden tiedot voidaan tarvittaessa hakea rajapinnan record-toiminnolla käyttäen 979-kentän a-osakentistä löytyviä ID:itä.

Esimerkkitietue, joka sisältää osakohteita: https://api.finna.fi/v1/record?id=fikka.4450004&field[]=fullRecord

Lisätietoja

Lisätietoja hakusyntaksista.

Rajapinta tukee myös Finnan tarkennetun haun syntaksia samoin parametrein kuin tarkennetun haun hakutuloksessa, esimerkiksi:

https://api.finna.fi/v1/search?sort=relevance&bool0%5B%5D=AND&lookfor0%5B%5D=sibelius&type0%5B%5D=AllFields&lookfor0%5B%5D=festival&type0%5B%5D=AllFields&lookfor0%5B%5D=&type0%5B%5D=AllFields&join=AND&filter%5B%5D=~language%3A"fin"&limit=20

Dokumentaation muutoshistoria

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


  • No labels

16 Comments

  1. Anonymous

    Hei,

     

    Olisi todella tervetullutta jos kuvia voisi API:n kautta saada muussakin kuva koossa kuin fullres. Menee hirveästi aikaa latailla netin yli isoja kuvia.

     

  2. Unknown User ([email protected])

    Minusta olisi järkevää, että myös year-kenttä tulisi oletuksena mukana.

  3. Anonymous

    Miten saa haettua KAIKKI kuvat tietyltä vuodelta? 
    Nyt näyttäisi olevan niin, että json-tiedosto on aina saman pituinen, oli haku mikä tahansa. Mistä tämä johtuu? 

    1. Unknown User ([email protected])

      Ilman page-parametria haku antaa vain ensimmäisen hakutulossivun. Page-parametria (ks. ohjeet yllä) käyttämällä saa tuloksia enemmän.

      1. Anonymous

        En ymmärtänyt tota page-ohjetta.
        Mihin kohtaan tähän alla olevaan hakuun pitää laittaa tuo page?
        https://api.finna.fi/v1/search?lookfor=&filter[]=online_boolean:%221%22&filter[]=format:%220/Image/%22

        1. Unknown User ([email protected])

          1. Anonymous

            Okei, kiitoksia paljon! (smile)

  4. Anonymous

    Olisiko asiasanoihin (subjects) mahdollista liittää tieto, mistä sanastosta/ontologiasta ne ovat peräisin?

    1. Onnistuu, tosin joudutaan tekemään uusi kenttä, ettei rikota yhteensopivuutta.

       

      1. Tästä on nyt kehitysehdotus ALLI-4905 - Getting issue details... STATUS .

    2. Rajapinnasta voi nyt pyytää subjectsExtended-kentän, joka sisältää lähteen lisäksi myös asiasanan tyypin.

  5. Anonymous

    Olisiko mahdollista saada fullrecordiin palauttamiin kenttiin mukaan myös tuo kenttä 520 a?   Kokeilin parilla kirjalla joissa ko. kentässä on tietoa, mutta marc-tietueseen sitä ei tule. Pystyykö 500 tai 520 kentät pyytämään kenttinä jsonin jatkoksi, kokeilin &field[]=title&field[]=spelling -lisäämällä, mutta tietoa ei saa ulos. Liekö sama syy? Kiitos!

  6. 520-kenttää ei valitettavasti voida tällä hetkellä näyttää rajapinnassa, koska se saattaa sisältää tekijänoikeuksien alaista sisältöä.

    500-kentän pitäisi tulla MARC-tietueeseen ihan normaalisti, mutta erillisenä JSON-kenttänä sitä ei tällä hetkellä ole.

  7. Anonymous

    Hei, pystyykö rajapinnasta pyytämään Finna Streetissä käytössä olevan sijaintitiedon?

    1. Finna Streetissä käyttäjän sijainti pyydetään suoraan käyttäjän selaimelta (JS: navigator.geolocation.getCurrentPosition()). Sijainnin perusteella tehdään haku 100 metrin säteellä sopivilla rajauksilla, ja vastaavat hakuparametrit toimivat myös rajapinnassa. Rajapinnasta voi pyytää sijainnit geoLocations-kentällä, ks. esimerkkihaku.

      geoLocations sisältää paikkatiedot WKT-muodossa.

      1. Anonymous

        Kiitos, toimii hyvin!