# Project Gutenberg Books Scraper (`parseforge/gutendex-project-gutenberg-books-scraper`) Actor

Scrapes Project Gutenberg catalog for book metadata, subjects, bookshelves, and download links. Filter by search query, topic, language, author year, or book ID.

- **URL**: https://apify.com/parseforge/gutendex-project-gutenberg-books-scraper.md
- **Developed by:** [ParseForge](https://apify.com/parseforge) (community)
- **Categories:** News, Developer tools
- **Stats:** 2 total users, 1 monthly users, 89.7% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $19.00 / 1,000 result items

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

[![ParseForge](https://raw.githubusercontent.com/ParseForge/apify-assets/main/banner.jpg)](https://apify.com/parseforge?fpr=vmoqkp)

### Project Gutenberg Books Scraper

**Scrape Project Gutenberg books by title, author, topic, or language, up to a million per run.** Every book comes with its metadata, subjects, bookshelves, and download links. No login or API key. Export to CSV, JSON, Excel, or XML.

Project Gutenberg's official catalog has no bulk export and no API for filtered searches. This reads the public catalog directly, filtered by title, author, topic, language, or author years, and returns each match in one fixed schema.

| Who uses it | What they scrape Project Gutenberg for |
|---|---|
| Digital librarians | Building a local catalog of public domain titles for a library system |
| Literary researchers | Gathering all works by an author or within a topic for corpus analysis |
| Book app developers | Populating a reading app with metadata and download links for free ebooks |
| Educators | Compiling reading lists by language, topic, or historical period |

### What it does

This Actor collects Project Gutenberg book records by search query, topic, language, author year range, or specific book IDs, and returns each one as a flat row.

- 🔎 **Catalog search:** match titles and author names with a keyword query, multiple words are AND-combined.
- 🌐 **Language filter:** restrict results to one of 20 languages using ISO 639-1 codes.
- 📚 **Topic filter:** match subjects or bookshelves like children, science, philosophy, history, fiction, or religion.
- 📅 **Author year range:** filter by author birth or death year, use negatives for BCE.
- 🆔 **Direct lookup:** fetch specific titles by their Project Gutenberg book ID, overrides other filters.

Results export to CSV, JSON, Excel, or XML, or straight from the API.

### What you can do with Project Gutenberg data

**📖 Build a digital library catalog.**

A librarian runs the Actor with a topic filter like 'science' and language 'en' to gather metadata for a curated collection.

**🔬 Analyze literary trends.**

A researcher collects all books by authors born between 1800 and 1900 to study 19th-century fiction.

**📱 Populate a reading app.**

A developer fetches book IDs for classic titles to include download links and metadata in their app.

**🌍 Create multilingual reading lists.**

An educator filters by language 'es' and topic 'children' to compile Spanish children's books for a classroom.

### Why choose this scraper

|  | What you get |
|---|---|
| **No API key** | Reads the public catalog directly, no registration or rate limits |
| **70K+ books** | Access the full Project Gutenberg collection of free public domain ebooks |
| **Fixed schema** | Every book returns the same flat fields for easy processing |
| **Flexible filters** | Combine search, topic, language, and author year to narrow results |
| **Scalable** | Collect up to a million books per run |

### How it compares

This Actor and the listed competitor both scrape Project Gutenberg, but they differ in filter options and output details.

| Feature | ParseForge | Project Gutenberg Scraper |
|---|---|---|
| Search by title or author | Yes | Yes |
| Filter by topic | Yes | Not listed |
| Filter by language | Yes | Not listed |
| Filter by author year range | Yes | Not listed |
| Lookup by book ID | Yes | Not listed |
| Download links (EPUB, Kindle, TXT, HTML) | Yes | Yes |

### Configure the run

Drive the Actor from search queries, topics, languages, author year ranges, and specific book IDs, alone or together, and filters run as each book is read so only matches reach your dataset. The Input tab lists every parameter.

A first run with the defaults:

```json
{
  "maxItems": 10,
  "searchQuery": "shakespeare"
}
```

A larger pull:

```json
{
  "maxItems": 200,
  "searchQuery": "shakespeare"
}
```

### Pricing

Pay-per-result: **$0.021 per result** collected. You pay only for the results written to your dataset.

| Results collected | Approximate cost |
|---|---|
| 100 results | $2.10 |
| 1,000 results | $21.00 |
| 10,000 results | $210.00 |

New Apify accounts start with $5 in free credit.

### Free users

Free-plan runs return up to 10 results as a preview. [Upgrade your Apify plan](https://console.apify.com/sign-up?fpr=vmoqkp) to collect up to 1,000,000 results per run.

### Run it

1. [Create a free Apify account with $5 in credit](https://console.apify.com/sign-up?fpr=vmoqkp).
2. Open the [Project Gutenberg Books Scraper](https://apify.com/parseforge/gutendex-project-gutenberg-books-scraper?fpr=vmoqkp).
3. Set your inputs and any filters, then click **Start**.
4. Export the results as CSV, Excel, JSON, or XML from the **Dataset** tab.

Run it programmatically through the [Apify API](https://docs.apify.com/api/v2) (`run-sync-get-dataset-items`) or the [ApifyClient](https://docs.apify.com/api/client/js) for JavaScript and Python.

### Use with AI agents (MCP)

Give an AI agent live access to Project Gutenberg through the Model Context Protocol. Add the Actor to Claude, Cursor, or any MCP client:

```bash
claude mcp add --transport http apify "https://mcp.apify.com/?tools=parseforge/gutendex-project-gutenberg-books-scraper"
```

Then prompt it in plain language to run the scraper and read back the results.

### Troubleshooting

**Why am I getting no results?**

Check your filters. If you used book IDs, they override other filters. Otherwise, try broadening your search query or removing some filters.

**Why did the run stop before reaching my maximum books?**

The Actor stops when there are no more matching books in the catalog. Try adjusting your filters to get more results.

**How do I search for a phrase with multiple words?**

Join the words with %20 in the search query field. For example, 'sherlock%20holmes' will match books with both words.

**Can I get the full text of the books?**

No, this Actor returns metadata and download links, not the full text. You can use the download links to fetch the text separately.

**Why is my language filter not working?**

Make sure you use the correct ISO 639-1 code, such as 'en' for English or 'es' for Spanish. The select field lists all supported codes.

### FAQ

| Question | Answer |
|---|---|
| Do I need an API key or login? | No. This Actor reads the public Project Gutenberg catalog directly, so no registration or authentication is required. |
| How many books can I scrape in one run? | You can set the maximum books field up to 1,000,000. The Actor will stop after collecting that many matches. |
| Can I search by author name? | Yes. Use the search query field with the author's name, and it will match against both titles and author names. |
| What languages are supported? | The language filter includes 20 languages: English, Spanish, French, German, Italian, Portuguese, Russian, Chinese, Japanese, Arabic, Dutch, Latin, Greek, Finnish, Swedish, Polish, Hungarian, Tagalog, Catalan, and Czech. |
| How do I get a specific book? | Use the book IDs field and enter the Project Gutenberg ID, for example 1342 for Pride and Prejudice. This overrides other filters. |
| What is the topic filter? | It matches against subjects and bookshelves in the catalog, such as children, science, philosophy, history, fiction, or religion. |
| Can I filter by author birth or death year? | Yes. Use author year start and end fields. Use negative numbers for BCE dates. |
| What output formats are supported? | You can export the results to CSV, JSON, Excel, or XML from the Apify dataset. |
| Is the data up to date? | The Actor reads the live Project Gutenberg catalog at the time of the run, so it reflects current listings. |
| Can I combine filters? | Yes. You can combine search query, language, topic, and author year range to narrow results. Book IDs override other filters. |

### Related actors

Browse the full [ParseForge collection](https://apify.com/parseforge?fpr=vmoqkp) for more scrapers.

🆘 **Need help?** Email parseforge@protonmail.com with your run ID, your input, and what you expected.

⚠️ **Disclaimer.** This Actor is unofficial and is not affiliated with, endorsed by, or sponsored by Project Gutenberg Literary Archive Foundation. It collects only publicly available data. You are responsible for using the collected data in compliance with the source's terms of service and applicable data-protection laws, including GDPR, CCPA, and PIPL. Do not use it to collect personal data unlawfully.

# Actor input Schema

## `maxItems` (type: `integer`):

How many books to collect per run.

## `searchQuery` (type: `string`):

Keywords matched against titles and author names. Multiple words joined with %20 are AND-combined.

## `language` (type: `string`):

ISO 639-1 language code to restrict results to one language.

## `topic` (type: `string`):

Match a topic in subjects or bookshelves (e.g. children, science, philosophy, history, fiction, religion).

## `authorYearStart` (type: `integer`):

Earliest author birth/death year (use negatives for BCE).

## `authorYearEnd` (type: `integer`):

Latest author birth/death year.

## `bookIds` (type: `array`):

Lookup specific Project Gutenberg IDs (e.g. 1342 for Pride and Prejudice). Overrides other filters.

## Actor input object example

```json
{
  "maxItems": 10,
  "searchQuery": "shakespeare"
}
```

# Actor output Schema

## `overview` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "maxItems": 10,
    "searchQuery": "shakespeare"
};

// Run the Actor and wait for it to finish
const run = await client.actor("parseforge/gutendex-project-gutenberg-books-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "maxItems": 10,
    "searchQuery": "shakespeare",
}

# Run the Actor and wait for it to finish
run = client.actor("parseforge/gutendex-project-gutenberg-books-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "maxItems": 10,
  "searchQuery": "shakespeare"
}' |
apify call parseforge/gutendex-project-gutenberg-books-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,parseforge/gutendex-project-gutenberg-books-scraper"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/Hm6RXOQRrEsYFAomm/builds/f82zashgp3OvldOeh/openapi.json