Katso myös:
Finnan avoin rajapinta (API documentation in Finnish)
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
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
Example queries
Search for records using the search term "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 | |
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 | |
Retrieve a single record by ID | |
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) | |
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 |
Additional information on search parameters
Parameter | Type | Description | Notes |
---|---|---|---|
facet | Array | Facets 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. |
page | Number | Result page | 1-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. |
limit | Number | Number of results | 0-100 (default 20). limit=0 is useful when you only need the number of results or the results of faceting. |
lng | String | Language version |
|
The API also supports Finna advanced search syntax using the same parameters as seen on the advanced search results page, for example:
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.
Additional information on record fields
Field | Desciption |
---|---|
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.
"rating": { "average": 2.5, "count": 3 } |
fullRecord | Original record metadata. |
rawData | All index data for the record, excluding fullRecord. |
recordPage | Relative 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
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.