Katso myös:

Finnan avoin rajapinta (API documentation in Finnish)


The API provides a way to perform searches to the material provided by the organizations (Finnish libraries, archives and museums) participating in Finna.fi. For example the metadata of Fennica - the Finnish National Bibliography and Viola - the Finnish National Discography are included in the API. The Library Network Services unit of the National Library is responsible for the maintenance and development of the interface.

Inquiries and feedback on the API:  finna-posti AT helsinki.fi

Terms of Use

See API Terms of Use and Recommendations.

Examples of Use

Documentation in Swagger

The primary and up to date documentation is available in the Swagger UI.

The OpenAPI specification can be loaded from https://api.finna.fi/v1?swagger.

Basic Usage

The queries are formatted in the following way:


By default the results are returned in JSON  format. JSONP format is used if the request includes a callback parameter:


CORS is also supported, and all origin URLs are allowed.

The API is not meant for handling large result sets (see the page parameter for more information).

Available filter values can be fetched with an empty search and the field as a facet:

Example queries

Search for records using the search term "sibelius":


Search CDs using the search term "sibelius":


Search online images using the search term "sibelius" https://api.finna.fi/v1/search?lookfor=sibelius&filter[]=online_boolean:"1"&filter[]=format:"0/Image/"&field[]=title&field[]=images
Search online images using the search term "sibelius", faceted by organization


Search for records from years 1870-1890


Formats of all records


Set limit to 0 if you don't need records:


All online images


All records with the allowed use "Modifications allowed, also commercial use"


All organizations, names in swedish


Records with "sibelius" as author


Retrieve a single record by ID


Retrieve two records by ID


To return possible field values for a facet field you can perform a query without a search term and filters.


A query may be targeted to a specific (non-facet) index field by including the field in the search term.

Note: put facet fields in the filter-parameter. For example:

?lookfor=format:0/Book/ (not supported)

?lookfor=&filter[]=format:0/Book/ (use this instead)


NOT & AND filters

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"


Additional information on search parameters

facetArrayFacets to be returned

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. 

pageNumberResult page1-n (default 1). N.B. The API returns a maximum of 100 000 records. E.g. with limit=20 maximum page=5000. If it's necessary to handle larger sets of records, it's possible to limit the set handled at once e.g. with the last_indexed field.
limitNumberNumber of results

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

lngStringLanguage version

  • fi (finnish, default)
  • sv (swedish)
  • en-gb (english)

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

Finna search instuctions.

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": "fikka.3405646",
            "title": "Uimaveden puhdistus",
            "dedupIds": [

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.

More information on the deduplication algorithm

Additional information on record fields


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


Component parts that belong to the record. Used for example in sound recordings. Requesting this information can increase the query time considerably.


Prepend the URL with https://api.finna.fi when retrieving the image, for example:


For books the URL will return a transparent .gif-image (10x10 pixels) when no book cover is found.


Rating by Finna users.

  • average: average, 0-5.

  • count: number of ratings

"rating": {
    "average": 2.5,
    "count": 3
fullRecordOriginal record metadata.

All index data for the record, excluding fullRecord.

recordPageRelative link to record page on Finna. Prepend the URL with https://www.finna.fi

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.

Handling of Component Parts

Some MARC records found in Finna contain embedded component parts. These include articles in a journal and pieces of music in a music CD. In the Finna UI these are displayed in the Contents/Pieces tab of the record view for the host record, and the metadata used for this list is in host record's MARC field 979. In the API the 979 fields have been compacted to a single field, which contains a repeated subfield for each component part ID. Metadata for the component parts can be fetched as necessary with the record action of the API by using the record IDs found in the subfields a of field 979.

Here is an example record containing component parts: https://api.finna.fi/v1/record?id=fikka.4450004&field[]=fullRecord


29.1.2016 First version
5.2.2016 Added information regarding the handling of component parts
17.3.2016 Fixed erroneous prefix for image URLs in the description for field 'images'. 
22.6.2016 Updated Examples of Use
26.9.2016 Added support for CORS
17.1.2017 Added a mention of the Swagger specification and UI
17.1.2017 The API has new fields subjectsExtended and imagesExtended. See the Swagger UI for more information.
5.1.2017 Added a mention about the maximum number of results and hints for searching larger sets
4.10.2018 Documentation now only in Swagger. Added additional notes and revised example queries.

  • No labels