Pokapi (Python Okapi Interface) is a Python package for getting basic data from a FOLIO LSP server using the Okapi API.

The FOLIO platform is a library services platform.  The Caltech Library uses a hosted solution by EBSCO for its library catalog.   To make writing interfaces and automation scripts in Python easier, the Caltech Library Digital Library Development team are developing Pokapi (Python Okapi Interface), a Python package that provides an object-oriented interface to accessing in a FOLIO record data via the Okapi API.


The instructions below assume you have a Python interpreter installed on your computer; if that's not the case, please first install Python version 3 and familiarize yourself with running Python programs on your system.

On Linux, macOS, and Windows operating systems, you should be able to install pokapi with pip.  To install pokapi from the Python package repository (PyPI), run the following command:

python3 -m pip install pokapi

As an alternative to getting it from PyPI, you can use pip to install pokapi directly from GitHub, like this:

python3 -m pip install git+https://github.com/caltechlibrary/pokapi.git


The use of Pokapi is straightfoward. First, callers must create one instance of a Folio object that defines various aspects of how to communicate with their FOLIO/Okapi system. Then, callers can use the record(...) method on that Folio object to get objects that represent records in their FOLIO system. The method only requires an identifier, which can be a FOLIO instance identifier, an item barcode, or an EDS accession number. More details about all of this are provided below.

The Folio interface object

To use Pokapi, first create a Folio object with parameters that define certain things Pokapi can't get on its own. These are: the the Okapi URL for your instance, an Okapi API token, a tenant id, and the prefix that appears in front of your accession numbers.  Assuming that these values are stored in separate variables, the following code illustrates how to create a Folio object:

from pokapi import Folio

folio = Folio(okapi_url = the_okapi_url,
              okapi_token = the_okapi_token,
              tenant_id = the_tenant_id,
              an_prefix = the_accession_number_prefix)

As an example of a prefix for accession numbers, for Caltech the prefix is the clc part of an accession number such as clc.025d49d5.735a.4d79.8889.c5895ac65fd2.

The record(...) method

The Folio class has only one method on it currently: record(...). This method contacts the FOLIO server to obtain data and returns a FolioRecord object with the data stored in fields. The following fields are implemented at this time:

Field Type Meaning
id string FOLIO instance record identifier
accession_number string The accession number for the record
title string Title of the work
author string Author; multiple authors are separated by "and"
publisher string Publisher
year string Year of publication
edition string the edition of the work (if any)
isbn_issn string ISBN or ISSN

The method Folio.record(...) can take any one of the following mutually-exclusive keyword arguments to identify the record to be retrieved:

  • barcode: retrieve the record corresponding to the given item barcode
  • instance_id: retrieve the record having the given FOLIO instance identifier
  • accession_number: retrieve the record corresponding to the accession number

Here is an example of using the method:

r = folio.record(barcode = "35047019531631")
assert r.id == "1fedf5f3-b631-4d34-8d40-e022f70ab232"
assert r.title == "The bad doctor"
assert r.year == "2015"
assert r.author == "Williams, Ian"
assert r.isbn_issn == "9780271067544"
assert r.publisher == "The Pennsylvania State University Press"

Known issues and limitations

The following are known limitations at this time:

  • If a record has multiple publishers, only the first publisher name is retrieved.
  • The title is extracted from the instance record's title field, but because (at least in our catalog) the title contains both a title and author info, Pokapi has to use heuristics to extract out just the title from the string. The heuristics might fail in some cases, especially if your installation of FOLIO uses different conventions for formatting the title field.
GitHub - caltechlibrary/pokapi: Simple Python objects for getting data from Folio
Simple Python objects for getting data from Folio. Contribute to caltechlibrary/pokapi development by creating an account on GitHub.