Goodreads Sync
The Goodreads Sync 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:
- Add books from calibre to a shelf in Goodreads, optionally applying actions such as setting custom column values, uploading a rating, date read or review columns.
- Sync the contents of Goodreads shelves to books in calibre. Apply actions such as adding tags or setting values in custom columns or downloading rating/date read/review text.
- View your shelves or the details of a book on the Goodreads website from calibre
- Build a tags column on your books based on which of your Goodreads shelves they are on. Alternatively add books to Goodreads shelves based on a tags column.
- Add or remove books to one or more Goodreads shelves from a selection within Calibre
- Syncing the contents from one or more Goodreads shelves into Calibre, performing customisable actions for each shelf
- Configure actions to be performed for when adding books to a shelf or syncing from Goodreads, such as updating tags, custom columns.
- You can also synchronise your rating, date read and or review text custom column with your Goodreads review.
- Ability to download tags for your books based on the shelves they are on. You can customise which Calibre tags if any each shelf name will map to and use a custom genre column instead of tags if desired.
- Ability to upload to shelves for your books based on the tags they have been given. Applies the to the same Calibre column and shelf mappings as for the download tags feature above.
- Link your Calibre books to a Goodreads equivalent giving you right-click access to reviews or other information for that book
- Ability to switch editions for a linked Goodreads book
- Ability to create Empty Books in Calibre for books you sync from a Goodreads shelf
- Optionally update the ISBN in Calibre to match the edition on your Goodreads shelf
- Supports multiple Goodreads user accounts if required for users sharing a single operating system account
- Help file web page available from the configuration dialog or plugin menu
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.
Access the configuration dialog via:
- Preferences -> Plugins -> User interface action -> Goodreads -> Customize plugin
- Goodreads -> Customize plugin...
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.
| Column | Description |
|---|---|
| Active | 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. |
| Shelf Name | 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. |
| Count | 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. |
| Shelf Add Actions | 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. |
| Sync Actions | 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.
| Option | Description |
|---|---|
| When linking to Goodreads | Options updating ISBN with the Goodreads value whenever a calibre book is linked using this plugin.Never modify the calibre ISBN Replace calibre ISBN only if none present Always overwrite calibre ISBN value |
| Display 'Add to shelf' | For hiding plugin submenus you do not use. |
| Display 'Remove from shelf' | For hiding plugin submenus you do not use. |
| Display 'Update reading progress' | For hiding plugin submenus you do not use. |
| Display 'Sync from shelf' | For hiding plugin submenus you do not use. |
| Display 'View shelf' | For hiding plugin submenus you do not use. |
| Reading progress is % read | If checked, the progress column is a % read. If unchecked it is a page number. |
| Empty books author as LN, FN | The Goodreads website always returns authors in FN LN format. On the Sync from shelf dialog you can create empty books in calibre for unlinked books on your Goodreads shelf. Check this option to use LN, FN author format for those empty books. |
| Column | Description |
|---|---|
| Tags | Choose the calibre column to contain tags metadata. Used by the Download tags from shelves and Upload tags as shelves menu options. |
| Rating | Choose the calibre column to contain goodreads rating metadata. For use if synchronising a rating column to/from Goodreads within this plugin. |
| Date read | Choose the calibre column to contain last date read metadata. |
| Review text | Choose the calibre column to contain review text metadata. |
| Reading progress | Choose the calibre column to contain % read or last page read. |
For each shelf (though most likely this would only apply to your read shelf or similar) you can specify whether to:
- Upload your calibre rating, date read and/or review text custom column to Goodreads when adding a book to a shelf. You will have the opportunity to edit the rating and date read columns from within the Add to shelf... dialog.
- Overwrite your calibre rating, date read and/or review text custom column with the Goodreads value when syncing from that shelf.
To enable this functionality you must do three things:
- You must have created your custom columns in calibre, using Preferences -> Add your own columns, if you are not storing the Goodreads data values in one of the standard calibre columns (which you cannot do for date read!).
- Note that you will probably want a
Reviewcustom column to be of typeCommentsto allow multi-line html text (though you can only comfortably edit such text in the Edit Metadata dialog). - It is permissible to use a column of type
Textthough you may find editing/viewing in calibre more awkward albeit convenient for very short reviews!
- Note that you will probably want a
- Choose the appropriate column names in the Customize plugin... dialog for
Ratingcolumn,Date readcolumn and/orReview textcolumn in the Synchronisable Custom Columns section. - On one or more shelves, edit the Shelf Add or Sync actions (as appropriate) to tick the relevant checkbox(s) specifying
rating,date readand/orreview textshould be synced.
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.
This feature assumes you use a calibre custom column to store your reading progress for a book. That column could either be a % read or current page # for a book. When you choose the Update reading progress... menu option, you are presented with a dialog that allows you to automatically place the selected book(s) on either the currently-reading or read shelf based on your progress column.
In order to get this feature to work you must:
- Create a custom column (of type integer) to hold your progress
- Use the Customize... menu dialog to choose the custom column name in the
Reading progress columndropdown - Configure the
Reading progress is percent readcheckbox as appropriate for the values you will put in this column. - Optionally you can also configure a
Review text columnif you are wanting to have that uploaded to Goodreads at the same time.
Note that if you do not have your reading progress column configured correctly, or if you have no value in that column for the selected book then a value of -1 will show in the Update reading progress dialog in the progress column.
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 tags 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:
- Place tag values on your books either in the
tagscolumn or in a custom column representing the value you want mirrored as a Goodreads shelf. e.g. placing aScience Fictiontag on your relevant books. - Create the matching shelf on Goodreads, either using their website or clicking on the button located on the plugin configuration dialog. e.g. create a shelf called
science-fiction. - Use the Customize plugin dialog to specify which column to read the tags from or custom column name. In addition ensure you have a mapping in place for the (in this example)
science-fictionshelf with aScience Fictiontag - Ensure your books have been linked to Goodreads, either from being previously added to a shelf (or synced) or using the Link to Goodreads option.
- Select the books and use the Linked Book -> Upload tags as shelves menu option.
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.
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.
If you want to add a display column in calibre for the Goodreads Id, do the following:
- Preferences -> Interface -> Add your own columns
- Click on
+button then set at least the following
| Field | Value | Comments |
|---|---|---|
| Lookup name: | gr | Suggested value only, you can customise |
| Column heading: | Goodreads | Suggested value only, you can customise |
| Column type: | Column built from other columns |
Mandatory |
| Template: | {identifiers:select(goodreads)} |
Mandatory |
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 for you.
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 the Search Goodreads button to do a search on title/author 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.
Note you also have the ability to Switch Editions to choose a specifc edition of this book that you would like to link to.
Another 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 a 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.
- Goodreads have a limitation on the data they can expose via their search API. So when you choose a menu option to search for a Goodreads book to link to for a title/author search you will sometimes have no results coming back, yet the book will be found when you click on the button to search via the website.
- Historically, Goodreads have had a bug in their API which prevents this plugin from reading the contents of a shelf if it contains some particular books. I have raised this as an issue on the Goodreads bug forums here and their subsequent fix appears to be working. Any books which cause this error that are on your shelf will not appear for display with this plugin. This symptom can also happen if Goodreads happen to have their website down for maintenance.
- If your title/author/isbn data in calibre is incorrect at the time you link, and you later correct it in calibre, you will still be linked to the “wrong” book in Goodreads. If this situation occurs, choose the Goodreads -> Link to Goodreads menu option to create a new link for the correct book once you have edited your metadata.
- This plugin does not support per library configuration for custom columns used by this plugin. So if you have multiple libraries that you sync to goodreads with, they must use the same custom column names in each library.
If you enjoy my calibre plugins or extensions, please feel free to show your appreciation!
