# VNDB Visual Novels Scraper (`parseforge/vndb-visual-novels-scraper`) Actor

Scrapes visual novel entries from the Visual Novel Database (VNDB) by free-text search or raw filter expression. Returns each entry as a flat row with rating, vote count, release date, tags, and any extra fields you request.

- **URL**: https://apify.com/parseforge/vndb-visual-novels-scraper.md
- **Developed by:** [ParseForge](https://apify.com/parseforge) (community)
- **Categories:** Developer tools, Other
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $7.69 / 1,000 results

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)

### VNDB Visual Novels Scraper

**Scrape VNDB visual novels by title, keyword, or raw filter, up to a million per run.** Every entry returns its rating, vote count, release date, tags, and developer. No API key or registration. Export to CSV, JSON, Excel, or XML.

The Visual Novel Database (VNDB) is the central catalog for visual novels, but its official API requires learning a custom query language and handling pagination yourself. This Actor reads the public VNDB listings directly, lets you search by title or apply advanced filters like language or original language, and returns each matching visual novel in one consistent flat row. No API key, no query syntax to memorize.

| Who uses it | What they scrape VNDB for |
|---|---|
| Visual novel fans and curators | Build a personal list of top-rated untranslated visual novels to track for fan translation patches. |
| Game data analysts | Pull the full VNDB catalog to analyze rating distributions, tag co-occurrence, and release trends over decades. |
| Recommendation engine builders | Collect visual novels with their tags and ratings to train a content-based recommendation model. |
| Localization scouts | Identify high-rated Japanese-original visual novels with no English release for potential licensing. |

### What it does

This Actor collects VNDB visual novel entries by free-text search or raw filter expression and returns each one as a flat row with its rating, vote count, release date, and all requested fields.

- 🔍 **Free-text search:** type a title or keyword like 'saya' or 'fate stay night' and get every matching visual novel.
- 🏷️ **Advanced raw filters:** pass a VNDB Kana filter array to narrow by language, original language, platform, or any supported field.
- 📊 **Flexible sorting:** order results by rating, vote count, release date, title, VNDB ID, or search relevance.
- 📦 **Extra fields on demand:** request additional VNDB fields like original language, length in minutes, or development status beyond the defaults.

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

### What you can do with VNDB data

**📈 Track rating trends over time.**

A data journalist scrapes all visual novels released since 2000, sorted by release date, and plots average rating per year to see how the medium has evolved.

**🌐 Find untranslated gems.**

A fan translation group filters for Japanese-original visual novels with no English release, sorted by rating, to pick their next project.

**🏷️ Build a tag-based discovery tool.**

A hobbyist developer collects every visual novel with its full tag list and builds a search interface that lets users filter by multiple tags at once.

**📋 Audit a personal collection.**

A collector searches for specific titles they own, pulls the official VNDB rating and vote count, and compares against their own scores in a spreadsheet.

### Why choose this scraper

|  | What you get |
|---|---|
| **No API key required** | Reads the public VNDB listings without registration, OAuth, or rate-limit headaches. |
| **Flat row output** | Every visual novel lands as one row in CSV, JSON, Excel, or XML, ready for spreadsheets or databases. |
| **Up to a million entries** | Set a high maxItems and pull the entire catalog in one long run. |
| **Raw filter power** | Use the full VNDB Kana filter syntax for queries the simple search box cannot express. |

### How it compares

No other Store actor targets VNDB the same way, so the honest comparison is with the alternatives teams actually weigh.

| | VNDB Visual Novels Scraper | Build it in-house | By hand |
|---|---|---|---|
| Setup | Run it now, zero config | Days of engineering | None, but hours per pull |
| When VNDB changes | Maintained for you | You fix it | You re-learn the page |
| Proxies, retries, anti-bot | Built in | Your problem | Browser only |
| Output | Fixed JSON schema, CSV/Excel export | Whatever you build | Copy-paste |
| Cost | Pay per result | Engineering time | Analyst hours |

### Configure the run

Drive the Actor from a free-text title search or a raw VNDB filter expression, and set a maximum item count so only the top matches reach your dataset. The Input tab lists every parameter.

A first run with the defaults:

```json
{
  "search": "saya",
  "maxItems": 10
}
```

A larger pull:

```json
{
  "search": "saya",
  "maxItems": 200
}
```

### Pricing

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

| Results collected | Approximate cost |
|---|---|
| 100 results | $1.70 |
| 1,000 results | $17.00 |
| 10,000 results | $170.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 [VNDB Visual Novels Scraper](https://apify.com/parseforge/vndb-visual-novels-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 VNDB 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/vndb-visual-novels-scraper"
```

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

### Troubleshooting

**Why am I getting no results?**

Check that your search term matches actual VNDB titles or aliases. If you are using advanced filters, verify the filter syntax is a valid Kana array. Try removing filters and running with only a search term to isolate the issue.

**Why are some fields empty in my output?**

Not every visual novel has every field populated. For example, a newly added entry may not yet have a rating or vote count. If you need a specific field that is not in the defaults, add it to the Extra fields input.

**The advanced filter I wrote is not working.**

VNDB filter expressions must be valid JSON arrays using the Kana syntax. Common mistakes include missing brackets, using the wrong operator, or referencing a field name that does not exist. Test your filter against the VNDB API documentation examples first.

**My run is taking a long time.**

Large maxItems values mean more pages to fetch. If you only need the top results, reduce the maximum. Sorting by search rank with no search term can also slow things down; switch to a concrete sort order like rating.

**The search returns too many unrelated visual novels.**

Free-text search matches any part of a title or alias. Use a more specific search term, or switch to advanced filters for exact matching on fields like language or release date.

### FAQ

| Question | Answer |
|---|---|
| Do I need a VNDB API key to use this scraper? | No. This Actor reads the public VNDB listings directly. You do not need to register an application or obtain an API token. |
| What is the difference between the search box and the advanced filters? | The search box performs a free-text match against visual novel titles and aliases. The advanced filters field accepts a raw VNDB Kana filter array, which lets you query by any supported field like language, original language, or platform using exact operators. |
| How many visual novels can I scrape in one run? | You can set the maximum up to 1,000,000 entries per run. The actual number returned depends on how many visual novels match your search or filter criteria. |
| What fields does the scraper return by default? | The Actor requests a standard set of fields including title, rating, vote count, release date, and tags. You can request additional fields like original language or length in minutes using the Extra fields input. |
| Can I filter by language, for example only English releases? | Yes. Use the advanced filters input with a raw VNDB filter expression like \["lang","=","en"] to return only visual novels that have an English release. |
| What does 'Search rank' sorting do? | Search rank ordering is only meaningful when you provide a search term. It returns results ordered by how well they match your query, with the most relevant visual novels first. |
| Can I export the data to Excel? | Yes. The Actor supports CSV, JSON, Excel, and XML export formats. Choose your preferred format when you start the run or download the dataset. |
| Does this scraper also get character or staff data? | This Actor focuses on visual novel entries. Character and staff data are separate VNDB resources. You can request additional fields that reference related entities, but full character scraping requires a different approach. |
| How do I write a raw VNDB filter expression? | VNDB uses a Kana filter syntax documented at api.vndb.org. A filter is a JSON array like \["olang","=","ja"] for Japanese originals. You can nest arrays with "and" and "or" predicates for complex queries. |
| Is there a rate limit I should worry about? | The Actor is designed to respect VNDB's servers. It runs at a steady pace and handles pagination automatically. For very large runs, the platform manages the request rate. |

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

## `search` (type: `string`):

Free text to search visual novels by title or alias, for example 'saya' or 'fate stay night'. Leave empty to browse all visual novels (optionally narrowed by the advanced filters below).

## `sort` (type: `string`):

Order of the returned visual novels. 'Search rank' is only meaningful when a search term is given.

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

How many visual novels to collect per run.

## `filters` (type: `array`):

Optional raw VNDB filter expression, applied instead of the Search box. Advanced. Provide a VNDB Kana filters array, for example \["lang","=","en"] for English releases or \["olang","=","ja"] for Japanese originals. See api.vndb.org for the full filter reference.

## `fields` (type: `string`):

Optional comma separated list of additional VNDB fields to request on top of the defaults, for example 'olang,length\_minutes,devstatus'. Advanced.

## Actor input object example

```json
{
  "search": "saya",
  "sort": "rating",
  "maxItems": 10
}
```

# Actor output Schema

## `results` (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 = {
    "search": "saya",
    "maxItems": 10
};

// Run the Actor and wait for it to finish
const run = await client.actor("parseforge/vndb-visual-novels-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 = {
    "search": "saya",
    "maxItems": 10,
}

# Run the Actor and wait for it to finish
run = client.actor("parseforge/vndb-visual-novels-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 '{
  "search": "saya",
  "maxItems": 10
}' |
apify call parseforge/vndb-visual-novels-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,parseforge/vndb-visual-novels-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/EZnOcarC722MyygJR/builds/ua6zG7VtwQU49ziXY/openapi.json