View Single Post
Old 08-13-2012, 10:14 PM   #1
jhowell has much to be proud ofjhowell has much to be proud ofjhowell has much to be proud ofjhowell has much to be proud ofjhowell has much to be proud ofjhowell has much to be proud ofjhowell has much to be proud ofjhowell has much to be proud ofjhowell has much to be proud ofjhowell has much to be proud ofjhowell has much to be proud of
jhowell's Avatar
Posts: 83
Karma: 27385
Join Date: Nov 2011
Location: Florida
Device: iPad 2, Kinde PW II
[GUI PLUGIN]Overdrive Link - Version 1.10.2

UI plugin to link books in calibre to lending libraries

Many communities use OverDrive, 3M Cloud Library, Freading and OneClickdigital to handle their lending library services for electronic books. Some lending libraries use multiple service providers, with different book collections available though each. Open Library and Amazon also provide e-book lending services. Checking libraries for e-books of interest can be tedious for large numbers of books and multiple libraries, especially since libraries add to their collections over time.

The purpose of the Overdrive Link user interface action plugin is to search lending libraries for borrowable e-books that correspond to selected books in the user's calibre library. This allows the user to add entries for desired books in calibre and then to check occasionally to see if they are carried by any lending library at which they have borrowing privileges.

The plugin can detect books that are not available in the lending library's collection, but can be recommended for future acquisition by the library or purchased by the user, and provides access to the web page from which the recommendation or purchase can be made.

The plugin can also discover books from known authors or about particular subjects that are missing from the user's calibre library. These can be selectively added as "empty" calibre books.

For the plugin to be useful the user must have borrowing privileges at a lending library powered by one of the supported service providers. Check your local community library for possible access. In addition some libraries, such as the Free Library of Philadelphia, allow e-book borrowing by non-residents for a small fee.

Main Features:
  • Searching of OverDrive, 3M, Freading, OneClickdigital, Open Library and Amazon powered lending libraries for selected books from the calibre library.
  • Detection of books that can be recommended for library acquisition or purchased by the user.
  • Detection of books by known authors that are missing from the calibre library.
  • Detection of books that are missing from the calibre library using topic keywords.
  • Creating links from calibre books to web pages from where they can be borrowed, recommended or purchased.
  • Selecting books based on the links.
  • Display of links in the Id section of the book details panel or the plugin menu.
  • Unlinking of books on demand.
  • Configuration of lending libraries and search parameters.
  • Help display with additional information.

Version History:
Version 1.10.2 - 12 Mar 2014
Handle change made by Overdrive to search results page format.

Version 1.10.1 - 05 Mar 2014
Bug fixes for Amazon support.

Performance improvements.

Version 1.10.0 - 11 Feb 2014
Support additional provider, Amazon Kindle Owners' Lending Library, for US Amazon Prime members. Can search for books that can be borrowed or purchased from Amazon. Can update the 'amazon' book identifier.

Ability to configure author name variants to improve search and match accuracy.

Preserve the dialog box size and position, column sizes and sort order for Manage discovered books.

Show links for recommendable (!) and purchasable ($) books in the discovered books dialog.

Simpler book matching algorithm, eliminating the match confidence configuration parameter.

Faster book matching and handling of discovered books.

Rename associated metadata plugin from "Overdrive Link Helper" to "Overdrive Link".

Miscellaneous bug fixes.

Version 1.9.0 - 24 Dec 2013
Support additional lending library service providers OneClickdigital and Open Library.

Discovery of books by searching using keywords. Useful for finding books about a particular topic regardless of the author.

Remember the size and position of the search results dialog box and display result details immediately without the need to click the Show Details button. (Requires calibre version 1.17 or later.)

Support old-style Overdrive web sites, such as the Boston Public Library, by using This is slower and less accurate than the algorithm used for new-style library sites.

Use to find author names for books in cases where Freading returns none.

Reduce likelihood of incorrectly matching words in titles that sound similar.

Version 1.8.0 - 06 Nov 2013
In addition to Overdrive, supports lending library providers 3M Cloud Library and Freading.

Reverted back to having 'Search for books by selected authors' as a menu choice instead of a configuration option.

After searching to discover new books by selected authors, discovered books are proceeded by '*' in the details and the confirmation dialog now allows the discovered book results to be discarded by choosing "Yes (without discovered)".

Improve searching for anthologies.

Prevent Roman numbers in titles from matching similar numerals.

Unlink was removing links for disabled libraries, which should remain.

Version 1.7.1 - 26 Oct 2013
Fix bugs searching authors with multiple initials or apostrophes in names

Fix error when updating discovered books: NameError: global name 'add_olinks' is not defined

Fix occasional error with previously linked books: ValueError: Olink crid must be a UUID

Reduce visible HTML tags in job details when running as a ParallelJob

Version 1.7.0 - 24 Oct 2013
Searching for books is now done using the individual Overdrive library websites instead of This is faster and produces more complete search results.

Added the search configuration option "Check for books that can be recommended for acquisition (slow)". This causes each subsequent search to perform an additional check for books recommendable for acquisition by a library, but not currently available in the library's collection. The 'odrid' book identifier has been added to store links to these books at Overdrive libraries. Selecting any of the recommendable books that have been linked by a search will enable the menu choice of "Recommend book to libraryname", which will open a web browser to the page that the user can use to issue a recommendation for the library to acquire the book.

Replaced the "Search Overdrive for books by selected authors" menu item and "Save discovered unavailable books" configuration option with the new search configuration option, "Discover more books by authors of selected books". During search, this will save information about any newly discovered books by the authors of the selected books that are not currently present in calibre. The menu choice to manage this list has been renamed from "Manage Search-by-authors results" to "Manage discovered books".

In search results the links to available books in the library collection are displayed as "@libraryname" and links to books that can be recommended for acquisition are displayed as "!libraryname".

The submenu choices of "Select previously linked books" have been changed. "Select all previously linked books" is now "Select all available books". There is a new section with "Select all recommendable books" and select recommendable books at individual libraries. The recommendable books choices will not select books that are available from a library.

Renamed the configuration option "Allow multiple simultaneous jobs" to "Allow search jobs to run simultaneously".

Renamed the configuration option "Automatically select modified books" to "Mark changed books". This option will mark books that have been modified by the plugin, but will no longer cause a search for the marked books to be performed afterwards.

Eliminated the configuration options "Exclude books with tags matching" and "Proxy URL".

Version 1.6.0 - 18 Jun 2013
Handle parsing of recent change to Overdrive library websites

Option to split large searches into multiple jobs

Option to exclude books from search based on tags

Option to change search language, defaults to English

Option to save discovered, but unavailable, books to be excluded from future searches

Version 1.5.0 - 14 Mar 2013
"Discard Existing" changed to "Update Existing" in the "Manage Search-by-authors results" dialog (Updates Overdrive links of corresponding calibre books that were manually added subsequent to a search.)

Optional configuration of a SOCKS proxy to be used when searching Overdrive

More frequent updates to search job status and progress

Version 1.4.0 - 13 Feb 2013
Support Overdrive library consortia that require a branch to be selected during sign in

Fix exception when changing the priority of a newly configured Overdrive library

Version 1.3.2 - 15 Jan 2013
Fix incorrect handling of authors in last,first format in some cases

Find book matches by including partial title when a search by only author exceeds the search limit

Version 1.3.1 - 06 Jan 2013
Fix exception when attempting to configure a new library

Version 1.3.0 - 29 Dec 2012
Optional sign in with user's credentials to detect additional books available through Overdrive Advantage

Handle further changes in the Overdrive website redesign

Extend timeouts for slow responding websites

Version 1.2.2 - 06 Dec 2012
Handle changes at Brooklyn Public Library website

Additional default sample libraries

Version 1.2.1 - 20 Sep 2012
Bug fix for occasional error in menu display

Version 1.2.0 - 19 Sep 2012
Generate the menu actions ahead of time for compatibility with keyboard shortcuts and the Favourites Menu plugin.

Show both regular search and search for other available books by author in the plugin menu.

Performance improvements in 'Manage Search-by-author results' dialog.

Version 1.1.0 - 06 Sep 2012
Added searching by author for available Overdrive books that are missing from the calibre library.

Improvements to the fuzzy matching algorithm for titles and authors.

Reorganization of configuration options.

Reorganization of search results report.

Version 1.0.2 - 14 Aug 2012
Bug fix. (Prevent possible crash!)

Version 1.0.1 - 14 Aug 2012
Bug fix. (object has no attribute 'ids')

Version 1.0.0 - 14 Aug 2012
Initial release.

Special Notes:
  • Requires calibre version 0.8.61 or later.

Installation Notes:
  • Download the attached zip file, install the plugin and restart calibre as described in the Introduction to plugins thread.
  • Select Customize plugin from the plugin menu (or via Preferences -> Plugins).

Usage Details:

Library Configuration

Library and other configuration options can be accessed using the Customize plugin menu choice.

The plugin supports multiple lending libraries. Individual libraries and their relative priorities are set in the plugin's configuration. Each library is identified by a short, unique name (chosen by the user), its service provider (OverDrive, 3M, Freading, OneClickdigital, Open Library or Amazon Prime) and a library-id. Configured libraries will only be used for searching and unlinking if they are enabled in the configuration by checking the first column.

The default configuration contains some sample libraries that can be enabled for searching. Additional libraries can be added as needed using the (+) button and existing libraries can be removed using the (-) button.


OverDrive is the largest provider of e-book lending library services. Books are available in EPUB and PDF formats via Adobe Digital Editions and Kindle formats via Amazon. Audiobooks are also available. Some OverDrive libraries allow recommendation of books for future acquisition.

You can find libraries supported by OverDrive by selecting the Library Search tab at For OverDrive powered libraries the library-id is the host name of the library web site (e.g.: for the OverDrive site of the Free Library of Philadelphia). This can be found by examining the browser address bar after surfing to the library.

Optional User Credentials (OverDrive Only)

OverDrive Advantage allows individual lending libraries that are members of a consortium with a shared collection to have additional titles that are only available when their patrons are signed in. The plugin configuration has optional fields for the user's credentials for each lending library: branch ID number, library card number and PIN. Entering this data is not required and will only be useful if your lending library has OverDrive Advantage titles.

If you choose to configure your library credentials in the plugin, then a library card number is required. Some, but not all, libraries also require entry of a branch ID and/or PIN during sign in.

If your library normally prompts for the selection of a specific branch during sign in, the corresponding branch ID number will need to be entered as part of the configuration. This number can sometimes be found by observing the URLs being accessed during a manual sign in to the library. Look for something in the form of: https:/

As an alternative, you can enter your library card and PIN in the plugin configuration, but leave the branch ID field blank, check the first column to enable the library, and then perform a search for any book. The sign in process will fail, but the log of the search should contain a list of valid branches for the consortium along with their corresponding branch ID numbers.

Some libraries do not require a PIN or additional data field beyond the library card number. In those cases leave the PIN field blank in the configuration.

3M Cloud Library

Some lending libraries use 3M Cloud Library in addition to, or instead of, OverDrive. Books are available in EPUB and PDF formats via an application compatible with Adobe Digital Editions. 3M supports recommendation of books for future acquisition.

You can find libraries supported by 3M by using Lookup your library at The library-id can be found by going to the library web site and examining the browser address bar for the portion of the URL following /library/. For the Brooklyn Public Library the web site is and so the library-id is bpl.


Freading provides access to many older titles. Books are available in EPUB and PDF formats via Adobe Digital Editions.

Find libraries using The library-id can be found by inspecting the host name in the browser address bar for the portion preceding For the Free Library of Philadelphia the Freading web site is and so the library-id is freelibrary.


OneClickdigital provides access to audiobooks and a small selection of e-books. Audiobooks are playable using a proprietary app. E-books are in EPUB format using Adobe Digital Editions DRM. The library-id can be found by inspecting the host name in the browser address bar for the portion preceding For the Austin (TX) Public Library the OneClickdigital web site is and so the library-id is austinpublictx.

Open Library

Open Library provides access to a very large collection of books. Books are available for borrowing in EPUB and PDF formats via Adobe Digital Editions. The PDFs contain scanned page images from print books and the EPUBs are generally of low quality with many OCR errors.

There is a small collection of public domain books available to anyone, called the Lending Library. There is also a much larger collection of books available to patrons of specific libraries, called In Library. Participating libraries can be found at https:/

The default is to any match books in the Lending Library or In Library collections. This can be changed by setting the Branch-id field to a list of collection names separated by spaces. Allowed collection names are: lendinglibrary, inlibrary and printdisabled. (The last contains accessible books for the disabled.) The library-id should be left blank.

Amazon (Prime)

The Amazon Kindle Owners' Lending Library is available to Amazon Prime members and allows borrowing of one book per month from a limited selection on a registered kindle device.

The general configuration option Set amazon identifiers when links to Amazon Kindle editions are added causes the amazon book identifier to be updated to point to kindle editions discovered during search.

Currently only the US Amazon store at is supported. The library-id should be left blank.

Searching for Books

To search for books at configured libraries first highlight the desired book entries within calibre and the choose Search for selected books from the plugin's menu. Searches can take a long time and so are done as jobs. After the search completes, a summary of results is shown. If accepted by the user, identifiers are added to the calibre book metadata for each match found to provide a link back to the lending library web page for that book. These links can be later used to open that web page, either through the plugin's menu or the book details panel.

Only one link per book will be shown under Ids: in the book's details, corresponding to the highest priority library (first in configuration) from which the book is available. A plus sign after the library name indicates that the book is also available from other lending libraries (or in other editions) and the additional links can be found in the plugin menu as Borrow book at libraryname.

Author Name Variants

The plugin searches for matching books using the primary (first) author of the selected calibre books. Searches are done multiple times with variants of the author's name to improve results, e.g., replacing middle names with initials. This usually works well, but can produce extraneous results for common author names and can miss results for pseudonyms and unusual name variants.

In order to provide more control over author name searching and matching the plugin configuration has a place for optional Author name variants. These are entered one author per line with the author name as it appears in your calibre library first and any variants on the name to be used for searching following, separated by '&' characters. For example: Stephen King & Richard Bachman

If only a single name is entered then that only that name will be used in searching and no variants will be generated automatically. For example, entering just John Joseph Adams will cause searches for books by that author to exclude books by John Adams or John J. Adams.

Placing an author name in square brackets will prevent searches using that name, even if books by that author are selected for searching. For example: [Deepak Chopra]

For a match to occur between a calibre book and a library book the first author listed for one must appear in the author list of the other. This rule is relaxed for anthologies, where any match between listed authors is accepted since the listing of authors for anthologies at library providers is often incomplete. Books are considered to be anthologies if they have more than two authors in calibre or have a tag containing the word anthology.

Title Variants

When matching book titles, text in parentheses or following a colon is optional and a vertical bar ('|') can be used to separate alternate titles for the same book. Some examples of usage:

A book title sometimes prefixed with the series name will match either way if entered with parenthesis: (High Druid of Shannara) Jarka Ruus

A book that was published under multiple titles can match either one: The Barbie Murders (And Other Stories) | Picnic On Nearside

A book with an optional subtitle with match with or without it: The Ancestor's Tale: A Pilgrimage to the Dawn of Life

Discovering Books Missing from calibre

Selecting the plugin menu choice Search for books by selected authors will cause the search to look for the specific books selected and to also save a list of books by the author(s) of the selected books that are found at enabled lending libraries, but not present in the user's calibre library.

Selecting the plugin menu choice Discover books by keyword will cause the search to look for books that match the selected keywords(s) in their title (or description for some providers), but are not present in the user's calibre library. Keywords are configured using Customize plugin, one set of keywords per line. The discover-by-keyword menu choice will not appear unless at least one set of keywords is configured.

After search completion, these results can be accessed using the Manage discovered books choice from the plugin's menu. A table of books is presented and the user can choose the action to be taken for each: add to the calibre library as an "empty" book with minimal metadata (author, title, series, publisher, publication date, isbn, odid, odrid and odpid), ignore so that undesirable books do not appear in subsequent searches, and discard which will eliminate the book from the search results, but allows it to appear again in subsequent searches.

Books previously marked to be ignored can be displayed again using the Show Ignored button. The Update Existing button can be used to check if any of the listed books were recently added to calibre and if so mark them to be updated in calibre (by adding links and missing metadata) and then discarded from the list of discovered books.

Recommending Unavailable Books for Library Acquisition

The search configuration option Check for books that can be recommended for acquisition (slow) will cause subsequent searches to do an additional check to find books not currently in the library's collection, but potentially available to recommend for acquisition. (Some books may be detected that are not truly available for library acquisition due to restrictions by the publisher, such as geographic restrictions.)

The Select previously linked books / Select all recommendable books plugin menu item shows books not currently available in any of the configured lending libraries. When selected, these books will have a plugin menu choice of Recommend book to libraryname which opens a web browser to the page from which the user can issue a recommendation for the library to acquire that book.

Some libraries do not support book recommendations.

Searching for Books Available for Purchase

The search configuration option Check for books that can be purchased (slow) will cause subsequent searches to do an additional check to find books available for purchase by configured library providers.

The Select previously linked books / Select all purchasable books plugin menu item shows books linked by this search. When selected, these books will have a plugin menu choice of Purchase book from libraryname which opens a web browser to the page from which the user can purchase that book.

This is currently only available for Amazon US and Amazon (Prime) must be configured as a search provider. It can be used to quickly determine which calibre book entries are available in kindle format via Amazon.

Viewing Links for Available Books as a Custom Column

You can create a custom column to show books found to be available from an e-book lending library. Choose Preferences -> Add your own columns -> Add custom column. Enter a Lookup name of has_odid and a Column heading of OD (or any other description you desire.) The Column type should be Column built from other columns, select Show checkmarks and Sort/search column by should be set to Yes/No. Enter the following in the Template field: {identifiers:contains(odid:,Yes,)}

You will need to restart calibre for the change to take effect.

Removing Links to Lending Libraries

Removing a lending library from the plugin's configuration has no effect on books that have already been linked to that library. The only noticeable difference is that the links to an unconfigured library will be shown with a default name (based on the provider and library-id) rather than the previously configured name for the library. So selecting a book and then clicking the plugin's icon will always show the links established for that book, whether or not the lending library still exists in the configuration.

You can remove links by either deleting the odid, odrid and odpid identifiers under Ids in the Edit Metadata dialog for the book or by selecting Unlink selected book from the plugin's menu. (The unlink function only removes links for unconfigured libraries and enabled libraries. It leaves unchanged any links to libraries that are configured, but not marked as enabled.)

Restore Default Configuration

The following steps can be used to restore the default configuration for the plugin: From the main Calibre screen select: Preferences -> Miscellaneous -> Open calibre configuration directory. Navigate to the plugins subdirectory and delete the file Overdrive Link.json.

Implementation Notes:

If a library card number is entered in the configuration for an OverDrive library, the plugin will sign in with the user's credentials before checking book availability so that OverDrive Advantage titles can be found.

The plugin searches each configured library website for matching e-books using variants of the name of the primary (first) author of the selected calibre books. The search results are then matched against the selected books and a link is created for each matched book. Fuzzy matching is used to detect matches even when there are minor differences. This may sometimes result in missed matches or association of the wrong books.

If the configuration option to search for recommendable books or to search for purchasable books has been selected then an additional search to find those books is done, increasing search time.

If the menu choice to save discovered books was used then any search results that do not match books already present in the user's calibre library are retained for examination by the user.

Links to books discovered at libraries are stored in calibre as identifier metadata. The identifier for a book available in a library's collection is odid, the identifier for a book recommendable for acquisition by a library is odrid and the identifier for a book that can be purchased by the user is odpid. The format of these is book_id@provider_id/library_id where book_id is the identifier used by the provider to identify an edition of a book (e.g.: 36 character content reserve identifier for OverDrive), provider_id identifies the provider of library services (none for OverDrive, '3m/' for 3M Cloud Library or 'fr/' for Freading, 'ocd/' for OneClickdigital, 'ol/' for Open Library and 'ak/' for Amazon) and library_id identifies the specific library.

If a book is available in multiple editions or from multiple libraries there will be additional links, separated by ampersands. *For example: 6OTc4MDQ4NjExMDUzMDpl@fr/ocls&dot8az9@3m/bpl

A search for identifiers:"=odid:" can be done to find all books in calibre that are available at any lending library. A search for identifiers:" "*will show only books recommendable at that specific library. Commonly used searches can be performed through the plugin's menu under Select previously linked books.

The list of discovered books is stored in a hidden part of the calibre library database. This data can be examined in the file metadata_db_prefs_backup.json in the calibre library folder.

The plugin contains an embedded metadata plugin that provides the clickable links in the book details panel for available books. It can be disabled in the main plugin's configuration if this feature is not desired.

Attached Files
File Type: zip Overdrive (271.4 KB, 2320 views)

Last edited by jhowell; 03-12-2014 at 01:20 PM. Reason: Version 1.10.2
jhowell is offline   Reply With Quote