Katso myös:

Finnan avoin rajapinta (API documentation in Finnish)

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.

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

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

Terms of Use

See API Terms of Use and Recommendations.

Documentation in Swagger

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

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

Example queries

  
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/"&field[]=title&field[]=images
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&field[]=title&field[]=images

Search for records from years 1870-1890

https://api.finna.fi/v1/search?lookfor=&filter[]=search_daterange_mv:"[1870%20TO%201890]"

Formats of all records

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

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

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

All online images

https://api.finna.fi/v1/search?lookfor=&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?lookfor=&filter[]=usage_rights_str_mv:usage_B

All organizations, names in swedish

https://api.finna.fi/v1/search?lookfor=&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

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

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

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)

 https://api.finna.fi/v1/search?lookfor=publication_place_txt_mv:pomarkku&field[]=id&field[]=publication_place_str_mv&field[]=placesOfPublication&field[]=publicationInfo&prettyPrint=1

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"

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

Examples of Use

Additional information on search parameters

ParameterTypeDescriptionNotes
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": "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.

More information on the deduplication algorithm

Additional information on record fields

FieldDesciption
childRecordCount

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

embeddedComponentParts

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

images

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

https://api.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.

rating

Rating by Finna users.

  • average: average, 0-5.

  • count: number of ratings

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

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=viola.49914&field[]=fullRecord

  • No labels