History
29.1.2016 First version
Terms of Use
To be added later.
Questions and feedback may be sent to [email protected].
General
The API provides a way to perform searches to the material provided by the organizations participating in Finna.fi.
The queries are formatted in the following way:
https://api.finna.fi/v1/<action>?<parameters>
By default the results are returned in json-format. jsonp-format is used if the request includes a callback-parameter
https://api.finna.fi/v1/<action>?callback=process
Actions
Search
https://api.finna.fi/v1/search?<parameters>
Perform a search.
Parameter | Type | Selite | Sallitut arvot |
---|---|---|---|
lookfor | String | Search term | |
facet | Array | Facets to be returned | List of index fields (column Core Fields) that may be used in faceting (Facet Field = Yes).
"facets": { |
facetFilter | Array | List of facet value filters |
"facets": { "format": [ { "value": "0\/Book\/", "translated": "Book", "count": 4893, "href": "?lookfor=sibelius&type=AllFields&filter%5B%5D=format%3A%220%2FBook%2F%22", "children": [ { "value": "1\/Book\/eBook\/", "translated": "e-book", "count": 237, "href": "?lookfor=sibelius&type=AllFields&filter%5B%5D=format%3A%221%2FBook%2FeBook%2F%22" } ] } ] } |
filter | Array | Search filters |
See type-field for using non-facet fields in filtering. |
type | String | Search type |
List of index fields that are used in different search types (column Search). A query may be targeted to a specific (non-facet) index field by including the field in the search term. ?lookfor=publication_place_txt_mv:pomarkku&field[]=id&field[]=publication_place_str_mv&field[]=placesOfPublication&field[]=publicationInfo&prettyPrint=1 Note: put facet fields in the filter-parameter. For example: ?lookfor=format:0/Book/ (not supported) ?lookfor=&filter[]=format:0/Book/ (use this instead) |
sort | String | Search result order |
|
page | Number | Result page | 1-n (default 1). |
limit | Number | Number of results | 0-100 (oletus 20). limit=0 is useful when you only need the number of results or the results of faceting. |
lng | String | Language version |
|
field | Array | Record fields to be returned | See the list of supported record fields below. If not defined, the bolded record fields from the list are returned. If empty, no records are returned. |
callback | String | JSONP callback-function | Optional, not in use by default. |
prettyPrint | Number | Pretty printed JSON result | 0, 1 (default 0). |
Similar records (mainly books) from different sources are combined (deduplicated) during the search and only the record with the highest priority is shown in the search results. Filter the results using building to restrict returned records to specific sources.
The record field of dedupIds of a deduplicated record contains the IDs of similar records, for eaxmple:
{
"resultCount": 42,
"records": [
{
"id": "fennica.1003041",
"title": "Puhdistus",
"dedupIds": [
"fennica.1003041",
"jykdok.1256458",
"keski.2341400",
"vaari.1688117",
"vaski.2846838"
]
},
The IDs can be used to return a specific version of a record (see Record-action).
Faceting results are affected by all similar records that have been combined in the search results to a single (deduplicated) result. For example, the values of all similar records are shown in the building facet. If needed, use facetFilter-parameter to restrict returned facet results.
Record
https://api.finna.fi/v1/record?<parameters>
Retrieve record fields.
Parameter | Type | Description | Supported values |
---|---|---|---|
id | String|Array | Record ID or IDs | id record field
|
field | Array | Record fields. | See the list of supported record fields below. If not defined, the bolded record fields from the list are returned. If empty, no records are returned. |
callback | String | JSONP callback-function | Optional, not in use by default. |
prettyPrint | Number | Pretty printed JSON result | 0, 1 (default 0). |
Supported record fields
The following record fields can be used in the field parameter.
Record field content is dependent on the quality of the metadata. Most record fields are not unified acrossa records and therefore, for example, author names may be presented in different ways. Fields may also contain untranslated content.
If a requested field is missing from the response, it is not defined for the record.
Field | Type | Desciption |
---|---|---|
accessRestrictions | Array | Access restrictions, if known. "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 | Array | Alternative titles. "alternativeTitles": [ "Miehet mustissa", "MIB" ] |
authors | Array | Authors.
"authors": { "main": "Bowie, David", "secondary": [ "Spiders from Mars" ] } "authors": { "main": "Ozric Tentacles", "corporate": "Ozric Tentacles," } |
awards | Array | Awards. "awards": [ "Tieto-Finlandia-palkinto 2013." ] |
bibliographicLevel | String | Publication type, for example 'Monograph', 'MonographPart' (part of a monograph), 'Serial' (serial publication), 'SerialPart' (part of a serial publication) and 'Unknown'. "bibliographicLevel": "Monograph" |
buildings | Array | Location (hierarchical). Includes the following fields:
"buildings": [ { "value": "0\/TAIY\/", "translated": "Taideyliopisto" }, { "value": "1\/TAIY\/tea\/", "translated": "Teatterikorkeakoulun kirjasto" }, { "value": "2\/TAIY\/tea\/1\/", "translated": "Lainattavat" } ] |
callNumbers | Array | Library material shelf locations. "callNumbers": [ "84.5", "KAUHU" ] |
childRecordCount | Number | Number of child records. Requesting this information can increase the query time considerably. "childRecordCount": 0 |
classifications | Array | Library material classification codes. "classifications": { } |
cleanIsbn | String | ISBN-number (processed). See also isbns. "cleanIsbn": "1402087179" |
cleanIssn | String | ISSN-number (processed). See also issns. "cleanIssn": "0065-2164" |
collections | Array | Collections. Used for example in museum material. "collections": [ "Riuttalan talonpoikaismuseo" ] |
containerIssue | String | Issue number of container publication. "containerIssue": "4" |
containerReference | String | Reference to container publication. "containerReference": "s. 191-201" |
containerStartPage | String | Start page number in container publication. "containerStartPage": "191" |
containerTitle | String | Title of container publication. "containerTitle": "Finland : an introduction" |
containerVolume | String | Volume of container publication. "containerVolume": "25" |
corporateAuthor | String | Corporate author "corporateAuthor": "Valtiontalouden tarkastusvirasto." |
dedupIds | Array | IDs of similar records from other sources. "dedupIds": [ "alma.678448", "oula.894534", "tamcat.399614" ] |
dissertationNote | String | Dissertation note "dissertationNote": "Pro gradu -ty\u00f6 : Tampereen yliopisto, historiatieteen laitos, yleinen historia." |
edition | String | Edition. "edition": "10. osin uud. laitos" "edition": "Pidennetty versio" |
embeddedComponentParts | Array | Component parts that belong to the record. Used for example in sound recordings. Requesting this information can increase the query time considerably. "embeddedComponentParts": [ { "id": "viola.305175", "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" ] }, { "id": "viola.305176", ... |
events | Array | Events related to the record (for example creation, find, use in museum material) "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 | Array | Record formats (hierarchical).
For example: e-book (1/Book/eBook/) is a child of Book (0/Book/). The whole format hierarchy is returned starting from the root level. "formats": [ { "value": "0\/Book\/", "translated": "Kirja" }, { "value": "1\/Book\/eBook\/", "translated": "E-kirja" } ] |
fullRecord | String | Original metadata of the record (MARC, EAD, LIDO, DC, QDC). |
generalNotes | Array | General notes. "generalNotes": [ "Ainoastaan verkkolehden vuoden viimeinen numero ilmestyy painettuna.", "Ei ilmestynyt lainkaan painettuna 2005." ] |
genres | Array | Genres. See also subjects. "genres": [ "Electronic books", "Conference proceedings" ] "genres": [ "DVD-levyt" ] "genres": [ "kirja-arvostelut" ] |
hierarchyParentId | Array | Parent record ID. Used for example in archive (EAD) material. "hierarchyParentId": [ "narc.VAKKA-192941.KA_VAKKA-62641.KA" ] |
hierarchyParentTitle | Array | Parent record titlle. Used for example in archive (EAD) material. "hierarchyParentTitle": [ "Aa Diaarit" ] "hierarchyParentTitle": [ "The rise and fall of Ziggy Stardust and the spiders from Mars" ] |
hierarchyTopId | Array | Hierarchy top level record ID. Used for example in archive (EAD) material. "hierarchyTopId": [ "narc.VAKKA-192941.KA" ] |
hierarchyTopTitle | Array | Hierarchy top level record title. Used for example in archive (EAD) material. "hierarchyTopTitle": [ "Viipurin provinssikanslian arkisto" ] |
humanReadablePublicationDates | Array | Julkaisuajankohdat ihmisen luettavassa muodossa. "humanReadablePublicationDates": [ "1983-2006." ] |
id | String | Finna record identifier (unique). "id": "alma.757000" |
identifierString | String
| Record identified (not unique). "identifierString": "201190a20" "identifierString": "FSD" |
imageRights | Array | Terms of use for record images:
"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 | Array | Record image URLs. "images": [ "\/Cover\/Show?id=hkm.HKMS000005%3Akm002w3s&fullres=1&index=0" ] Prepend the URL with https://www.finna.fi when retrieving the image, for example: https://www.finna.fi/Cover/Show?id=hkm.HKMS000005%3Akm002w3s&fullres=1&index=0 For books the URL will return a transparent .gif-image (10x10 pixels) when no book cover is found. |
institutions | Array | Organization. See also buildings.
"institutions": [ { "value": "LUC", "translated": "Lapin korkeakoulukirjasto" } ] |
isbns | Array | ISBN-numbers. See also cleanIsbn. "isbns": [ "951-0-31435-8 (sid.)", "978-951-0-31435-7 (sid.)" ] |
isCollection | Boolean | Is the record a archive collection. "isCollection": true |
isPartOfArchiveSeries | Boolean | Is the record part of a archive series. "isPartOfArchiveSeries": true |
issns | Array | ISSN-numbers. See also cleanIssn. "issns": [ "1913-4711" ] |
languages | Array | Languages. See also originalLanguages. "languages": [ "fin", "swe" ] |
lccn | String | Library of Congress Control Number "lccn": "2010252176" |
manufacturer | String | Manufacturer. "manufacturer": "([Myllykoski] : Myllykosken kirjap.)" |
measurements | Array | Physical measurements. "measurements": [ "Pituus: 42 cm", "Leveys: helma 22 cm; rinta 34 cm; olka+hiha 14,5+32,5 cm", "Lis\u00e4mitta: Koko 110" ] |
nonPresenterAuthors | Array | Authors without presenters. See also presenters.
"nonPresenterAuthors": [ { "name": "Doyle, Arthur Conan", }, { "name": "Attwood, David", "role": "ohj." } ] |
onlineUrls | Array | URLs (library material).
"onlineUrls": [ { "url": "http:\/\/eca.europa.eu\/portal\/page\/portal\/publications\/Journal", "text": "Elektroninen julkaisu (PDF)", "source": { "value": "selma", "translated": "Eduskunnan kirjasto - Selma" } } ] |
openUrl | String | OpenURL (library material). |
originalLanguages | Array | Original languages. See also languages. "originalLanguages": [ "jpn" ] |
otherLinks | Array | Record relations. Used in MARC records. "otherLinks": [ { "heading": "Arvosteltu teos", "title": "Viimeiset runonlaulajat", "author": "Martti Haavio" } ] |
physicalDescriptions | Array | Physical description. "physicalDescriptions": [ "0,01 hyllmeter", "1 arkivenheter" ] |
physicalLocations | Array | Physical locations of archive material. "physicalLocations": [ "Historiska och litteraturhistoriska arkivet", "Helsingfors, Nationalbiblioteket" ] |
placesOfPublication | Array | Place of publication. "placesOfPublication": [ "New York, NY :" ] |
playingTimes | Array | Playing times. Used for example in sound recordings. "playingTimes": [ "00:06:42" ] |
presenters | Presenters (see also 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 | Array | Production credits. Used for example in sound recordings. "productionCredits": [ "Miikka Huttunen (\u00e4\u00e4nitt\u00e4j\u00e4, miksaaja), Jukkis Uotila (tuottaja), Klaus Suonsaari (tuottaja), Svante Forsb\u00e4ck (masteroija)." ] |
projectedPublicationDate | String | Estimated date of publication. "projectedPublicationDate": "12\/2015" |
publicationDates | Array | Date of publication. "publicationDates": [ "1972" ] |
publicationEndDate | String | Last date of publication. Used for example in periodicals and movies. "publicationEndDate": "2003" |
publicationFrequency | Array | Publication frequency. "publicationFrequency": [ "Kerran kuukaudessa." ] |
publicationInfo | Array | Publication info (may also include the place of publication). "publicationInfo": [ "Dortmund" ] |
publishers | Array
| Publishers. "publishers": [ "Published by E. & F.N. Spon for the Royal Institute of British Architects" ] |
previousTitles / newerTitles | Previous and newer titles. May also be included in the field recordLinks. | |
rating | Array | Rating by Finna users. Used in the following formats 0/Book/, 0/Journal/, 0/Sound/ and 0/Video/.
"rating": { "average": 2.5, "count": 3 } |
rawData | Array | Raaka metadata käsittelemättömänä. Esimerkkiä ei esitetä tässä suuren koon vuoksi. |
recordLinks | Array | Links (relations) between records.
"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 | String | Relative link to record page on Finna. Prepend the URL with https://www.finna.fi |
series | Array | Series information.
"series": [ { "name": "Ursan julkaisuja", "additional": "0357-7937;", "number": "28", "issn": "0357-7937" } ] "series": [ { "name": "Laatukirjasto" } ] |
sfxObjectId | String | SFX-object ID "sfxObjectId": "1000000000310928" |
shortTitle | String | Short title. See also title and subTitle. "shortTitle": "Parhaat ruokasienet" |
source | Array | Source (organization)
"source": [ { "value": "keski", "translated": "Keski-kirjastot" } ] |
subjects | Array | Subjects/Topics. The array consists of a array of topics possibly followed by arrays of subtopics. "subjects": [ [ "Holmes, Sherlock,", "fikt." ], [ "elokuvat", "Iso-Britannia", "2000-2009" ], [ "j\u00e4nnityselokuvat" ], [ "rikoselokuvat" ] ] |
subTitle | String | Subtitle. See also title ja shortTitle. "subTitle": "sieniopas" |
summary | Array | Summary. "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 | Array | Required equipment needed for consuming the material. "systemDetails": [ "Internet-yhteys; www-selain." ] |
title | String | Title. See also shortTitle and subTitle. "title": "Parhaat ruokasienet : sieniopas" |
titleSection | String | Section related to the title, if it is part of a series. See also series. "titleSection": "3." |
titleStatement | String | Additional information related to the title. May also contain information on authors. "titleStatement": "directed by Ridley Scott ; screenplay by Hampton Fancher and David Peoples" |
toc | Array | Table of contents. May also contain other information. "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 | Array | Uniform title. Used in library material. "uniformTitles": [ "On the origin of species" ] |
unitId | String | Archive material ID. See also id. "unitId": "Aa:6" |
urls | Array | Related external resources. Linkit (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 | String | Year (for example year of publication, manufacture). Also used in main_date_str facet. "year": "1761" |
Examples
Search for records using the search term "sibelius": | https://api.finna.fi/v1/search?lookfor=sibelius |
Search CDs using the search term "sibelius": | https://api.finna.fi/v1/search?lookfor=sibelius&filter[]=format:"1/Sound/CD/" |
Search online images using the search term "sibelius" | https://api.finna.fi/v1/search?lookfor=sibelius&filter[]=online_boolean:"1"&filter[]=format:"0/Image/" |
Search online images using the search term "sibelius", faceted by organization | https://api.finna.fi/v1/search?lookfor=sibelius&filter[]=online_boolean:"1"&filter[]=format:"0/Image/"&facet[]=building |
Formats of all records | https://api.finna.fi/v1/search?facet[]=format |
All online images | https://api.finna.fi/v1/search?filter[]=online_boolean:"1"&filter[]=format:"0/Image/" |
All records with the allowed use "Modifications allowed, also commercial use" | https://api.finna.fi/v1/search?filter[]=usage_rights_str_mv:usage_B |
All organizations, names in swedish | https://api.finna.fi/v1/search?facet[]=building&lng=sv |
Records with "sibelius" as author | https://api.finna.fi/v1/search?lookfor=sibelius&type=Author |
Retrieve a single record by ID | https://api.finna.fi/v1/record?id=fennica.123 |
Retrieve two records by ID | https://api.finna.fi/v1/record?id[]=fennica.123&id[]=fennica.124 |
The search term may also include a more complex query, for example a target (non-facet) field or a logical operator. See also 'type' parameter of Search action.
Search using search terms "sibelius" and "festival" | https://api.finna.fi/v1/search?lookfor=sibelius+AND+festival |
Demo application
https://github.com/NatLibFi/NDL-VuFind2/tree/gh-pages/api
Additional information
The API also supports Finna advanced search syntax using the same parameters as seen on the advanced search results page, for example:
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