Allow Reading Stats to filter stats by year

[Freso]

Feature Request

Problem / Opportunity

We currently have /stats which covers all books in the given “category”, e.g., https://openlibrary.org/people/freso/books/already-read/stats for all of my already-read books.

It would be neat to be able to narrow this down on a year and month basis, e.g., to see the stats for books I finished in March 2025.

Storygraph and Goodreads both have features similar to this; Goodreads has “Year in Books” (e.g., mine for 2024: https://www.goodreads.com/user/year_in_books/2024/4511032) and Storygraph has a more involved Stats page that allows you to see a yearly overview, a monthly one, or an all-time one: https://app.thestorygraph.com/stats/freso?year=2025

This would help incentivise patrons to keep their reading logs in Open Library, making them return to us more frequently to update their reading data and/or (re)view their stats. Which in turn would help us with more/better data on book activity which we use for measuring popularity etc.

This also adds into if we ever want to make the stats shareable (which would be a separate issue from this one!), since people in bookish community are more likely to want to share stats of what they read in the last month or year than what they've read of all time. What Open Library has compared to GR and SG with the author genders/sexes, nationalities, and birth countries is data that are not at all available in Goodreads or Storygraph, and would certainly be of interest esp. to book clubs, reading circles, etc. with a more social justice oriented mindset.

It would be solved once there is a way to narrow down the stats page (at least for already-read) by year and by month.

Proposal

https://openlibrary.org/people/freso/books/already-read/stats could have dropdowns or a calendar or other UI elements to allow users to select a specific year and possibly month.

I would also suggest that the resulting URLs should be hackable, like https://openlibrary.org/people/freso/books/already-read/stats/2025 and https://openlibrary.org/people/freso/books/already-read/stats/2025/03, to allow for intuitive “manual” construction and editing of URLs by the user.

Breakdown

Related files

Extend the readinglog_stats endpoint to support year

openlibrary/openlibrary/plugins/upstream/mybooks.py

Line 159 in 8edf95a

class readinglog_stats(delegate.page):

. Note the ReadingLog.get_works method already has an argument, year, which we can use. E.g. something like this:

class readinglog_stats(delegate.page):
    path = "/people/([^/]+)/books/(want-to-read|currently-reading|already-read)/stats(/\\d{4})?"

    def GET(self, username, key='want-to-read', year=None):
        ...

        if year:
            # Skip the '/'
            year = int(year[1:])

        readlog = ReadingLog(user=user)
        works = readlog.get_works(key, page=1, limit=2000, year=year).docs

Requirements Checklist

Checklist of requirements that need to be satisfied in order for this issue to be closed:

• Going to a reading stats with a year prefix should show reads filtered by year

Stakeholders

---

Instructions for Contributors

• Before creating a new branch or pushing up changes to a PR, please first run these commands to ensure your repository is up to date, as the pre-commit bot may add commits to your PRs upstream.

[cdrini]

Note limiting this to just year for now; supporting month would require changing a number of other methods.

[cdrini]

To get the UI, we'll need to:

Update openlibrary/templates/account/readinglog_stats.html to take in two new arguments, year and yearly_reads, and show the yearly dropper after the h1 ; something like:

    $if shelf_key == 'already-read' and yearly_reads:
        <div>
            $:render_template("books/year_breadcrumb_select", selected=year_filter or _("All Time"), url_prefix="%s/books/already-read/stats" % owner_key)
        </div>

We'll also need to update the year_breadcrumb_select to take in the yearly reads directly instead of a full mb, which will require a bit of massaging. But it's only used in one spot, so shouldn't be too difficult. Tackled it here: #10649

And the GET endpoint will need to pass these new arguments along as well, eg

        if year:
            # Skip the '/'
            year = int(year[1:])
            yearly_reads = BookshelvesEvents.get_user_yearly_read_counts(username)
        else:
            yearly_reads = None
        ...
       return render['account/readinglog_stats'](
            ...,
            year=year,
            yearly_reads=yearly_reads
        )