Gutendex

JSON web API for Project Gutenberg ebook metadata

Try it

Test queries here. See the docs below.

Documentation

For long-term use, please run your own server with the code and installation instructions on GitHub.

API Endpoints Overview

The Gutendex API provides the following endpoints:

  • Books: /books/ - List and search books
  • Categories: /bookshelves/, /subjects/ - Browse categories
  • Languages: /languages/ - Browse available languages
  • Formats: /formats/ - Browse available formats
  • Discovery: /random/, /recommendations/ - Find new books
  • Authors: /sameAuthor/<id>/ - Books by specific author
  • Similar Books: /books/<id>/similar/ - Find similar books

Lists of Books

Lists of book information in the database are queried using the API at /books (e.g. gutendex.com/books). Book data will be returned in the format 

{
  "count": <number>,
  "next": <string or null>,
  "previous": <string or null>,
  "results": <array of Books>
}

where results is an array of 0-32 book objects, next and previous are URLs to the next and previous pages of results, and count in the total number of books for the query on all pages combined.

By default, books are ordered by popularity, determined by their numbers of downloads from Project Gutenberg.

Parameters can also be added to book-list queries in a typical URL format. For example, to get the first page of written by authors alive after 1899 and published in English or French, you can go to /books?author_year_start=1900&languages=en,fr

You can find available query parameters below.

author_year_start and author_year_end

Use these to find books with at least one author alive in a given range of years. They must have positive or negative integer values. For example, /books?author_year_end=-499 gives books with authors alive before 500 BCE, and /books?author_year_start=1800&author_year_end=1899 gives books with authors alive in the 19th Century.

copyright

Use this to find books with a certain copyright status: true for books with existing copyrights, false for books in the public domain in the USA, or null for books with no available copyright information. These can be combined with commas. For example, /books?copyright=true,false gives books with available copyright information.

ids

Use this to list books with Project Gutenberg ID numbers in a given list of numbers. They must be comma-separated positive integers. For example, /books?ids=11,12,13 gives books with ID numbers 11, 12, and 13.

languages

Use this to find books in any of a list of languages. They must be comma-separated, two-character language codes. For example, /books?languages=en gives books in English, and /books?languages=fr,fi gives books in either French or Finnish or both.

mime_type

Use this to find books with a given MIME type. Gutendex gives every book with a MIME type starting with the value. For example, /books?mime_type=text%2F gives books with types text/html, text/plain; charset=us-ascii, etc.; and /books?mime_type=text%2Fhtml gives books with types text/html, text/html; charset=utf-8, etc.

search

Use this to search author names and book titles with given words. They must be separated by a space (i.e. %20 in URL-encoded format) and are case-insensitive. For example, /books?search=dickens%20great includes Great Expectations by Charles Dickens.

sort

Use this to sort books: ascending for Project Gutenberg ID numbers from lowest to highest, descending for IDs highest to lowest, or popular (the default) for most popular to least popular by number of downloads.

topic

Use this to search for a case-insensitive key-phrase in books' bookshelves or subjects. For example, /books?topic=children gives books on the "Children's Literature" bookshelf, with the subject "Sick children -- Fiction", and so on.

Individual Books

Individual books can be found at /books/<id>, where <id> is the book's Project Gutenberg ID number. Error responses will appear in this format: 

{
  "detail": <string of error message>
}

API Objects

Types of JSON objects served by Gutendex are given below.

Book

{
  "id": <number of Project Gutenberg ID>,
  "title": <string>,
  "subjects": <array of strings>,
  "authors": <array of Persons>,
  "summaries": <array of strings>,
  "translators": <array of Persons>,
  "bookshelves": <array of strings>,
  "languages": <array of strings>,
  "copyright": <boolean or null>,
  "media_type": <string>,
  "formats": <Format>,
  "download_count": <number>
}

Format

{
  <string of MIME-type>: <string of URL>,
  ...
}

Person

{
  "birth_year": <number or null>,
  "death_year": <number or null>,
  "name": <string>
}

Category and Classification Endpoints

/bookshelves/

List all available bookshelves (categories) with book counts.

Parameters:

  • search - Search bookshelf names (case-insensitive)

Example: /bookshelves/?search=children

/subjects/

List all available subjects (genres) with book counts.

Parameters:

  • search - Search subject names (case-insensitive)

Example: /subjects/?search=fiction

/bookshelves/<name>/books/

Get all books in a specific bookshelf.

Parameters:

  • sort - Sort order: ascending, descending, or popular (default)

Example: /bookshelves/Children's Literature/books/

/subjects/<name>/books/

Get all books with a specific subject.

Parameters:

  • sort - Sort order: ascending, descending, or popular (default)

Example: /subjects/Fiction/books/

Language Endpoints

/languages/

List all available languages with book counts.

Parameters:

  • search - Search language codes (case-insensitive)

Example: /languages/?search=en

/languages/<code>/books/

Get all books in a specific language.

Parameters:

  • sort - Sort order: ascending, descending, or popular (default)

Example: /languages/en/books/

Format Endpoints

/formats/

List all available MIME types with book counts.

Parameters:

  • search - Search MIME types (case-insensitive)

Example: /formats/?search=text

/formats/<mime_type>/books/

Get all books with a specific MIME type.

Parameters:

  • sort - Sort order: ascending, descending, or popular (default)

Example: /formats/text/html/books/

Discovery and Recommendation Endpoints

/random/

Get random books for discovery.

Parameters:

  • count - Number of random books (default: 1)
  • language - Filter by language code
  • subject - Filter by subject name (case-insensitive)

Examples:

  • /random/?count=5 - Get 5 random books
  • /random/?language=en&count=3 - Get 3 random English books
  • /random/?subject=fiction&count=2 - Get 2 random fiction books

/sameAuthor/<author_id>/

Get all books by a specific author.

Parameters:

  • sort - Sort order: ascending, descending, or popular (default)

Example: /sameAuthor/123/

/books/<book_id>/similar/

Find books similar to a given book based on shared authors, subjects, and bookshelves.

Parameters:

  • limit - Maximum number of similar books (default: 10)

Example: /books/11/similar/?limit=5

/recommendations/

Get book recommendations based on topics.

Parameters:

  • topic - Comma-separated list of topics (required)
  • count - Number of books per topic (default: 3)

Examples:

  • /recommendations/?topic=fiction - Get 3 random fiction books
  • /recommendations/?topic=fiction,romance&count=2 - Get 2 books each for fiction and romance

Response Formats

List Responses

Most list endpoints return paginated results in this format:

{
  "count": <number>,
  "next": <string or null>,
  "previous": <string or null>,
  "results": <array of objects>
}

Category/Language/Format Objects

Category, language, and format list items include book counts:

{
  "name": <string>,
  "book_count": <number>
}

Error Responses

Error responses follow this format:

{
  "error": <string of error message>
}