Skip to main content

Python client library for accessing Finna REST API

Project description

Finna-client

This is a minimal Python 3.x client library for accessing the Finna.fi 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.

Installation

The easiest way to install is via pip:

pip3 install finna-client

Dependencies

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 finna_client.py 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 finna_client.py
Demonstrating usage of FinnaClient

* Creating a FinnaClient object
Now we have a FinnaClient object: FinnaClient(api_base='https://api.finna.fi/api/v1/')

* 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
URL:   https://api.finna.fi/Cover/Show?id=musketti_helina.M015%3ARd3.1%3A768&index=0&size=large

Title: Mainoskortti (painokuva): englantilaisen Harry Holt Trio:n mainoskortti
URL:   https://api.finna.fi/Cover/Show?id=muistaja_kerava.M011-90287&index=0&size=large

Title: Postikorttipainanteinen valokuva kahdeksasta oksalla seisovasta makawi-papukaijasta Miamin Parrot Junglessa
URL:   https://api.finna.fi/Cover/Show?id=siirtolaisuusmuseo_ah.M011-1376833&index=0&size=large


* 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'}

License

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