Page History

Versions Compared

Key

This line was added.
This line was removed.
Formatting was changed.

...

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

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

...

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.

...

Parameter

Type

Description

Allowed values

lookfor

String

Search term

facet

Array

Facets to be returned

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&amp;type=AllFields&amp;limit=2&amp;filter%5B%5D=building%3A%220%2FVaski%2F%22&amp;filter%5B%5D=format%3A%220%2FMusicalScore%2F%22"
  },

facetFilter

Array

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&amp;type=AllFields&amp;filter%5B%5D=format%3A%220%2FBook%2F%22",
            "children": [
                {
                    "value": "1\/Book\/eBook\/",
                    "translated": "e-book",
                    "count": 237,
                    "href": "?lookfor=sibelius&amp;type=AllFields&amp;filter%5B%5D=format%3A%221%2FBook%2FeBook%2F%22"
                }
            ]
        }
    ]
}

filter

Array

Search filters

```
<facet>="<value>"
```
List of facet fields (column Core Fields) that may be used in filtering (Facet Field=Yes).
- Examples:
  - format: Content type (book, image, physical object...)
  - building: Organization that provides the material
  - online_boolean: Online available material
  - usage_rights_str_mv: Usage rights code
  - search_daterange_mv: date range
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/"
   
```

Info
See type-field for using non-facet fields in filtering.

type

String

Search type

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

Info

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

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

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

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

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

sort

String

Search result order

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.

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

fi (finnish, default)
sv (swedish)
en-gb (english)
Info
Language version only affects building and format facets and institutions record field.

field

Array

Record fields to be returned

See the list of supported record fields below. If not defined, the record fields marked with bold in the list are returned. If empty, no records are returned.

callback

String

JSONP callback-function

Optional, not in use by default.

prettyPrint

Number

Pretty printed JSON result

0, 1 (default 0).

...

Content

Space Tools

Versions Compared

Old Version 44

New Version 45

Key

General

Terms of Use