DOCSEARCHbyAlgolia
Submit Docs

Gutendex API Documentation

repository·master·Indexed 18 days ago

https://github.com/garethbjohnson/gutendex

A self-hosted REST API that serves Project Gutenberg book catalog information in JSON format. Features include the /books endpoint for paginated queries with filtering by author years, copyright, IDs, languages, MIME types, and topics, as well as individual book retrieval by ID. Includes documentation on JSON object schemas for Books, Formats, and Persons, and the updatecatalog management command for synchronizing the local database with the latest Project Gutenberg RDF files.

Tokens
1.1K
Snippets
3
Records
6
Agent score
13%

What's inside Gutendex

  1. Query lists of books via the /books endpoint

    master

    Use the /books endpoint to retrieve lists of book information. Results are paginated, returning 0-32 books per request. By default, books are ordered by popularity (number of downloads).

    Response Format:

    {
  "count": <number>,
  "next": <string or null>,
  "previous": <string or null>,
  "results": <array of Books>
}
    • count: Total number of books matching the query across all pages.
    • next: URL to the next page of results.
    • previous: URL to the previous page of results.
    • results: Array of book objects.
    {
  "count": <number>,
  "next": <string or null>,
  "previous": <string or null>,
  "results": <array of Books>
}

  2. Retrieve an individual book by ID

    master

    To get detailed information for a specific book, use the endpoint /books/<id>, where <id> is the Project Gutenberg ID number.

    Error Response: If the book is not found or an error occurs, the API returns:

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

  3. Understand Gutendex API object schemas

    master

    The Gutendex API returns three primary JSON object types:

    Book

    Represents a single book entry.

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

    Format

    An object where keys are MIME-types and values are URLs to the files.

    {
  "text/html": "https://example.com/book.html",
  "text/plain": "https://example.com/book.txt"
}

    Person

    Represents an author, editor, or translator.

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

  4. Filter book lists with query parameters

    master

    You can refine book list queries at /books using various URL parameters:

    • author_year_start & author_year_end: Find books with authors alive in a specific year range (integers). Example: /books?author_year_start=1800&author_year_end=1899.
    • copyright: Filter by copyright status. Use true (copyrighted), false (public domain in USA), or null (no info). Multiple values can be comma-separated. Example: /books?copyright=true,false.
    • ids: List specific books by their Project Gutenberg ID numbers (comma-separated integers). Example: /books?ids=11,12,13.
    • languages: Filter by two-character language codes (comma-separated). Example: /books?languages=en,fr.
    • mime_type: Find books with a MIME type starting with the provided value. Example: /books?mime_type=text%2F.
    • search: Case-insensitive search for author names or book titles using space-separated words. Example: /books?search=dickens%20great.
    • sort: Change sort order. Options: ascending (ID low to high), descending (ID high to low), or popular (default).
    • topic: Case-insensitive search for key-phrases in bookshelves or subjects. Example: /books?topic=children.

  5. Error handling in updatecatalog

    master

    If the updatecatalog command encounters an error, it will:

    1. Log the error message.
    2. Attempt to clean up the temporary directory (TEMP_PATH).
    3. Send an email containing the log to the configured administrators.

    If the temporary path defined in settings.CATALOG_TEMP_DIR already exists when the command starts, it will raise a CommandError and abort to prevent data corruption.

  6. Update the Project Gutenberg catalog via updatecatalog

    master

    The updatecatalog management command automates the process of downloading the latest Project Gutenberg catalog, replacing local RDF files, and synchronizing the database with the new data.

    Workflow:

    1. Downloads the compressed catalog from https://gutenberg.org/cache/epub/feeds/rdf-files.tar.bz2 into a temporary directory.
    2. Decompresses the catalog using tar.
    3. Identifies and removes stale directories and corresponding book records in the database that are no longer present in the new catalog.
    4. Syncs files using rsync to replace old catalog files with the new ones.
    5. Updates the database by iterating through the RDF files and creating or updating Book, Person (authors, editors, translators), Bookshelf, Format, Language, Subject, and Summary objects.
    6. Cleans up temporary files.
    7. Sends an email notification containing the execution log to the addresses specified in settings.ADMIN_EMAILS (if configured).

    Note: This command requires tar and rsync to be available in the system path.

    python manage.py updatecatalog