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.

Files for finna-client, version 0.1.2
Filename, size File type Python version Upload date Hashes
Filename, size finna_client-0.1.2-py3-none-any.whl (6.1 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size finna-client-0.1.2.tar.gz (5.4 kB) File type Source Python version None Upload date Hashes View

Supported by

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