See also:
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
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).
Search
https://api.finna.fi/v1/search?<parametrit>
Haku Finnan indeksistä.
filter-kentän mahdollisia arvoja saa selville tekemällä kyselyn ilman hakusanaa ja rajauksia:
- aineistotyypit:
https://api.finna.fi/v1/search?lookfor=&facet[]=format&prettyPrint=1&limit=0
- kielikoodit:
https://api.finna.fi/v1/search?lookfor=&facet[]=language&prettyPrint=1&limit=0
(käytössä hieman laajennettu ISO 639-3, ks. myös mappaustaulukko)
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).
"facets": { |
facetFilter | Lista | Lista palautettavien fasettiarvojen rajauksille |
"facets": { "format": [ { "value": "0\/Book\/", "translated": "Kirja", "count": 4893, "href": "?lookfor=sibelius&type=AllFields&filter%5B%5D=format%3A%220%2FBook%2F%22", "children": [ { "value": "1\/Book\/eBook\/", "translated": "E-kirja", "count": 237, "href": "?lookfor=sibelius&type=AllFields&filter%5B%5D=format%3A%221%2FBook%2FeBook%2F%22" } ] } ] } |
filter | Lista | Rajaukset |
Rajaukset ovat oletuksena AND-rajauksia. OR tai NOT-rajausta voi käyttää lisäämällä fasetin eteen '~' (OR) tai '-' (NOT).
Mikäli haluat käyttää rajauksessa muita kuin fasettikenttiä, ks. type-kentän ohje. |
type | Merkkijono | Hakutyyppi |
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. ?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 |
|
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 |
|
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). |
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" ] },
...
]
}
Record
https://api.finna.fi/v1/record?<parametrit>
Tietueiden nouto ID:llä
Parametri | Tyyppi | Selite | Sallitut arvot |
---|---|---|---|
id | Merkkijono tai lista | Tietueen ID tai tietueiden ID:t | id tietuekenttä
|
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). |
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ä | Tyyppi | Selite |
---|---|---|
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" ] |
alternativeTitles | Lista | Vaihtoehtoiset nimekkeet "alternativeTitles": [ "Miehet mustissa", "MIB" ] |
authors | Lista | Kaikki tekijät
"authors": { "main": "Bowie, David", "secondary": [ "Spiders from Mars" ] } "authors": { "main": "Ozric Tentacles", "corporate": "Ozric Tentacles," } |
awards | Lista | Palkinnot. "awards": [ "Tieto-Finlandia-palkinto 2013." ] |
bibliographicLevel | Merkkijono | Julkaisun tyyppi, esimerkiksi Monograph (monografia), MonographPart (monografian osa), Serial (sarjajulkaisu), SerialPart (sarjajulkaisun osa) ja Unknown (tuntematon). "bibliographicLevel": "Monograph" |
buildings | Lista | Sijainti (hierarkkinen). Sisältää kentät:
"buildings": [ { "value": "0\/TAIY\/", "translated": "Taideyliopisto" }, { "value": "1\/TAIY\/tea\/", "translated": "Teatterikorkeakoulun kirjasto" }, { "value": "2\/TAIY\/tea\/1\/", "translated": "Lainattavat" } ] |
callNumbers | Lista | Kirjastoaineiston hyllypaikat. Merkintätapa vaihtelee kirjastoittain. "callNumbers": [ "84.5", "KAUHU" ] |
childRecordCount | Luku | Tietueen lapsitietueiden lukumäärä. Tämän tiedon pyytäminen voi kasvattaa vasteaikaa merkittävästi. "childRecordCount": 0 |
classifications | Lista | Luokitukset eri luokitusjärjestelmissä. "classifications": { } |
cleanIsbn | Merkkijono | Pelkkä ISBN-tunnus ilman ulkoasua tms. Katso myös isbns "cleanIsbn": "1402087179" |
cleanIssn | Merkkijono | Pelkkä ISSN-tunnus. Katso myös issns. "cleanIssn": "0065-2164" |
collections | Lista | Kokoelmat. Käytössä esimerkiksi museoaineistossa. "collections": [ "Riuttalan talonpoikaismuseo" ] |
containerIssue | Merkkijono | Sisältävän julkaisun numero "containerIssue": "4" |
containerReference | Merkkijono | Viite sisältävään julkaisuun "containerReference": "s. 191-201" |
containerStartPage | Merkkijono | Alkusivu sisältävässä julkaisussa "containerStartPage": "191" |
containerTitle | Merkkijono | Sisältävän julkaisun nimeke "containerTitle": "Finland : an introduction" |
containerVolume | Merkkijono | Sisältävän julkaisun volyymi (vuosikerta / kirjasarjan osa) "containerVolume": "25" |
corporateAuthor | Merkkijono | Yhteisötekijä "corporateAuthor": "Valtiontalouden tarkastusvirasto." |
dedupIds | Lista | Muista lähteistä tulleiden samaa sisältöä edustavien tietueiden id:t "dedupIds": [ "alma.678448", "oula.894534", "tamcat.399614" ] |
dissertationNote | Merkkijono | Opinnäytteen huomautus "dissertationNote": "Pro gradu -ty\u00f6 : Tampereen yliopisto, historiatieteen laitos, yleinen historia." |
edition | Merkkijono | Painos, laitos tai versio "edition": "10. osin uud. laitos" "edition": "Pidennetty versio" |
embeddedComponentParts | Lista | 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" ] }, ... |
events | Lista | 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" } ] } |
formats | Lista | Tietueen aineistotyypit (hierarkkinen).
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" } ] |
fullRecord | Merkkijono | Tietueen alkuperäinen metadata (MARC, EAD, LIDO, DC, QDC). |
generalNotes | Lista | Yleiset huomautukset. "generalNotes": [ "Ainoastaan verkkolehden vuoden viimeinen numero ilmestyy painettuna.", "Ei ilmestynyt lainkaan painettuna 2005." ] |
genres | Lista | Aineiston "genret". Teoksen teema tai tyylilaji kuvaillaan kohdassa subjects. "genres": [ "Electronic books", "Conference proceedings" ] "genres": [ "DVD-levyt" ] "genres": [ "kirja-arvostelut" ] |
hierarchyParentId | Lista | Emotietueen ID. Käytössä esimerkiksi arkistoaineistoss (EAD). "hierarchyParentId": [ "narc.VAKKA-192941.KA_VAKKA-62641.KA" ] |
hierarchyParentTitle | Lista | Emotietueen nimeke. Käytössä esimerkiksi arkistoaineistoss (EAD). "hierarchyParentTitle": [ "Aa Diaarit" ] "hierarchyParentTitle": [ "The rise and fall of Ziggy Stardust and the spiders from Mars" ] |
hierarchyTopId | Lista | Hierarkian päätietueen ID. Käytössä ainakin arkistoaineistossa. "hierarchyTopId": [ "narc.VAKKA-192941.KA" ] |
hierarchyTopTitle | Lista | Hierarkian päätietueen nimeke. Käytössä ainakin arkistoaineistossa. "hierarchyTopTitle": [ "Viipurin provinssikanslian arkisto" ] |
humanReadablePublicationDates | Lista | Julkaisuajankohdat ihmisen luettavassa muodossa. "humanReadablePublicationDates": [ "1983-2006." ] |
id | Merkkijono | 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" |
imageRights | Lista | Kuvien käyttöoikeudet:
"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" ] } |
images | Lista | 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. |
institutions | Lista | Organisaatio. Katso myös buildings
"institutions": [ { "value": "LUC", "translated": "Lapin korkeakoulukirjasto" } ] |
isbns | Lista | ISBN-tunnukset. Katso myös cleanIsbn. "isbns": [ "951-0-31435-8 (sid.)", "978-951-0-31435-7 (sid.)" ] |
isCollection | Totuusarvo | Onko tietue kokoelma (arkistoaineisto) "isCollection": true |
isPartOfArchiveSeries | Totuusarvo | Onko tietue osa arkistosarjaa (arkistoaineisto) "isPartOfArchiveSeries": true |
issns | Lista | ISSN-tunnukset. Katso myös cleanIssn. "issns": [ "1913-4711" ] |
languages | Lista | Aineiston kielet. Katso myös originalLanguages. "languages": [ "fin", "swe" ] |
lccn | Merkkijono | Library of Congress Control Number "lccn": "2010252176" |
manufacturer | Merkkijono | Valmistaja "manufacturer": "([Myllykoski] : Myllykosken kirjap.)" |
measurements | Lista | 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" ] |
nonPresenterAuthors | Lista | Tekijät ilman esittäjiä. Katso myös presenters.
"nonPresenterAuthors": [ { "name": "Doyle, Arthur Conan", }, { "name": "Attwood, David", "role": "ohj." } ] |
onlineUrls | Lista | Online-linkit (kirjastoaineisto). Sisältää kentät:
"onlineUrls": [ { "url": "http:\/\/eca.europa.eu\/portal\/page\/portal\/publications\/Journal", "text": "Elektroninen julkaisu (PDF)", "source": { "value": "selma", "translated": "Eduskunnan kirjasto - Selma" } } ] |
openUrl | Merkkijono | OpenURL (kirjastoaineisto). |
originalLanguages | Lista | Aineiston alkuperäiskielet. Katso myös languages. "originalLanguages": [ "jpn" ] |
otherLinks | Lista | Muut tietueen linkit. Käytetään ainakin arvosteltujen teosten merkitsemiseen. "otherLinks": [ { "heading": "Arvosteltu teos", "title": "Viimeiset runonlaulajat", "author": "Martti Haavio" } ] |
physicalDescriptions | Lista | Aineiston fyysinen kuvaus. "physicalDescriptions": [ "0,01 hyllmeter", "1 arkivenheter" ] |
physicalLocations | Lista | Arkistomateriaalin fyysiset sijainnit. "physicalLocations": [ "Historiska och litteraturhistoriska arkivet", "Helsingfors, Nationalbiblioteket" ] |
placesOfPublication | Lista | Julkaisupaikka "placesOfPublication": [ "New York, NY :" ] |
playingTimes | Lista | Toistoaika. Käytetään ainakin äänitteiden yksittäisissä kappaleissa ja äänikirjoissa. "playingTimes": [ "00:06:42" ] |
presenters | Esittäjät (ks. myös nonPresenterAuthors).
"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)" ] } | |
productionCredits | Lista | 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)." ] |
projectedPublicationDate | Merkkijono | Arvioitu julkaisuajankohta "projectedPublicationDate": "12\/2015" |
publicationDates | Lista | Julkaisuajankohta "publicationDates": [ "1972" ] |
publicationEndDate | Merkkijono | Viimeinen julkaisuajankohta (kausijulkaisuissa) tai ensi-illan ajankohta (elokuvissa). "publicationEndDate": "2003" Edelleen jatkuva julkaisu merkitään usein vuotena 9999: "publicationEndDate": "9999" |
publicationFrequency | Lista | Julkaisutiheys. Ilmoitettu yleensä sanallisesti suomeksi. "publicationFrequency": [ "Kerran kuukaudessa." ] |
publicationInfo | Lista | 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 | |
rating | Lista | Käyttäjien julkaisulle antamien arvostelujen keskiarvo ja lukumäärä. Käytössä seuraavissa aineistotyypeissä: 0/Book/, 0/Journal/, 0/Sound/ ja 0/Video/.
"rating": { "average": 2.5, "count": 3 } |
rawData | Lista | Tietueen kaikkien indeksikenttien sisältö, pois lukien fullRecord. |
recordLinks | Lista | Tietueiden väliset linkit. Linkki voidaan muodostaa ainakin nimekkeen tai isn:n perusteella.
"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" } ] |
recordPage | Merkkijono | Relatiivinen linkki tietueen sivulle Finnassa. Lisää linkin alkuun https://www.finna.fi |
sectors | Lista | Sektori (kirjasto, museo tai arkisto).
"sectors": [ { "value": "0/mus/", "translated": "Museo" } ] |
series | Lista | Sarjatiedot
"series": [ { "name": "Ursan julkaisuja", "additional": "0357-7937;", "number": "28", "issn": "0357-7937" } ] "series": [ { "name": "Laatukirjasto" } ] |
sfxObjectId | Merkkijono | SFX-tietueen tunniste "sfxObjectId": "1000000000310928" |
shortTitle | Merkkijono | Päänimeke. Katso myös title ja subTitle. "shortTitle": "Parhaat ruokasienet" |
source | Lista | Tietueen lähde
"source": [ { "value": "keski", "translated": "Keski-kirjastot" } ] |
subjects | Lista | 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" ] ] |
subTitle | Merkkijono | Alanimeke. Katso myös title ja shortTitle. "subTitle": "sieniopas" |
summary | Lista | 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." ] |
systemDetails | Lista | Aineiston käyttöön tarvittava järjestelmä. "systemDetails": [ "Internet-yhteys; www-selain." ] |
title | Merkkijono | Koko nimeke. Katso myös shortTitle ja subTitle "title": "Parhaat ruokasienet : sieniopas" |
titleSection | Merkkijono | Nimekkeeseen liittyvä osan numero, jos nimeke kuuluu sarjaan. Katso myös series. "titleSection": "3." |
titleStatement | Merkkijono | Nimekkeeseen liittyvää lisätietoa. Sisältää usein tietoja tekijöistä. "titleStatement": "directed by Ridley Scott ; screenplay by Hampton Fancher and David Peoples" |
toc | Lista | 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" ] |
uniformTitles | Lista | Yhtenäistetyt nimekkeet (kirjastoaineisto). "uniformTitles": [ "On the origin of species" ] |
unitId | Merkkijono | Arkistoyksikön tunniste. Katso myös id. "unitId": "Aa:6" |
urls | Lista | Tietueeseen liittyvät resurssit ja toiminnot ulkoisissa järjestelmissä. Sisältää kentät:
"urls": [ { "url": "http:\/\/www.makupalat.fi\/", "desc": "Tietokannan k\u00e4ytt\u00f6liittym\u00e4" }, { "url": "http:\/\/www.makupalat.fi\/fi-FI\/Info\/", "desc": "Tietokantaopas" } ] |
year | Merkkijono | 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
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
16 Comments
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.
Unknown User (timo.mz.laine@helsinki.fi)
Minusta olisi järkevää, että myös
year
-kenttä tulisi oletuksena mukana.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?
Unknown User (timo.mz.laine@helsinki.fi)
Ilman page-parametria haku antaa vain ensimmäisen hakutulossivun. Page-parametria (ks. ohjeet yllä) käyttämällä saa tuloksia enemmän.
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
Unknown User (timo.mz.laine@helsinki.fi)
Muuten ihan oikein, mutta pagen jälkeen ei tule hakasulkeita, eli tähän tapaan: https://api.finna.fi/v1/search?lookfor=&filter[]=online_boolean:%221%22&filter[]=format:%220/Image/%22&page=100
Anonymous
Okei, kiitoksia paljon!
Anonymous
Olisiko asiasanoihin (subjects) mahdollista liittää tieto, mistä sanastosta/ontologiasta ne ovat peräisin?
Ere Maijala
Onnistuu, tosin joudutaan tekemään uusi kenttä, ettei rikota yhteensopivuutta.
Ere Maijala
Tästä on nyt kehitysehdotus ALLI-4905 - Getting issue details... STATUS .
Ere Maijala
Rajapinnasta voi nyt pyytää subjectsExtended-kentän, joka sisältää lähteen lisäksi myös asiasanan tyypin.
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!
Ere Maijala
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.
Anonymous
Hei, pystyykö rajapinnasta pyytämään Finna Streetissä käytössä olevan sijaintitiedon?
Ere Maijala
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.
Anonymous
Kiitos, toimii hyvin!