Skip to content
Ten thousand books, six million ratings
Jupyter Notebook
Branch: master
Clone or download

Latest commit

Latest commit 6dd165b Oct 1, 2018


Type Name Latest commit message Commit time
Failed to load latest commit information.
books_xml fixed books_xml archive 📙 Nov 16, 2017
contrib Create Oct 1, 2018
samples CSV samples, license Sep 13, 2017
.gitignore Initial commit 📚 Sep 13, 2017
LICENSE . Sep 13, 2017 fixed books_xml archive 📙 Nov 16, 2017 . Sep 29, 2017
book_tags.csv Initial commit 📚 Sep 13, 2017
books.csv Initial commit 📚 Sep 13, 2017
quick_look.ipynb notebook, zipped files, thanks 📓 Sep 29, 2017
ratings.csv Initial commit 📚 Sep 13, 2017
tags.csv Initial commit 📚 Sep 13, 2017
to_read.csv Initial commit 📚 Sep 13, 2017


This dataset contains six million ratings for ten thousand most popular (with most ratings) books. There are also:

  • books marked to read by the users
  • book metadata (author, year, etc.)
  • tags/shelves/genres


Some of these files are quite large, so GitHub won't show their contents online. See samples/ for smaller CSV snippets.

Open the notebook for a quick look at the data. Download individual zipped files from releases.

The dataset is accessible from Spotlight, recommender software based on PyTorch.


ratings.csv contains ratings sorted by time. It is 69MB and looks like that:


Ratings go from one to five. Both book IDs and user IDs are contiguous. For books, they are 1-10000, for users, 1-53424.

to_read.csv provides IDs of the books marked "to read" by each user, as user_id,book_id pairs, sorted by time. There are close to a million pairs.

books.csv has metadata for each book (goodreads IDs, authors, title, average rating, etc.). The metadata have been extracted from goodreads XML files, available in books_xml.


book_tags.csv contains tags/shelves/genres assigned by users to books. Tags in this file are represented by their IDs. They are sorted by goodreads_book_id ascending and count descending.

In raw XML files, tags look like this:

	<shelf name="science-fiction" count="833"/>
	<shelf name="fantasy" count="543"/>
	<shelf name="sci-fi" count="542"/>
	<shelf name="for-fun" count="8"/>
	<shelf name="all-time-favorites" count="8"/>
	<shelf name="science-fiction-and-fantasy" count="7"/>	

Here, each tag/shelf is given an ID. tags.csv translates tag IDs to names.

goodreads IDs

Each book may have many editions. goodreads_book_id and best_book_id generally point to the most popular edition of a given book, while goodreads work_id refers to the book in the abstract sense.

You can use the goodreads book and work IDs to create URLs as follows:

Note that book_id in ratings.csv and to_read.csv maps to work_id, not to goodreads_book_id, meaning that ratings for different editions are aggregated.

You can’t perform that action at this time.