Finna API (in english)

List of index fields (column Core Fields) that may be used in faceting (Facet Field = Yes).

• Results for non-hierarchical facets (other than format, building, sector_str_mv, category_str_mv) consist of the first 30 values sorted by count in decreasing order. 
• The result item consists of the following fields:
  

  • value: facet value that may be used in the filter-parameter.

  • translated: translated display string

  • count: number of records

  • isApplied: 1 if if the facet is in used in the filter-parameter of the query

  • href: (relative) link for toggling (AND) filtering using the facet on or off (depending on whether the facet is active in the filter-parameter of the current query). For other operators, see 'filter' -field.

  • children Children facet items. Defined only for hierarchical facets.

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

List of facet value filters

• facetFilter[]=<facet>:"<regular expression>"
   

• Allows filtering the returned facet items using regular expressions targeted to the value-field of the facet.
• Note: the filtered facet needs to be present among the list of returned facets (facet-parameter).
  Examples:
  • Only University of Jyväskylä main level among building building-facet
  • University of Jyväskylä building-facet root level values:
    

    • facetFilter[]=building:"0/JYU"

  • University of Jyväskylä building-facet values (all levels):
    

    • facetFilter[]=building:"\d/JYU"

  • Format-facet root level items:

    • facetFilter[]=format:"^0/"

  • e-books and CDs from format-facet:

    • facetFilter[]=format:"(1/Book/eBook/|1/Sound/CD)"

• The result will include the matched facet items and their possible parent items.
  For example when filtering e-books (facetFilter[]=format:"1/Book/eBook/") from format-facet values, the result will include also the root-level item Book (0/Book):

"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"
                }
            ]
        }
    ]
}

• <facet>="<value>"

• List of facet fields (column Core Fields) that may be used in filtering (Facet Field=Yes).
   
• To return possible field values for a facet field you can perform a query without a search term and filters. For example to list all values for the format-field:

  • https://api.finna.fi/v1/search?lookfor=&facet[]=format&prettyPrint=1&limit=0

• AND-filtering is used by default. OR or NOT filtering can be used by prepending the field with '~' (OR) or '-' (NOT). 
  Examples:
  
  • No books: 

    • filter[]=-format:"0:/Book"

  • Books or CDs: 

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

• AllFields (basic search, default)

• Title

• Author

• Subject

• year

• JournalTitle

• CallNumber (shelf location for library material).

• publisher

• Series

• toc (Table of Contents)

• ISN (Journal ISN-number)

• Classification
  • For example:

    • Classification="ykl+35.6"

List of index fields that are used in different search types (column Search).

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

• Relevance (relevance, default)
• title
• author
  • Main author is used when the record has multiple authors.
• last_indexed desc (last indexed)
• main_date_str desc (newest first)
• main_date_str asc (oldest first)
• callnumber (shelf location of library material)
  • When the record has multiple call numbers the first one is used in sorting.

0-100 (oletus 20). limit=0 is useful when you only need the number of results or the results of faceting.

• fi (finnish, default)
• sv (swedish)

• en-gb (english)

  Language version only affects building and format facets and institutions record field.

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.

id record field

• For example jykdok.922403

 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.

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

Alternative titles.

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

Authors.

• main: main author
• corporate: corporate author
• secondary: other authors

"authors": {
    "main": "Bowie, David",
    "secondary": [
        "Spiders from Mars"
    ]
}

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

Awards.

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

Publication type, for example 'Monograph', 'MonographPart' (part of a monograph), 'Serial' (serial publication), 'SerialPart' (part of a serial publication) and 'Unknown'.

"bibliographicLevel": "Monograph"

Location (hierarchical). Includes the following fields:

• value: location code, used in faceting
• translated: translated display string

"buildings": [
    {
        "value": "0\/TAIY\/",
        "translated": "Taideyliopisto"
    },
    {
        "value": "1\/TAIY\/tea\/",
        "translated": "Teatterikorkeakoulun kirjasto"
    },
    {
        "value": "2\/TAIY\/tea\/1\/",
        "translated": "Lainattavat"
    }
]

Library material shelf locations.

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

Number of child records. Requesting this information can increase the query time considerably.

"childRecordCount": 0

Library material classification codes.

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

}

ISBN-number (processed). See also isbns.

"cleanIsbn": "1402087179"

ISSN-number (processed). See also issns.

"cleanIssn": "0065-2164"

Collections. Used for example in museum material.

"collections": [
    "Riuttalan talonpoikaismuseo"
]

Issue number of container publication.

"containerIssue": "4"

Reference to container publication.

"containerReference": "s. 191-201"

Start page number in container publication.

"containerStartPage": "191"

Title of container publication.

"containerTitle": "Finland : an introduction"

Volume of container publication.

"containerVolume": "25"

Corporate author

"corporateAuthor": "Valtiontalouden tarkastusvirasto."

IDs of similar records from other sources.

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

Dissertation note

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

Edition.

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

"edition": "Pidennetty versio"

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

    ]

}

Record formats (hierarchical).

• value: format code (used in faceting)
• translated: translated display string

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"
    }
]

General notes.

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

Genres. See also subjects.

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

"genres": [
    "DVD-levyt"
]

"genres": [
    "kirja-arvostelut"
]

Parent record ID. Used for example in archive (EAD) material.

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

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

Hierarchy top level record ID. Used for example in archive (EAD) material.

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

Hierarchy top level record title. Used for example in archive (EAD) material.

"hierarchyTopTitle": [
    "Viipurin provinssikanslian arkisto"
]

Julkaisuajankohdat ihmisen luettavassa muodossa.

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

Finna record identifier (unique).

"id": "alma.757000"

String

Record identified (not unique).

"identifierString": "201190a20"

"identifierString": "FSD"

Terms of use for record images:

• copyright: Copyright

• link: Link to license

• description: Optional description.

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

        ]
}

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.

Organization. See also buildings.

• value: organization code
• translated: translated display string

"institutions": [
    {
        "value": "LUC",
        "translated": "Lapin korkeakoulukirjasto"
    }
]

ISBN-numbers. See also cleanIsbn.

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

Is the record a archive collection.

"isCollection": true

Is the record part of a archive series.

"isPartOfArchiveSeries": true

ISSN-numbers. See also cleanIssn.

"issns": [
    "1913-4711"
]

Languages. See also originalLanguages.

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

Library of Congress Control Number

"lccn": "2010252176"

Manufacturer.

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

Physical measurements.

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

Authors without presenters. See also presenters.

• name: name
• role: role

"nonPresenterAuthors": [
    {
        "name": "Doyle, Arthur Conan",
    },
    {
        "name": "Attwood, David",
        "role": "ohj."
    }
]

URLs (library material).

• url: URL
• text: (untranslated) display string
• source: record source (organization)
  • value: organization code
  • translated: translated display string

"onlineUrls": [
    {
        "url": "http:\/\/eca.europa.eu\/portal\/page\/portal\/publications\/Journal",
        "text": "Elektroninen julkaisu (PDF)",
        "source": {
            "value": "selma",
            "translated": "Eduskunnan kirjasto - Selma"
        }
    }
]

OpenURL (library material).

Original languages. See also languages.

"originalLanguages": [
    "jpn"
]

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

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

Physical description.

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

Physical locations of archive material.

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

Array

Place of publication.

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

Playing times. Used for example in sound recordings.

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

Presenters (see also nonPresenterAuthors).

• presenters (Array)
  • name: name
  • role: role
• details (Array): Details. Presenter names may also be included here (depending on the metadata).

"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)"
    ]
}

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

Estimated date of publication.

"projectedPublicationDate": "12\/2015"

Date of publication.

"publicationDates": [
    "1972"
]

Last date of publication. Used for example in periodicals and movies.

"publicationEndDate": "2003"

Publication frequency.

"publicationFrequency": [
    "Kerran kuukaudessa."
]

Publication info (may also include the place of publication).

"publicationInfo": [
    "Dortmund"
]

Array

Publishers.

"publishers": [
    "Published by E. & F.N. Spon for the Royal Institute of British Architects"
]

Rating by Finna users. Used in the following formats 0/Book/, 0/Journal/, 0/Sound/ and 0/Video/.

• average: average, 0-5.

• count: number of ratings

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

Raaka metadata käsittelemättömänä. Esimerkkiä ei esitetä tässä suuren koon vuoksi.

Links (relations) between records.

• value
• link
  • type: field of linked record, for example title or ISSN-number
  • value: value of linked record
  • exclude
• translated: translated display string of link type

"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"
    }
]

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"
    }
]

SFX-tietueen tunniste

"sfxObjectId": "1000000000310928"

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

"shortTitle": "Parhaat ruokasienet"

Array

Tietueen lähde

• value: organisaation koodi
• translated: organisaation käännetty nimi

"source": [
    {
        "value": "keski",
        "translated": "Keski-kirjastot"
    }
]

Asiasanat/aiheet. Array 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"
    ]

]

Alanimeke. Katso myös title ja shortTitle.

"subTitle": "sieniopas"

Yhteenveto/tiivistelmä (pituus vaihtelee). Kaikkia Finnassa olevia tiivistelmiä ei tarjota rajapinnan kautta tekijänoikeudellisista syistä johtuen. Mikäli rajapinta palauttaa tiivistelmän, sen käyttö on sallittua rajapinnan käyttöehtojen mukaisesti.

"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."
]

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

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

Koko nimeke. Katso myös shortTitle ja subTitle

"title": "Parhaat ruokasienet : sieniopas"

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

"titleSection": "3."

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

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

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

Yhtenäistetyt nimekkeet (kirjastoaineisto). Yhtenäisyys ei välttämättä toteudu eri organisaatioiden välillä.

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

Arkistoyksikön tunniste (arkistoaineisto)

"unitId": "Aa:6"

Linkit (tietueeseen liittyvät resurssit ja toiminnot ulkoisissa järjestelmissä. Sisältää myös kentän images kuvalinkit). 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"
    }
]

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

"year": "1761"

https://api.finna.fi/v1/search?lookfor=sibelius

https://api.finna.fi/v1/search?lookfor=sibelius&filter[]=format:"1/Sound/CD/"

https://api.finna.fi/v1/search?lookfor=sibelius&filter[]=online_boolean:"1"&filter[]=format:"0/Image/"

https://api.finna.fi/v1/search?lookfor=sibelius&filter[]=online_boolean:"1"&filter[]=format:"0/Image/"&facet[]=building

https://api.finna.fi/v1/search?facet[]=format

https://api.finna.fi/v1/search?filter[]=online_boolean:"1"&filter[]=format:"0/Image/"

https://api.finna.fi/v1/search?filter[]=usage_rights_str_mv:usage_B

https://api.finna.fi/v1/search?facet[]=building&lng=sv

https://api.finna.fi/v1/search?lookfor=sibelius&type=Author

https://api.finna.fi/v1/record?id=fennica.123

https://api.finna.fi/v1/record?id[]=fennica.123&id[]=fennica.124

https://api.finna.fi/v1/search?lookfor=id:vaski.2667110+OR+local_ids_str_mv:vaski.2667110
https://api.finna.fi/v1/record?id=vaski.2667110

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