Gutendex Next

A FastAPI & SQLite rewrite of the Django & Postgres-based Gutendex API, optimized for lower resource usage, faster response times, and simple Docker Compose deployment.

Gutendex-Next is a self-hosted web API for serving book catalog data from Project Gutenberg. It is a drop-in replacement for original Gutendex API featuring same endpoints, query parameters, and response format, so existing clients require no changes. The main differences are behind the scenes, in the backend implementation:

• Up to 5× faster catalog updates thanks to batched book processing and SQLite Write-Ahead (WAL) mode (10 minutes vs. 1 hour).
• 60% lower memory usage compared to the Django + PostgreSQL stack.
• Much faster API performance, comparable to Go and Node.js APIs, thanks to FastAPI and Pydantic, one of the fastest Python web framework combinations available today.
• Easy deployment with a single docker compose up -d command, instead of spending 30+ minutes setting up the environment and configuring services manually.
• Simple backups, since the catalog database is stored in a single SQLite database file.

Quick Start

Requirements: Docker + Docker Compose

# 1. Clone and enter the project
git clone https://github.com/Pool-Of-Tears/gutendex-next.git
cd gutendex-next

# 2. Create data directories
mkdir -p data

# 3. Build and start
docker compose up -d

# 4. Import the Gutenberg catalog (one-time, takes ~10 min)
docker compose exec gutendex-next python catalog/updatecatalog.py

# 5. Test it
curl http://localhost:5073

The API is now live at http://localhost:5073.

To update the catalog in the future, re-run step 4.

How does it work?

Gutendex uses FastAPI to serve book catalog data in a simple JSON REST API.

Project Gutenberg publishes nightly archives of complex XML files. Gutendex downloads these, stores the data in a local SQLite database, and exposes it in a clean format.

API

The home page is at the root URL (http://localhost:5073).

Lists of Books

GET /books

Returns paginated book data:

{
  "count": 70000,
  "next": "/books?page=2",
  "previous": null,
  "results": [...]
}

results contains up to 32 books by default, ordered by download count. Use page and page_size to paginate.

Query Parameters

Parameter	Description
author_year_start	Books with an author alive on or after this year
author_year_end	Books with an author alive on or before this year
copyright	true, false, or null — combinable with commas
ids	Comma-separated Project Gutenberg IDs, e.g. ids=11,12,13
languages	Comma-separated language codes, e.g. languages=en,fr
mime_type	Formats starting with this MIME type, e.g. mime_type=text/plain
search	Space-separated words to search in titles and author names
sort	ascending or descending by ID; default is by download count
topic	Case-insensitive search in bookshelves and subjects
page	Page number (default: 1)
page_size	Results per page (default: 32, max: 100)

Individual Books

GET /books/<id>

Returns a single book by its Project Gutenberg ID.

API Objects

Book

{
  "id": 11,
  "title": "Alice's Adventures in Wonderland",
  "authors": [{"name": "Carroll, Lewis", "birth_year": 1832, "death_year": 1898}],
  "summaries": [],
  "editors": [],
  "translators": [],
  "subjects": ["Fantasy fiction"],
  "bookshelves": ["Children's Literature"],
  "languages": ["en"],
  "copyright": false,
  "media_type": "Text",
  "formats": {"text/html": "https://...", "application/epub+zip": "https://..."},
  "download_count": 35000
}

Person

{"birth_year": 1832, "death_year": 1898, "name": "Carroll, Lewis"}