Setting your Goodreads Shelf Add or Sync Actions
Additional Configuration Options
Synchronise Rating, Date Read and/or Review Text Columns
Download Tags from Goodreads Shelves
Upload Tags as Goodreads Shelves
Linking calibre Books to Goodreads Books
Linking using the Goodreads metadata download plugin
Linking using ‘Add to Shelf’ / ‘Remove from Shelf’
Linking using ‘Link with Goodreads’
Linking using ‘Sync from Shelf’
Linking using ‘Add empty book’
Important Note About Bulk Operations
The Goodreads plugin was designed to allow integration between the books that you manage in calibre and your reading list shelves that you maintain with your Goodreads.com account.
With this plugin you can:
Your first step if you have not already will be to setup an account with Goodreads.com. This plugin will work with multiple Goodreads accounts, so if you happen to share your PC with other users (and do not each have a separate logon) this is able to be supported by the plugin.
Within the Goodreads plugin configuration dialog, you will initially be prompted for a name for your first account. If you have only a single account to setup, the name is irrelevant. If you have multiple, the name will appear in the submenus for certain actions.
Next, click on the Authorize Plugin with Goodreads button. This will launch a web browser allowing you to login to Goodreads.com with the user account you want associated with the calibre profile you just selected. Once you are logged in, click the Allow access button on the web page displayed. You can now close your web browser.
Finally back in calibre confirm the dialog question being asked. If everything has been successful, a list of your Goodreads shelves will be displayed.
The list of shelves and book counts displayed on the configuration dialog reflect those available the last time the list was refreshed. To update this list, click on the Refresh button located to the right. This will update the counts of books on each shelf, and add/remove any custom shelves you have created in Goodreads.
Note that refreshing your shelves list will not result in you losing any sync actions you have created.
The Active column checkbox for each shelf reflects whether it will appear in your menus. You may decide for example that your ‘currently-reading’ shelf requires no synchronisation or management from calibre.
The Shelf Name column includes an icon for each shelf. The red shelf icons indicate that a shelf is ‘exclusive’ according to how it was setup on Goodreads. Exclusive shelves mean that the book can only appear on one of your shelves at a time. So adding a book to your ‘currently-reading’ shelf and then adding it to your ‘read’ shelf will remove it from the ‘currently-reading’ shelf as they are exclusive shelves by default.
The Count* column is purely informational and is not kept up to date by any actions you perform in calibre. You must click the Refresh button if you wish to view the latest count information.
The Shelf Add Actions column reflects any rules you have setup in the plugin for use with the Add to shelf menu option. When this menu option is chosen, any actions which you have specified will be applied for each book in calibre added to the shelf, such as adding a value to a custom column or a tag. To edit these actions, either right-click, or click the Edit Sync Actions button to the right.
The Sync Actions column reflects any rules you have setup in the plugin for use with the Sync from shelf menu option. When this menu option is chosen, any actions which you have specified will be applied for each book in calibre that matches a book on that Goodreads shelf. To edit these actions, either right-click, or click the Edit Sync Actions button to the right.
You can multiple select shelves before clicking the edit button to configure all selected shelves to have the same actions.
Selecting a shelf in the configuration dialog and choosing Edit Shelf Add Actions or Edit Sync Actions will present a new dialog listing any actions that you wish to apply for books being added or synced from that shelf respectively.
For instance, you might setup a rule to set a #read custom column in calibre to Y when a book is added to your read shelf in Goodreads. There are also checkboxes available for synchronising your calibre rating and/or date read columns (see below). You might specify an additional rule to remove a ToRead tag from that book. The flexibility is there for as many actions as you wish. Note that currently this plugin only supports actions for text, comments, datetime and yes/no custom columns, along with the tags column.
Use the Add and Remove buttons (+/-) to add/remove actions to your list.
From the plugin configuration dialog you can also specify:
For each shelf (though most likely this would only apply to your read shelf or similar) you can specify whether to:
To enable this functionality you must do three things:
When you select one or more books in calibre and choose the Add to shelf... menu option, the dialog that appears allows you to choose one or more Goodreads shelves to add your book to. You can filter the list of shelves to just those marked as Active according to how you enabled them on the Configure plugin dialog. You cannot select multiple exclusive shelves, because by their nature it is not possible for a book to appear on more than one exclusive shelf at once.
A Status column displays whether each book you have selected is ready to be added to the shelf by virtue of being linked via a Goodreads Id (see more on Linking books to Goodreads below). Only books that have links can be added to a shelf when you click on the Add to Shelf button. If a book does not have a link, but does have an ISBN, the plugin will have attempted to link automatically for you.
If any of the shelve(s) you have selected to add the book(s) to have rating or date read column checkboxes enabled (as per above) then you can also directly edit those values in this dialog. A date read column will default to today.
For all books that are linked, once you click on the Add to Shelf button they will be added to the selected shelves (regardless of whether the books are already on them). If enabled the rating and/or date read column values for those books will be assigned to your review for those books on Goodreads. Finally, the new rating/date read values if changed will be written to the calibre database for those added books.
Note that books that were not linked are effectively ignored – they are not uploaded to Goodreads, and any changes to rating/date read columns are discarded.
When you select the Sync from shelf... menu option, you will be presented with a list of one or more shelves to sync from. Note that for performance reasons you should limit your sync actions to the minimum shelves and shelf size possible – see the ‘Important note about bulk operations’ later in this document.
Only shelves that have some kind of sync action specified can be synchronised from. So in the Configure plugin... dialog for this plugin, for each shelf you want to sync from you must have used the Edit sync actions option to either specify actions to be applied to calibre column(s), or have configured the rating and/or date read columns to be synced from.
Once you have selected a shelf and clicked ok, you will be displayed a dialog showing all of the book(s) on those Goodreads shelve(s). There are additional columns showing the calibre book information from the linked books – see the Linking books section for further details. Note that if you have books on your Goodreads shelf that have no equivalent in calibre you have the option of creating an empty book via the right-click menu, to allow them to be synced.
The bottom part of this dialog reminds you what action(s) will take place when you complete the sync operation for all of the books that are linked.
Clicking on the Sync Now button will for all linked books apply the specified actions to your columns, as well as updating the rating and date read columns if configured.
An alternate way of tagging your books is to use the Download tags from shelves menu option. Say for instance you have a series of shelves representing genres like science-fiction, romance, adventure etc. Rather than setting up a sync action for each shelf to set the appropriate tag for the books on it, you can instead select your linked books and have tags applied based on the shelves they are on. This feature is only available for books you have linked to Goodreads that are on one or more of your shelves.
It is quite possible that there is not a 1:1 mapping between your Goodreads shelf names and your desired calibre tag names. Perhaps some shelves your books are on you may not want to map tags to such as currently-reading. The Configure plugin dialog allows you to edit the mappings for each shelf. Clear the tag field completely for any shelf you do not want to create a tag for. You can specify multiple calibre tags if you so wish – for instance a paranormal-romance shelf could map to tags of Paranormal, Romance.
Note that you can alternately specify a custom column as the target for your shelf mappings rather than using the main tags column. So you might set up a custom column #genre dedicated to your Genre and in the Configure plugin dialog choose this column to be the destination for your shelf mappings with the Tags column dropdown. You might also choose to setup your tags or custom column to be hierarchical for display in the tag browser. For more information on hierarchical tags see this thread on the calibre forums.
Note also that there is a difference in behaviour between choosing the target column to be the tags column versus it being a custom column. When it is a tags column, the plugin assumes it is not safe to erase all tags in that column when you use this feature (as tags are frequently used for other purposes). So it will always append new mapped values. The implication is that if you move a book between shelves and then use this download feature again, it will not erase whatever previously mapped tag value it had. So you will have to do this manually.
If however you set your target column to be a custom column such as a #genre column, then the plugin assumes that column is dedicated for this purpose. So it will always erase values from the custom column and overwrite with the new shelf values each time you use this feature. Hence a custom column is the best choice for use with this feature.
It is possible to add books to shelves in Goodreads based on the tags you have applied to them. This feature uses the exact same mappings and column specified for the Download tags from shelves option above. This may offer a more convenient alternative to repeatedly filtering your search results to just select the rows of a specific genre to then add to your genre specific shelf using the Add to shelf menu option.
You cannot however use this feature as a way to “clean your calibre tags”. If you specify multiple calibre tags for a Goodreads shelf in your mappings, you are in effect saying that a book must have all those tags for it to be assigned to that shelf. So a paranormal-romance shelf with calibre tags of Paranormal, Romance will only have books added to it with both those tags present. A book with just the Romance tag would not – you are instead able to map that separately to a romance shelf in Goodreads.
To use this feature, you should perform the following steps:
The biggest challenge for this plugin is identifying the matching book between the record stored in calibre and that stored in Goodreads. While many books have an ISBN which can be useful, not all do, or it may not as yet have been populated in calibre. In addition, many of the programming API calls that Goodreads supply rely on using their own Goodreads id.
The solution taken by this plugin is to enable storing the Goodreads id for a book in the calibre database. It is stored as an identifier called goodreads which you can see in the IDs field of the Edit Metadata dialog. A book linked to goodreads will also have a hyperlink called Goodreads appear in the book details panel on the right side of calibre for each linked book, allowing you to navigate directly to the Goodreads website page for that book.
It is also possible to display this identifier as a column in the GUI – see the first post of this plugin thread at the end of this help document.
Once a link is established either automatically or manually by yourself, you will not be prompted again for that book. Note that if you incorrectly linked a book such as it having the wrong title/author at the time there is no validation – it is your responsibility to re-link it. See the Known Issues section below for more information on this.
There is a metadata download plugin called Goodreads which you can use to download book metadata in the same way as the plugins that come with calibre such as Amazon. If you have used this plugin with a book, it will populate the goodreads identifier.
When you perform an action like Goodreads -> Add to shelf, the plugin first looks to see whether you have already linked the calibre book to a Goodreads one. If you have not, it will attempt to automatically match on ISBN if that is present on the calibre book.
If that fails, you will still have the opportunity via the preview dialog with Search Goodreads to do a search on title/author against Goodreads to find a matching book. In addition from that search results dialog you have the ability to launch a search using the Goodreads website. You can drag/drop a book URL back onto the results dialog for selection. If you cancel the action, the link will be discarded.
Should you wish, you might choose to do this “linking” as a separate workflow activity, such as after adding a new book to calibre. Choose the Goodreads -> Link with Goodreads menu option, which will perform the same checks indicated above of matching ISBN then title/author. You can identify which books have a Goodreads id set by whether the menu option of Goodreads -> View linked book is enabled when you right-click on that book.
A third approach to linking takes place when you choose Goodreads -> Sync from shelf. In this circumstance the search to establish links occurs in the opposite direction as your starting point is a list of Goodreads book on the shelf. calibre is queried to find any books matching the Goodreads id for each book from a previous link. If no match is found, calibre is queried for a matching ISBN to the Goodreads book.
If that fails, the user has the ability from the sync preview dialog using Search calibre to issue a search against calibre for a match on title and author. This performs a “fuzzy” search to increase the likelihood of finding a match in calibre, in case minor differences in punctuation, spacing or ordering of words like “A” and “The” differ. In the calibre search results dialog, you also have the ability to perform direct queries against calibre to find the book, in case the metadata is incorrect in your database such as misspelled words.
Of course it is possible that you have no matching book when you attempt to sync from a Goodreads shelf. For instance you sync with your read shelf in which contains paperbacks you do not have calibre records for. A right-click option of Add empty book is available from the sync preview dialog to handle this situation. Once you click Sync now a record for each book you have flagged with that action is created in calibre, linked to the corresponding Goodreads book and sync actions can be applied as per normal.
Goodreads have Terms & Conditions associated with their API that this plugin is dependent upon. The T&C place a very strict limit on the throughput of calls being made. The more successful this plugin is and the more users that perform actions like adding to shelves etc, the greater the risk of the plugin being banned.
If you ignore this warning the plugin will stop working for everyone (including you) and there is no workaround.
To discourage users from bulk operations using the plugin there is a limit of 50 selected rows for the actions of add to shelves/remove from shelves. If you have more books you wish to add in bulk to the Goodreads website, export them from calibre as a CSV catalog and upload to the Goodreads website. For more details see http://www.goodreads.com/review/import
Note also that adding many hundreds of books to a shelf and either syncing or add/removing to it from calibre using this plugin will be slow and also potentially cause issues. Every time you do actions with your shelves the entire contents of that shelf are read (200 books at a time). I cannot think of a genuine reason for having an enormous amount of books on a Goodreads shelf (apart from your “read” shelf which will grow over time). So do not for instance be tempted to put your entire collection of thousands of books on your to-read shelf from this plugin! Apart from running very slowly for you, the risk of all users being disabled becomes far higher.
If you do have genuine reasons for wanting a lot of books on your shelf and adding to it from calibre regularly, please post on the plugin thread and state what they are. I may need to make further changes to the plugin design to attempt to handle this scenario.
For any problems, issues or obtaining the latest version of this plugin, please refer to the calibre plugins forum for the thread related to this Goodreads Sync plugin.