Goodreads API

Does Goodreads have a public API?

Not any more. Goodreads stopped issuing new developer keys on 8 December 2020 and says on its help site that it plans to retire the current version of its public API, supporting only existing active keys while it decides the future. A developer starting today cannot get a key. Integuru's Goodreads integration provides 18 verified actions over direct HTTP requests, authenticated with your own Goodreads account, covering book data and your own shelves.

| | Retired Goodreads developer API | Integuru for Goodreads | |---|---|---| | Access | No new keys since 8 December 2020 | Your own Goodreads login | | Covers | Existing keyholders only, pending retirement | Books, authors, series, genres, quotes, shelves, progress, friends | | Best for | Apps that obtained a key before 2021 | Reading apps and agents starting now |

What you can do with the Goodreads API

Look up a book. search_goodreads_books takes a title, author or ISBN as query and an optional limit, and returns book ids. get_goodreads_book takes the numeric book_id from a book URL and returns the record, including the work_id that groups every edition. From there, list_goodreads_book_editions and list_goodreads_book_quotes take the work_id, while list_goodreads_book_reviews (up to 40, which is all the book page carries) and list_goodreads_book_lists take the book_id.

Authors, series, genres and quotes. get_goodreads_author and list_goodreads_author_books take the numeric author_id from an author URL, the latter paged up to 100 with a sort field. get_goodreads_series pages a series by series_id. list_goodreads_genres filters genres by a query substring and returns slugs that list_goodreads_genre_books accepts, such as science-fiction. search_goodreads_quotes searches quotes by phrase, author or title.

Your shelves and progress. get_my_goodreads_profile returns the signed-in account, and get_goodreads_user, get_reading_progress, list_goodreads_shelf_books and list_friends all default to it when user_id is omitted. list_goodreads_shelf_books takes a shelf of read, to-read, currently-reading, a custom slug, or #ALL# for everything, with sort and a page_size up to 100. list_friends_activity pages the friends feed your account sees.

Shelving a book, rating it or updating progress are writes and are built on request through the Managed Service.

Who uses this

Reading apps that let a user connect Goodreads import list_goodreads_shelf_books with #ALL# on first sync and get_reading_progress on each refresh, and The StoryGraph connects through the same login-based model, so a reader who keeps both, or is moving from one to the other, sees one library. Book-recommendation assistants built on the AI agents pattern read the read shelf, pull candidates from list_goodreads_genre_books and check each with get_goodreads_book, and answer with titles the reader has not already logged. Publishers and authors track list_goodreads_book_reviews and list_goodreads_author_books for their own titles without a retired key.

Setup notes

Integuru authenticates against www.goodreads.com with the reader's own credentials and returns that account's shelves, progress and friends feed, plus the book, author and genre pages any signed-in reader can view. Ids are the numbers in Goodreads URLs; user_id also accepts the id-with-slug form such as 2632-marc and uses the numeric prefix. Read work_id from get_goodreads_book before calling the edition and quote actions.

Get started

Install the CLI and connect your Goodreads login:

npm install -g integuru

Or sign in at app.integuru.com and add Goodreads. To add shelving or progress updates, the Managed Service scopes and builds those actions against your account. The integrations catalogue lists every live platform.