Skip to main content

Python client library for accessing Finna REST API

Project description


This is a minimal Python 3.x client library for accessing the REST API. The API can be used to search for records (e.g. books and images) in the Finna discovery service and to retrieve information about individual records.


The easiest way to install is via pip:

pip3 install finna-client


The library depends on the requests module which is used for HTTP/REST access. If you install this via pip, the dependencies will be handled automatically.

How to use

The client library comes with examples demonstrating its usage. You can invoke the example simply by running the script.

In your own code, you can use the FinnaClient class like this:

from finna_client import FinnaClient

# then you can create your own client
finna = FinnaClient()

Example invocation

Here is the output from a typical example session:

$ python3
Demonstrating usage of FinnaClient

* Creating a FinnaClient object
Now we have a FinnaClient object: FinnaClient(api_base='')

* Performing a general search
Search would have matched 1354 records
{'buildings': [{'value': '0/Helmet/', 'translated': 'Helmet-kirjastot'}, {'value': '1/Helmet/v/', 'translated': 'Vantaa'}, {'value': '2/Helmet/v/v28/', 'translated': 'Länsimäki'}], 'onlineUrls': [], 'series': [], 'subjects': [['matkailu'], ['pyöräily'], ['polkupyörät'], ['kulkuneuvot']], 'languages': ['eng'], 'rating': {'count': 0, 'average': 0}, 'images': ['/Cover/Show?author=Byrne%2C+David&callnumber=&size=large&title=Bicycle+diaries&recordid=helmet.2029887&source=Solr&isbn=0571241034&index=0'], 'formats': [{'value': '0/Book/', 'translated': 'Kirja'}, {'value': '1/Book/Book/', 'translated': 'Kirja'}], 'presenters': {'presenters': [], 'details': []}, 'id': 'helmet.2029887', 'title': 'Bicycle diaries', 'nonPresenterAuthors': [{'name': 'Byrne, David'}]}
{'buildings': [{'value': '0/Heili/', 'translated': 'Heili-kirjastot'}, {'value': '1/Heili/12/', 'translated': 'Parikkala'}, {'value': '2/Heili/12/321/', 'translated': 'Saaren kirjasto'}], 'onlineUrls': [], 'series': [{'name': 'The Boxcar Children'}], 'subjects': [], 'languages': ['eng'], 'rating': {'count': 0, 'average': 0}, 'images': [], 'formats': [{'value': '0/Book/', 'translated': 'Kirja'}, {'value': '1/Book/Book/', 'translated': 'Kirja'}], 'presenters': {'presenters': [], 'details': []}, 'id': 'heili.888120', 'title': 'Bicycle Mystery', 'nonPresenterAuthors': [{'name': 'Warner, Gertrude Chandler'}, {'name': 'Cunningham, David kuvittanut', 'role': 'aut'}]}
{'buildings': [{'value': '0/Keski/', 'translated': 'Keski-kirjastot'}, {'value': '1/Keski/jyv/', 'translated': 'Jyväskylä'}], 'onlineUrls': [], 'series': [], 'subjects': [['free jazz', 'triot', '2000-2009'], ['jazz', 'sähkökitara', 'Suomi', '2000-2009'], ['jazz', 'bassokitara', 'Yhdysvallat', '2000-2009'], ['jazz', 'kontrabasso', 'Yhdysvallat', '2000-2009'], ['jazz', 'rummut', 'Saksa', '2000-2009'], ['psykedeelinen rock', '2000-2009']], 'languages': ['eng'], 'rating': {'count': 0, 'average': 0}, 'images': [], 'formats': [{'value': '0/Sound/', 'translated': 'Äänite'}, {'value': '1/Sound/CD/', 'translated': 'CD'}], 'presenters': {'presenters': [{'name': 'Johnny La Marama', 'role': 'esitt.'}, {'name': 'Kalima, Kalle', 'role': 'esitt.'}], 'details': ['Johnny La Marama: Chris Dahlgren (b, electronics, voc), Kalle Kalima (g, electronics, voc), Eric Schaefer (dr, perc, sampler, voc)']}, 'id': 'keski.512598', 'title': 'Bicycle revolution', 'nonPresenterAuthors': []}
{'buildings': [{'value': '0/Helmet/', 'translated': 'Helmet-kirjastot'}, {'value': '1/Helmet/k/', 'translated': 'Kauniainen'}, {'value': '2/Helmet/k/k01/', 'translated': 'Kauniainen'}], 'onlineUrls': [], 'series': [], 'subjects': [['1940-luku'], ['1950-luku'], ['Yhdysvallat']], 'languages': ['eng'], 'rating': {'count': 0, 'average': 0}, 'images': [], 'formats': [{'value': '0/Sound/', 'translated': 'Äänite'}, {'value': '1/Sound/SoundDisc/', 'translated': 'Äänilevy'}], 'presenters': {'presenters': [{'name': 'Gaddy, Bob', 'role': 'esittäjä'}, {'name': 'Gaddy, Bob', 'role': 'laulaja'}, {'name': 'Gaddy, Bob', 'role': 'piano'}, {'name': 'Dupree, Jac', 'role': 'laulaja'}, {'name': 'Dupree, Jack', 'role': 'piano'}, {'name': 'Sue, Bobby', 'role': 'laulaja'}], 'details': []}, 'id': 'helmet.1252370', 'title': 'Bicycle boogie', 'nonPresenterAuthors': [{'name': 'Gaddy, Bob', 'role': 'säveltäjä'}, {'name': 'McGhee, Brownie', 'role': 'säveltäjä'}, {'name': 'Dupree, Jack', 'role': 'säveltäjä'}, {'name': 'Dale, Larry', 'role': 'säveltäjä'}, {'name': 'Sue, Bobby', 'role': 'säveltäjä'}, {'name': 'Terry, Sonny', 'role': 'huuliharppu'}, {'name': 'McGhee, Brownie', 'role': 'kitara'}, {'name': 'Harris, Bob', 'role': 'b'}, {'name': 'Wood, George', 'role': 'rummut'}, {'name': 'Dale, Larry', 'role': 'kitara'}, {'name': 'Wallace, Cedric', 'role': 'b'}, {'name': 'Johnson, Earl A.', 'role': 'rummut'}, {'name': 'Moore, Gene', 'role': 'rummut'}, {'name': 'Dodds, Baby', 'role': 'rummut'}, {'name': 'Lucas, Al', 'role': 'b'}, {'name': 'Brown, Pete', 'role': 'alttosaksofoni'}, {'name': 'Spruill, Jimmy', 'role': 'kitara'}, {'name': 'Page, June', 'role': 'b'}, {'name': 'Spoots, George', 'role': 'rummut'}]}
{'buildings': [{'value': '0/Eepos/', 'translated': 'Eepos-kirjastot'}, {'value': '1/Eepos/50/', 'translated': 'Kauhava'}, {'value': '2/Eepos/50/402/', 'translated': 'Kauhavan pääkirjasto'}, {'value': '3/Eepos/50/402/1/', 'translated': '1'}], 'onlineUrls': [], 'series': [], 'subjects': [], 'languages': ['eng'], 'rating': {'count': 0, 'average': 0}, 'images': [], 'formats': [{'value': '0/Sound/', 'translated': 'Äänite'}, {'value': '1/Sound/SoundDisc/', 'translated': 'Äänilevy'}], 'presenters': {'presenters': [], 'details': ['Bob Gaddy (voc, p) ; Brownie McGhee (g) ; Jack Dupree (voc, p) ; Larry Dale (voc, g) ; Bobby Sue (voc)..']}, 'id': 'eepos.2088987', 'title': 'Bicycle boogie', 'nonPresenterAuthors': [{'name': 'Gaddy, Bob'}]}

* Performing a search for images available online
Search would have matched 3 records
Title: Lavagem do Bonfim

Title: Mainoskortti (painokuva): englantilaisen Harry Holt Trio:n mainoskortti

Title: Postikorttipainanteinen valokuva kahdeksasta oksalla seisovasta makawi-papukaijasta Miamin Parrot Junglessa

* Performing a book search by author, sorting results by date, oldest first
Search would have matched 5477 records
{'id': 'fennica.431237', 'year': '1800', 'title': 'Tomtesagor'}
{'id': 'alma.510296', 'year': '1822', 'title': 'Suomen kansan wanhoja runoja, ynnä myös nykyisempiä lauluja'}
{'id': 'piki.916440', 'year': '1822', 'title': 'Suomen kansan vanhoja runoja, ynnä myös nykyisempiä lauluja. Ensimmäinen osa'}
{'id': 'sksdoria_books.10024_147698', 'year': '1822', 'title': 'Suomen kansan wanhoja runoja ynnä myös nykyisempiä lauluja : 1. osa'}
{'id': 'helka.1214011', 'year': '1822', 'title': 'Suomen kansan wanhoja runoja ynnä myös nykyisempiä lauluja'}
* Retrieving a single record
{'buildings': [{'value': '0/NLF/', 'translated': 'Kansalliskirjasto'}, {'value': '1/NLF/fennica/', 'translated': 'Fennica'}], 'onlineUrls': [], 'series': [], 'subjects': [], 'languages': [], 'rating': {'count': 0, 'average': 0}, 'images': [], 'formats': [{'value': '0/Book/', 'translated': 'Kirja'}, {'value': '1/Book/Book/', 'translated': 'Kirja'}], 'presenters': {'presenters': [], 'details': []}, 'id': 'fennica.431237', 'title': 'Tomtesagor', 'nonPresenterAuthors': [{'name': 'Topelius, Z., puuteluettelotieto'}]}

* Retrieving multiple records
{'id': 'alma.510296', 'title': 'Suomen kansan wanhoja runoja, ynnä myös nykyisempiä lauluja'}
{'id': 'piki.916440', 'title': 'Suomen kansan vanhoja runoja, ynnä myös nykyisempiä lauluja. Ensimmäinen osa'}
{'id': 'fennica.431237', 'title': 'Tomtesagor'}


The code is published under the Apache 2.0 license.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

finna-client-0.2.1.tar.gz (6.1 kB view hashes)

Uploaded source

Built Distribution

finna_client-0.2.1-py3-none-any.whl (6.2 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page