# Open Library Books - Search and ISBN Metadata (`atesen-software/open-library-books`) Actor

Search Open Library by title, author or keywords, or look up one ISBN edition. Saves authors, ISBNs, subjects, years and links. Official API, no key.

- **URL**: https://apify.com/atesen-software/open-library-books.md
- **Developed by:** [Atesen Software](https://apify.com/atesen-software) (community)
- **Categories:** Developer tools
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 75.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$1.20 / 1,000 book results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

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

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Open Library Books — Search and ISBN Metadata

Need clean book metadata (title, authors, ISBNs, subjects, first publish year) without copying it by hand from Open Library? This Actor searches Open Library by keywords, title or author, or resolves one ISBN to its exact edition, and saves tidy rows you can export as JSON, CSV or Excel — for **$1.20 per 1,000 books**.

Data source: [Open Library](https://openlibrary.org), a project of the Internet Archive, through its official public [Search API](https://openlibrary.org/dev/docs/api/search) and [Books API](https://openlibrary.org/dev/docs/api/books). No API key, login or proxy is needed. Built and maintained by Atesen Software.

### What you can use it for

- **Catalog and reading-list enrichment**: add authors, subjects, publication years, languages and Open Library links to your own book list.
- **ISBN resolution**: turn a checksum-valid ISBN-10 or ISBN-13 into the exact edition record.
- **Library, classroom and research lookups**: confirm a title exists, compare edition counts and first publication years.
- **Prototype data for book apps**: small, capped exports instead of hand-built spreadsheets.

### Input

```json
{"title":"The Hobbit","maxBooks":2,"includeCoverUrl":true}
```

- `query`, `title` and `author` can be combined (for example `{"title":"Dune","author":"Herbert"}`).
- `isbn` is a separate mode for one edition: `{"isbn":"978-0-261-10221-7"}`. Spaces and hyphens are accepted; the checksum is validated before any request.
- `maxBooks`: 1–50, default 10. `maxRequests`: 1–10, default 10 (retries count).
- `includeCoverUrl`: default false. Adds a cover image URL only; images are never downloaded.

Missing selectors or an invalid ISBN do not fail the run: you get one free `status` row explaining the problem, with zero API requests and zero charge.

### Output

Each `book` row has `title`, `authors`, `authorIds`, `workId` / `editionId`, `metadataLevel` (`work` for search results, `edition` for ISBN lookups), `firstPublishYear`, `publicationYears` or `publicationDate`, `editionCount`, `isbns`, `subjects`, `languages`, `editionIds`, `openLibraryUrl`, optional `coverUrl`, the `sourceUrl` of the API call and `retrievedAt`. Fields missing at the source stay null or empty; nothing is invented. Lists are capped at 100 entries.

Example row from a real run with `{"title":"The Hobbit"}` (lists shortened):

```json
{
  "recordType": "book",
  "status": "completed",
  "metadataLevel": "work",
  "workId": "OL27482W",
  "editionId": null,
  "title": "The Hobbit",
  "authors": ["J.R.R. Tolkien"],
  "authorIds": ["OL26320A"],
  "firstPublishYear": 1937,
  "editionCount": 482,
  "isbns": ["9788422615866", "9780739410745", "0261102214"],
  "subjects": ["Fantasy", "Battle of Five Armies", "dragons"],
  "openLibraryUrl": "https://openlibrary.org/works/OL27482W",
  "coverUrl": null
}
```

An ISBN lookup (`{"isbn":"978-0-261-10221-7"}`) returned edition `OL37509862M`, `publicationDate` "2009" and ISBNs `9780261102217` and `0261102214`.

Every run also writes one free `status` row and an `OUTPUT` summary (status, saved rows, request count) in the key-value store.

### How much does it cost?

Pay per event: **$0.0012 per saved book ($1.20 per 1,000 books)**. There is no start fee. Status rows, invalid input, no-match searches and provider errors are never charged. You can set a maximum cost per run; the budget is checked before every API request and every row, so the Actor stops cleanly when it is reached.

### Run outcomes

- `completed` / `no_results`: normal finish.
- `invalid_input`: free status row, no requests.
- `rate_limited`: Open Library asked to slow down for longer than 15 seconds; the run finishes with a free status row and a `retryAt` time. Books already saved stay in the dataset.
- `request_limit` / `budget_limit`: the request cap or your cost limit was reached; saved books stay.
- Unexpected HTTP errors, redirects or invalid JSON from the API fail the run loudly so you never mistake an outage for "no books".

### Fair use of Open Library

Open Library asks API users to identify their application, stay within its rate limits and use the monthly [data dumps](https://openlibrary.org/developers/dumps) for bulk work ([API guidelines](https://openlibrary.org/developers/api)). This Actor sends an honest User-Agent with the app name and a support contact, waits at least 1.1 seconds between requests, honors `Retry-After` on 429/503, never follows redirects, and caps each run at 50 books and 10 requests. It only calls the JSON APIs; it does not scrape HTML, crawl the Covers API or download texts, scans or images. Please keep runs small and spaced, and do not use it as a high-traffic backend; for a full catalog, download the dumps.

### Data licensing and attribution

Open Library states that it does not assert any new copyright over the material in its database, and that some contributions may carry existing rights in some jurisdictions ([licensing](https://openlibrary.org/developers/licensing)). Cover images are provided separately by the Covers API; if you display covers, Open Library asks for a courtesy link back. Please credit Open Library when you publish the data.

### FAQ

**Why are runs capped at 50 books?** The cap keeps usage at the human scale the provider's guidelines ask for. For bulk data, use the Open Library dumps.

**Work or edition?** Search results are works (one book across many editions). ISBN lookups return one edition. Check `metadataLevel` before comparing `editionCount` or `firstPublishYear`.

**Can I get full texts or cover files?** No. Only metadata and, optionally, the cover URL.

**Can I schedule it?** Yes, for small, spaced runs.

**Is personal data involved?** No. Titles, ISBNs and author names are bibliographic data.

### Support

Use the **Issues** tab on the Actor page or write to support@atesensoftware.com. This Actor is independent and not affiliated with Open Library or the Internet Archive. Built and maintained by Atesen Software.

# Actor input Schema

## `query` (type: `string`):

Optional general book keywords. Combine with title or author; not with ISBN.

## `title` (type: `string`):

Optional book title. Combine with query or author; not with ISBN.

## `author` (type: `string`):

Optional author name. Combine with query or title; not with ISBN.

## `isbn` (type: `string`):

Alternative single ISBN-10/13 edition lookup. Checksum validated; spaces and hyphens accepted. Do not combine with search selectors.

## `maxBooks` (type: `integer`):

Maximum book rows to save in this run (1-50). Each saved book is one paid result.

## `maxRequests` (type: `integer`):

Maximum Open Library API requests in this run, retries included (1-10).

## `includeCoverUrl` (type: `boolean`):

Include a cover URL when available, without downloading the image.

## Actor input object example

```json
{
  "title": "The Hobbit",
  "maxBooks": 10,
  "maxRequests": 10,
  "includeCoverUrl": false
}
```

# Actor output Schema

## `results` (type: `string`):

Default dataset. Only book records have a result event.

## `summary` (type: `string`):

Completion status, result count, partial flag and API request count.

# 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 = {
    "title": "The Hobbit"
};

// Run the Actor and wait for it to finish
const run = await client.actor("atesen-software/open-library-books").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 = { "title": "The Hobbit" }

# Run the Actor and wait for it to finish
run = client.actor("atesen-software/open-library-books").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 '{
  "title": "The Hobbit"
}' |
apify call atesen-software/open-library-books --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,atesen-software/open-library-books"
        }
    }
}
```

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/QWKgE5o5myJP7GWOe/builds/oFvTTAPFfhhjepKWU/openapi.json
