# Google Books & Play Books Catalog Explorer (`xyrelith-data/google-books-scraper`) Actor

Search Google Books and Play Books by keyword, author, subject, ISBN or volume ID, and pull Ngram time series. Returns bibliographic metadata, ISBNs, BISAC categories, covers, previews, ratings, Play Books prices and word-frequency trends.

- **URL**: https://apify.com/xyrelith-data/google-books-scraper.md
- **Developed by:** [Xyrelith Data](https://apify.com/xyrelith-data) (community)
- **Categories:** Automation, Developer tools, E-commerce
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.49 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
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?

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

## Google Books & Play Books Catalog Explorer

Pull structured book data from Google Books, live ebook prices from Play Books, and word-frequency
trends from the Google Ngram Viewer — without an API key, login, cookie or proxy. One run can
search a catalog, resolve ISBNs or volume IDs, browse an author or subject, compare Play Books
prices, and export Ngram time series as rows.

### What you get

- **Book records** with volume ID, title and subtitle, all authors, publisher, publication date,
  full description, page count, print type, ISBN-10/13 and other identifiers, language, BISAC
  categories, average rating, viewability, embeddability, open-access flag, cover image, Google
  Books page, preview page, and an optional Play Books URL with price and rating.
- **Play Books cards** with title, series label, rating, current price, original price and sale
  flag, cover, and the verified Play Books URL.
- **Ngram rows** with phrase, phrase type (aggregate or case variant), parent phrase, year,
  relative frequency, corpus, smoothing and a link to the graph.

Every record carries `sourceUrl`, `scrapedAt` and `recordType`. Empty values are omitted at every
depth, so you never get `null`, `""`, `[]` or `{}` in a dataset.

### Modes

| Mode | What it does |
|---|---|
| `search` | Keyword search with Google Books operators: `intitle:`, `inauthor:`, `inpublisher:`, `subject:`, `isbn:`. Pages through results 20 at a time. |
| `byVolumeIds` | Exact lookup from bare volume IDs or Google Books / Play Books URLs. Duplicates and invalid values are skipped. |
| `byIsbn` | ISBN-10 or ISBN-13 lookup, one or many, with or without hyphens. |
| `byAuthor` | Everything Google Books indexes under an author name (`inauthor:`). |
| `bySubject` | Browse a BISAC-style subject or category (`subject:`). |
| `playStoreSearch` | Search the Play Books storefront and return its first 20 ebook cards with live prices. |
| `ngrams` | Google Ngram time series for one or many phrases, any supported corpus and year range. |

### Inputs

| Field | Type | Default | Description |
|---|---|---|---|
| `mode` | string | `search` | What to fetch. |
| `searchQuery` | string | `the lord of the rings` | Keywords for `search` or `playStoreSearch`. |
| `volumeIds` | array | `[]` | Volume IDs or Google Books / Play URLs for `byVolumeIds`. |
| `isbns` | array | `[]` | ISBN-10 or ISBN-13 values for `byIsbn`. |
| `authorNames` | array | `[]` | Author names for `byAuthor`. |
| `subjects` | array | `[]` | Subject/category names for `bySubject`. |
| `ngramPhrases` | array | `[]` | Words or phrases for `ngrams`. |
| `language` | string | `any` | Keep books in one language (applied to the fetched result window). |
| `languageCode` | string | — | Exact language-code override (e.g. `eo`, `tl`); takes precedence over `language`. |
| `viewability` | string | `all` | Filter to full view, preview, or no preview. |
| `printType` | string | `all` | Books, magazines, or both. |
| `freeEbooksOnly` | boolean | `false` | Keep only open-access volumes. |
| `sortBy` | string | `relevance` | Relevance, or newest-first within the fetched result window. |
| `ngramYearStart` | integer | `1800` | First Ngram year (1800–2022). |
| `ngramYearEnd` | integer | `2019` | Last Ngram year (1800–2022). |
| `ngramCorpus` | string | `en` | Ngram corpus: English, American/British English, English fiction, French, German, Spanish, Italian, Russian, Hebrew, Chinese. |
| `ngramSmoothing` | integer | `3` | Smoothing window, 0–50. |
| `ngramCaseInsensitive` | boolean | `true` | Emit a case-insensitive aggregate plus each case variant. |
| `includeFullDetails` | boolean | `true` | Fetch each volume's detail feed for the full description and finer BISAC categories. |
| `includePlayStoreDetails` | boolean | `true` | Check each volume's Play Books page for price, currency, rating and a verified Play link. |
| `maxItems` | integer | `50` | Hard cap on emitted records. Daily prefill uses 3. |

Enrichment is best-effort: a volume without a public Play ebook edition simply has no Play fields.
The daily-test prefill runs `search` on one query with `maxItems: 3` and both enrichment toggles
off, so it costs one Google Books request.

### Search operators

Google Books accepts field prefixes inside `searchQuery`:

```json
{"mode": "search", "searchQuery": "intitle:dune inauthor:herbert", "maxItems": 20}
```

```json
{"mode": "search", "searchQuery": "subject:\"science fiction\" isbn:9780441013593", "maxItems": 5}
```

Operators can be combined with spaces. Use `byAuthor` or `bySubject` when you want a dedicated
author or category scan.

### Examples

Search and enrich:

```json
{
  "mode": "search",
  "searchQuery": "artificial intelligence",
  "language": "en",
  "viewability": "preview",
  "sortBy": "newest",
  "includeFullDetails": true,
  "includePlayStoreDetails": true,
  "maxItems": 25
}
```

Exact volumes (both forms work):

```json
{
  "mode": "byVolumeIds",
  "volumeIds": ["zyTCAlFPjgYC", "https://books.google.com/books?id=i9-wAAAAIAAJ"],
  "maxItems": 2
}
```

Play Books prices:

```json
{"mode": "playStoreSearch", "searchQuery": "atomic habits", "maxItems": 10}
```

Ngram comparison:

```json
{
  "mode": "ngrams",
  "ngramPhrases": ["dune", "foundation"],
  "ngramYearStart": 1950,
  "ngramYearEnd": 2019,
  "ngramCorpus": "en-fiction",
  "ngramSmoothing": 3,
  "ngramCaseInsensitive": true,
  "maxItems": 2000
}
```

### Output fields

#### Book record (`recordType: "book"`)

`volumeId`, `title`, `subtitle`, `authors`, `primaryAuthor`, `publisher`, `publishedDate`,
`publishedYear`, `description`, `pageCount`, `printType`, `isbn10`, `isbn13`,
`otherIdentifiers`, `language`, `categories`, `averageRating`, `viewability`, `embeddable`,
`openAccess`, `freeEbook`, `coverUrl`, `googleBooksUrl`, `previewUrl`, `playStoreUrl`,
`playStorePrice`, `playStoreCurrency`, `playStoreIsFree`, `playStoreRating`,
`playStoreRatingCount`, `query`, `sourceUrl`, `scrapedAt`, `recordType`.

#### Play Books card (`recordType: "playBook"`)

`playBookId`, `title`, `seriesInfo`, `rating`, `price`, `priceText`, `priceCurrency`,
`originalPrice`, `originalPriceText`, `onSale`, `isFree`, `coverUrl`, `playStoreUrl`,
`position`, `query`, `sourceUrl`, `scrapedAt`, `recordType`.

#### Ngram row (`recordType: "ngram"`)

`phrase`, `phraseType`, `parentPhrase`, `year`, `frequency`, `corpus`, `smoothing`,
`caseInsensitive`, `sourceUrl`, `scrapedAt`, `recordType`.

### How pagination works

Google Books returns 20 entries per request and exposes at most the first **600 results per
query** (`start-index` beyond 600 returns nothing). The actor keeps paging until `maxItems`, an
empty page, or the 600-result window. For a very broad query, split it by subject, author, ISBN or
another field operator — each split has its own 600-result window. Play Books search returns its
first 20 ebook cards; refine the query to see a different slice. Ngram requests are not paginated:
all phrases are requested in one call and rows are capped by `maxItems`.

### Prices

Play Books prices are read from the US storefront (`hl=en`, `gl=US`) at run time and reported in
the currency Play returns (normally USD). `playStoreSearch` fills a price for every card.
Per-volume enrichment adds a price only when Google publishes an ebook edition for that exact
volume; print-only volumes get no Play fields. Sale cards expose both `price` and `originalPrice`
plus `onSale`.

### Limits and honest notes

- **600 results per Google Books query.** This is a source window, not an actor setting.
- **20 Play Books cards per search.** The storefront loads more results with internal calls that
  are not part of the public page.
- **Physical dimensions are not published** by the Books feed or the public book page.
- **Download links are not emitted.** Google's EPUB/PDF download URLs redirect to a login or
  return an empty signed response. Use `openAccess` / `freeEbook` to find free full-view books.
- **Ratings are partial.** Google exposes an average for a subset of volumes; `includePlayStoreDetails`
  fills a Play rating and rating count when an ebook edition exists.
- **`sortBy: "newest"` sorts the fetched window**, because the Books feed ignores sort parameters.
- **Ngram years run 1800–2022.** Rows outside the corpus' usable range can be zero.
- **Descriptions are full only with `includeFullDetails`.** The search feed returns snippets; the
  detail feed returns the publisher description when Google has it.
- **No proxy or key is needed.** The actor uses Google's public Books feed, Play Books pages and
  Ngram JSON directly.

### FAQ

**Do I need a Google API key?** No. The actor does not use the keyed Books API, which currently
rate-limits anonymous callers.

**Why did I get fewer rows than `maxItems`?** The query may have fewer matches, the filters may
remove some, or the 600-result source window was reached. The run status message says which.

**Why is one book missing a rating or price?** Google only rates some volumes, and Play only sells
some ebook editions. Missing values are omitted rather than estimated.

**Can I get a book's full description?** Yes — leave `includeFullDetails` on (the default). It
costs one extra small request per record.

**Can I query any language?** The `language` dropdown covers 74 common codes; `languageCode` accepts
any exact ISO code as an override. Language filtering happens over the fetched window, so combine
it with a specific query for best results.

**Are prices historical?** No. Prices and availability are a snapshot of the US Play Store at run
time.

### Data sources

Google Books volume feeds (`books.google.com/books/feeds/volumes`), the Play Books storefront
(`play.google.com/store/...c=books`) and the Google Ngram JSON endpoint
(`books.google.com/ngrams/json`). This actor is not affiliated with Google.

# Actor input Schema

## `mode` (type: `string`):

What to fetch. Each mode reads its own input block below.

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

Keywords for mode=search or mode=playStoreSearch. Google Books operators work: `intitle:`, `inauthor:`, `inpublisher:`, `subject:`, `isbn:`, combinable with spaces/OR. Example: `intitle:dune inauthor:herbert`.

## `volumeIds` (type: `array`):

Google Books volume IDs (e.g. `zyTCAlFPjgYC`) or Books/Play URLs containing `id=`.

## `isbns` (type: `array`):

ISBN-10 or ISBN-13 values, with or without hyphens.

## `authorNames` (type: `array`):

Author names to search with Google Books' `inauthor:` operator, e.g. `Frank Herbert`.

## `subjects` (type: `array`):

BISAC-style subject names to search with `subject:`, e.g. `Science Fiction`, `Business & Economics`, `Juvenile Fiction`.

## `ngramPhrases` (type: `array`):

Words or phrases to compare, e.g. `dune`, `artificial intelligence`, `climate change`.

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

Keep books in one language. Applied to the fetched result window. Use `languageCode` for a code not listed.

## `languageCode` (type: `string`):

Optional exact ISO 639-1/639-2 code (e.g. `eo`, `tl`). Takes precedence over the Language dropdown.

## `viewability` (type: `string`):

Filter by how much of the book Google shows: full view, preview or no preview.

## `printType` (type: `string`):

Restrict results to books or magazines.

## `freeEbooksOnly` (type: `boolean`):

Keep only open-access volumes (public-domain or free full-view books).

## `sortBy` (type: `string`):

Relevance keeps Google's order. Newest sorts the fetched result window by publication date, newest first.

## `ngramYearStart` (type: `integer`):

First year of the Ngram time series (1800–2022).

## `ngramYearEnd` (type: `integer`):

Last year of the Ngram time series (1800–2022). Must be at least the start year.

## `ngramCorpus` (type: `string`):

Google Books Ngram corpus to query.

## `ngramSmoothing` (type: `integer`):

Smoothing window, 0 (none) to 50. Google's default is 3.

## `ngramCaseInsensitive` (type: `boolean`):

When on, emit a case-insensitive aggregate plus one row per case variant.

## `includeFullDetails` (type: `boolean`):

Book modes only. Fetch each volume's detail feed for the full description and finer BISAC categories. One extra small request per record; off in the daily prefill.

## `includePlayStoreDetails` (type: `boolean`):

Book modes only. Check each volume's Play Books page and add price, currency, rating and the verified Play URL when an ebook edition exists. No fields are added for print-only volumes.

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

Hard cap on emitted records. Book searches stop at Google's 600-result window; Play Books search returns at most 20.

## Actor input object example

```json
{
  "mode": "search",
  "searchQuery": "the lord of the rings",
  "volumeIds": [],
  "isbns": [],
  "authorNames": [],
  "subjects": [],
  "ngramPhrases": [],
  "language": "any",
  "viewability": "all",
  "printType": "all",
  "freeEbooksOnly": false,
  "sortBy": "relevance",
  "ngramYearStart": 1800,
  "ngramYearEnd": 2019,
  "ngramCorpus": "en",
  "ngramSmoothing": 3,
  "ngramCaseInsensitive": true,
  "includeFullDetails": false,
  "includePlayStoreDetails": false,
  "maxItems": 3
}
```

# Actor output Schema

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

Dataset containing book records, Play Books cards or Ngram time-series rows.

# 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 = {
    "mode": "search",
    "searchQuery": "the lord of the rings",
    "volumeIds": [],
    "isbns": [],
    "authorNames": [],
    "subjects": [],
    "ngramPhrases": [],
    "language": "any",
    "viewability": "all",
    "printType": "all",
    "freeEbooksOnly": false,
    "sortBy": "relevance",
    "ngramYearStart": 1800,
    "ngramYearEnd": 2019,
    "ngramCorpus": "en",
    "ngramSmoothing": 3,
    "ngramCaseInsensitive": true,
    "includeFullDetails": false,
    "includePlayStoreDetails": false,
    "maxItems": 3
};

// Run the Actor and wait for it to finish
const run = await client.actor("xyrelith-data/google-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 = {
    "mode": "search",
    "searchQuery": "the lord of the rings",
    "volumeIds": [],
    "isbns": [],
    "authorNames": [],
    "subjects": [],
    "ngramPhrases": [],
    "language": "any",
    "viewability": "all",
    "printType": "all",
    "freeEbooksOnly": False,
    "sortBy": "relevance",
    "ngramYearStart": 1800,
    "ngramYearEnd": 2019,
    "ngramCorpus": "en",
    "ngramSmoothing": 3,
    "ngramCaseInsensitive": True,
    "includeFullDetails": False,
    "includePlayStoreDetails": False,
    "maxItems": 3,
}

# Run the Actor and wait for it to finish
run = client.actor("xyrelith-data/google-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 '{
  "mode": "search",
  "searchQuery": "the lord of the rings",
  "volumeIds": [],
  "isbns": [],
  "authorNames": [],
  "subjects": [],
  "ngramPhrases": [],
  "language": "any",
  "viewability": "all",
  "printType": "all",
  "freeEbooksOnly": false,
  "sortBy": "relevance",
  "ngramYearStart": 1800,
  "ngramYearEnd": 2019,
  "ngramCorpus": "en",
  "ngramSmoothing": 3,
  "ngramCaseInsensitive": true,
  "includeFullDetails": false,
  "includePlayStoreDetails": false,
  "maxItems": 3
}' |
apify call xyrelith-data/google-books-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,xyrelith-data/google-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/hTiiWhMSJ0SEiOkAK/builds/RHIMj9apggQcHMtDi/openapi.json
