General

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

• finto.fi widget
• Twitter bot @FinnaBot
• Slide show
• Memory game
• finna-proxy

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:

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

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:

• formats: https://api.finna.fi/v1/search?lookfor=&facet[]=format&prettyPrint=1&limit=0
• language codes: https://api.finna.fi/v1/search?lookfor=&language[]=format&prettyPrint=1&limit=0 (uses slightly extended ISO 639-3, see mapping table)

Example queries

Additional information on search parameters

Finna search instuctions.

{
   "resultCount": 42,
   "records": [

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

Additional information on record fields

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

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

History

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.