# VNDB Scraper: Visual Novels, Characters & Releases (`recordsdata/vndb-visual-novel-scraper`) Actor

Scrape VNDB, the Visual Novel Database: rank 66,000+ visual novels by rating, votes or date with tags, developers and platforms, plus every character and release edition per title. Filter by minimum votes. Export CSV, Excel, JSON. No login or API key.

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

## Pricing

Pay per event

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?

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

<p align="center">
  <img src="https://api.apify.com/v2/key-value-stores/AAm3a1h3Z9nYfrvh9/records/banner?v=3" alt="RecordsData" width="100%" />
</p>

## VNDB Scraper: Visual Novels, Characters & Releases

> VNDB Scraper exports visual novels from VNDB, the Visual Novel Database, with Bayesian rating, vote count, play length, developers, platforms and top tags. Filter by language, platform, votes, release date or a raw VNDB filter, and add characters and release editions as separate rows. Export CSV, Excel, JSON or XML through the official VNDB API. No login, no API key. $0.02 per visual novel on the Free plan, 128 MB memory, small runs finish in seconds.

VNDB Scraper searches and ranks the 66,000+ visual novels in the Visual Novel Database and returns clean rows instead of HTML. Built for game stores, localizers, researchers, media editors and fans who need structured visual novel data.

### 🔎 What does VNDB Scraper do?

- **Rank and search**: top-rated or most-voted titles with a minimum-votes filter, or search by title such as "Fate" or "Steins;Gate".
- **Filter**: by available language, original language, platform, release date, or any VNDB filter in the `filters` JSON array (tag, length, `or` groups).
- **Characters and releases**: role, sex, age, measurements, traits for characters; date, languages, platforms, engine, voiced level, age rating and store links for releases. They work for search results and VN IDs.
- **Extra columns**: `extraFields` adds titles, relations, screenshots, staff, voice actors and editions to each visual novel row, with no extra rows and no extra events.
- **Scrape by VNDB ID**: give `v11` or just `11` for full detail.

### 📊 What data can you extract from VNDB?

The dataset has 69 data columns plus three error columns. Main columns by record type:

| Record type | Main fields |
|---|---|
| Visual novel (`vn`) | vnId, title, originalTitle, aliases, url, released, rating, voteCount, averageVote, lengthMinutes, lengthCategory, devStatus, originalLanguage, languages, platforms, developers, tags, imageUrl, description, externalLinks |
| Character (`character`) | characterId, vnId, vnTitle, name, originalName, sex, gender, age, birthday, heightCm, weightKg, bustCm, waistCm, hipsCm, bloodType, role, traits, url |
| Release (`release`) | releaseId, vnId, vnTitle, title, released, releaseType, languages, platforms, minAge, official, freeware, uncensored, engine, voicedLevel, catalog, gtin, media, publishers, storeLinks, url |
| Optional `extraFields` | titles, relations, screenshots, staff, voiceActors, editions |

Every row also carries `recordType` and `scrapedAt`. Optional fields are left out when VNDB has no value. Columns `rating`, `lengthMinutes`, `age`, `heightCm`, `weightKg` and `minAge` can hold placeholder text such as "Not Rated", so parse them defensively. Descriptions, tags and traits can contain spoilers: VNDB marks them and the actor does not filter them.

### 🧾 Sample output of VNDB Scraper

Real row from a cloud run on 2026-10-03 (shortened):

```json
{
  "recordType": "vn",
  "vnId": "v20802",
  "title": "Rance X -Kessen-",
  "originalTitle": "Rance Ⅹ -決戦-",
  "released": "2018-02-23",
  "rating": 90.5,
  "voteCount": 1234,
  "originalLanguage": "ja",
  "languages": ["ja", "ko", "zh-Hans"],
  "developers": ["Alice Soft"],
  "tags": ["Multiple Endings", "One True End", "Family"]
}
```

A character row from the same run:

```json
{
  "recordType": "character",
  "characterId": "c15",
  "vnId": "v11",
  "vnTitle": "Fate/stay night",
  "name": "Emiya Shirou",
  "sex": "m",
  "age": 17,
  "role": "main",
  "traits": ["Red", "Short", "Straight"],
  "url": "https://vndb.org/c15"
}
```

### 💲 How much does it cost to scrape VNDB?

Pay per event, charged only after a row is saved. You are never charged for error rows, "not found" rows, empty searches or failed runs. Prices read live on 2026-10-10:

| Event | Free plan | Gold and above |
|---|---|---|
| Visual novel record | $0.02 | $0.01778 |
| Character record | $0.01111 | $0.01 |
| Release record | $0.01111 | $0.01 |

The `extraFields` columns add no events. Characters and releases found through a search use the same events as those found through VN IDs.

Worked example: 1,000 visual novels cost 1,000 x $0.02 = $20.00 on the Free plan ($17.78 on Gold), and 1,000 character or release rows cost 1,000 x $0.01111 = $11.11 each. One VN ID with 30 characters and 12 releases is 43 rows, about $0.49 on the Free plan. A test run of 10 visual novels costs $0.20. Use `maxItems` or the Apify "maximum charge per run" setting to cap spend; the run stops cleanly with "Stopped at your max charge limit". Free Apify accounts are limited to 10 rows per run. Default memory is 128 MB.

### 🚀 How to scrape VNDB (3 steps)

1. Open the actor and click **Try for free**.
2. Choose how to find titles: a search query, a sort order and minimum votes, or a list of VN IDs. Tick **Characters per VN** or **Releases per VN** if you want those rows.
3. Click **Start**, then download the dataset as CSV, Excel, JSON or XML.

### ⚙️ Input

| Field | Type | Default | What it does |
|---|---|---|---|
| `searchQuery` | string | empty | Title keyword. Empty ranks the whole database |
| `sortBy` | select | `rating` | `rating`, `votecount`, `released`, `title`, `id` or `searchrank` (needs a search query) |
| `sortDirection` | select | `auto` | `auto`, `asc` or `desc`; `auto` puts newest or most first, title A-Z |
| `minVotes` | integer | 100 | Skip titles with fewer votes |
| `releasedAfter` | string | empty | Date `YYYY-MM-DD`; only newer titles |
| `language` | select | `any` | Only titles available in this language (57 options) |
| `originalLanguage` | select | `any` | Only titles written in this language |
| `platform` | select | `any` | Only titles available on this platform (48 options) |
| `filters` | array | empty | Advanced VNDB filter as JSON, e.g. `["tag","=","g50"]` |
| `extraFields` | array | empty | Add `titles`, `relations`, `screenshots`, `staff`, `voiceActors`, `editions` |
| `vnIds` | array | empty | VNDB IDs such as `v11`, `11` or `00011`, looked up 50 per request |
| `includeCharacters` | boolean | false | Add character rows per visual novel |
| `includeReleases` | boolean | false | Add release rows per visual novel |
| `maxItems` | integer | 10 | Cap on total rows (visual novels, characters and releases) |

The `filters` shape is checked locally (at most 200 conditions, depth 8); VNDB checks field names and values. The `length` filter only accepts `=` with values 1 to 5; `>=` works only on numeric and date fields.

Example input for English visual novels on Windows:

```json
{ "language": "en", "platform": "win", "minVotes": 100, "maxItems": 20 }
```

### 📦 Output

One dataset, one row per visual novel, character or release, told apart by `recordType`. The Output tab has an overview table with cover, rating, votes, developers and a VNDB link. Searches with no matches end as SUCCEEDED with zero rows charged. Missing VN IDs get free `not-found` rows (the first 25 get their own row, the rest one summary row). Invalid input (malformed date, `searchrank` without a query, junk VN IDs, a rejected filter) ends as SUCCEEDED with one free error row (`errorType: invalid-input`).

### ⚖️ VNDB scraper vs alternatives

Read on 2026-10-10 on the Apify Store. I found one other VNDB actor, `parseforge/vndb-visual-novels-scraper`.

| | This actor | parseforge |
|---|---|---|
| Characters and releases | Yes, own rows with store links | Not scraped, its FAQ says |
| Raw VNDB filter | Yes, `filters` array | Yes, `filters` array |
| Language and platform inputs | Dedicated selects | Only through raw filter |
| Sorts | 6, with direction | 6 including search rank |
| Extra fields | `extraFields`, 6 groups | `fields` input |
| Price per 1,000 (Free) | $20.00 VN, $11.11 others | Header from $7.69, README $17.00 |

The other actor is cheaper on its header price, and its page shows a price mismatch ($7.69 header, $17.00 in the README), so check its Console before big runs. Choose this one for characters, releases, store links, ready-made language and platform filters or the extra columns. For plain lists the raw filters cover the same ground and the price decides. Neither page shows an only-new mode.

### 💡 Use cases

Licensing scouts, store curation by platform, editorial "best of the year" lists, localization gap lists and character datasets for NLP.

### 🧠 Tips

- **Start with a ranked run.** Leave `searchQuery` empty, keep `minVotes` at 100 and sort by `rating`; lower `minVotes` to 0 for obscure titles.
- **Watch the row cap.** `maxItems` counts every row type together, so a cap of 10 with one VN ID, characters and releases may give the visual novel plus nine characters and no releases.
- **Monitoring.** Schedule a monthly run with `releasedAfter` set to the first of the month and dedupe by `vnId`; there is no only-new mode.

### 🔌 Run via API, schedule and integrations

```bash
curl -X POST "https://api.apify.com/v2/acts/RecordsData~vndb-visual-novel-scraper/run-sync-get-dataset-items?token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sortBy":"rating","minVotes":100,"maxItems":10}'
```

Schedule runs and send results to Google Sheets, Zapier, Make or n8n.

### 🤖 VNDB Scraper MCP server for AI agents

AI agents can call this Actor through the Apify MCP server at `https://mcp.apify.com?tools=RecordsData/vndb-visual-novel-scraper`. Every input field has a default, so an agent can run it with an empty or partial input and get the top visual novels by rating.

Add this to your MCP client configuration (Claude Desktop, Cursor, VS Code or any client that supports remote MCP servers):

```json
{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com?tools=RecordsData/vndb-visual-novel-scraper"
    }
  }
}
```

Example agent prompt:

> Use the VNDB Scraper to list the 10 highest-rated visual novels with at least 500 votes, then fetch the characters of the top one (VN ID) and tell me which characters have the role main.

An agent should choose this Actor when it needs visual novel ratings, tags, developers, characters or release editions from VNDB. It takes the same fields as the input table and returns one dataset row per visual novel, character or release.

### 🛡️ Is it legal to scrape VNDB?

The actor reads VNDB's official public API within its documented rate limit. The API is free for non-commercial use on a best-effort basis, and the data is released under the ODbL database license plus the Database Contents License (attribution, share-alike); descriptions and images may carry separate licenses. Data from VNDB (vndb.org), used under its data license; credit VNDB when you republish it. The actor logs an attribution line on every run. The data is about games, not private individuals.

### ❓ Frequently asked questions

#### What is a VN ID on VNDB?

A VN ID is the number after the letter v in a vndb.org URL. For example, https://vndb.org/v11 is Fate/stay night, so its ID is v11. VNDB Scraper accepts v11 or just 11 in the vnIds input, and every output row includes vnId, so you can search first and then deep-dive.

#### What does the VNDB rating mean in VNDB Scraper output?

The rating field in VNDB Scraper is VNDB's Bayesian rating on a 0 to 100 scale, which corrects for titles with few votes so a title with three perfect votes does not outrank a well-known favorite. The voteCount field comes in the same row, so you can judge how reliable the rating is.

#### Why did my VNDB Scraper run return 0 results?

Your filters matched nothing. The default minVotes in VNDB Scraper is 100, so a rare visual novel can fall below it: set minVotes to 0 or lower it. A releasedAfter date that is too recent can also remove every title. The run still succeeds and charges nothing.

#### Why did my VNDB Scraper run fail?

VNDB Scraper fails with a plain message when the official VNDB API is down or unreachable and no rows could be delivered. Nothing is charged for a failed run, so you can start it again later. Rows already saved before a problem are kept, and you pay only for those.

#### What happens if I send an empty or invalid input to VNDB Scraper?

An empty input is safe: VNDB Scraper returns the top 10 visual novels by rating. A wrong sortBy value is rejected by the platform with a 400 before any run starts. Other mistakes, such as a malformed releasedAfter date, searchrank without a query, a rejected filter or junk VN IDs, end as SUCCEEDED with one free error row. Nothing is charged.

#### Does VNDB Scraper include adult visual novels?

VNDB lists visual novels of all age ratings, and VNDB Scraper does not hide any of them. Release rows carry the minAge field, so you can filter adult editions out of your export yourself. The data describes games and fictional characters, not private individuals.

#### Do characters and releases cost extra in VNDB Scraper?

Yes. Each character record ($0.01111 on the Free plan) and each release record ($0.01111) is its own billed event, on top of the $0.02 per visual novel. They are fetched only when you tick Characters per VN or Releases per VN, and they now apply to search results as well as VN IDs. They count toward maxItems, so you pay for them only when you ask and can cap the total.

#### Can I try VNDB Scraper for free?

Yes. Free Apify accounts can run VNDB Scraper with a limit of 10 rows per run, which at $0.02 per visual novel costs about $0.20. Paid Apify plans remove the 10-row limit and get lower per-row prices, down to $0.01778 per visual novel.

#### What happens if a VN ID does not exist in VNDB Scraper?

You get a free not found row for that ID, so you can see which IDs failed. Only the first 25 misses get their own row; the rest are counted in one summary row, and lookup stops after 1,000 misses. VNDB Scraper never charges for not found rows, error rows, empty searches or failed runs. IDs that exist are still scraped and billed normally.

#### How do I get English visual novels on Windows with VNDB Scraper?

Set language to en and platform to win in VNDB Scraper, add minVotes of 100 to skip obscure entries, and choose a sort such as rating. Every row returned is available in English on Windows. For anything the selects do not cover, such as a tag or length class, use the filters input; it is combined with your other inputs.

#### What can I put in the filters input of VNDB Scraper?

A JSON array in the VNDB filter grammar, for example \["tag","=","g50"], or \["and", ...] and \["or", ...] groups of conditions. The shape is checked locally (200 conditions, depth 8) and VNDB checks field names and values. A rejected filter ends the run with one free error row quoting the VNDB message, so nothing is charged and you can fix it.

### 🎮 Want more game data? Other RecordsData scrapers

- [GOG Games Scraper](https://apify.com/RecordsData/gog-games-scraper)
- [Steam Reviews Scraper](https://apify.com/RecordsData/steam-reviews-scraper)
- [Epic Games Store Scraper](https://apify.com/RecordsData/epic-games-store-scraper)

### 🛟 Support

Found a bug or a missing field? Open the Issues tab or write to contact.punkrecordsdata@gmail.com. Custom solutions on request.

Last updated: 2026-10-11

# Actor input Schema

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

Search visual novels by title keyword, alias or release title, for example "Fate" or "Steins;Gate". Leave empty to rank the whole VNDB database using the sort order, minimum votes, release date, language and platform filters below.

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

Sort order for search and browse results: rating (best Bayesian score first), votecount (most voted first), released (newest first), title (A-Z), id (oldest VNDB entry first) or searchrank (best match for the search query first, needs a search query). Use Sort direction to reverse any of them.

## `sortDirection` (type: `string`):

Auto keeps the natural direction of each sort order (best, most and newest first; A-Z; oldest ID first; best match first). Choose ascending or descending to flip it, for example oldest release first.

## `minVotes` (type: `integer`):

Only include visual novels with at least this many user votes on VNDB (0 = no filter). Raising it removes obscure entries with unreliable ratings.

## `releasedAfter` (type: `string`):

Only include visual novels released on or after this date, format YYYY-MM-DD (for example 2020-01-01). Leave empty for no date filter.

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

Only visual novels that have a release in this language (VNDB language code, for example English = en, Japanese = ja, Chinese simplified = zh-Hans). Machine translations are not counted by VNDB. "Any language" adds no filter.

## `originalLanguage` (type: `string`):

Only visual novels that were originally written in this language (for example Japanese = ja finds the Japanese originals, which is most of VNDB). "Any language" adds no filter.

## `platform` (type: `string`):

Only visual novels that have a release on this platform (VNDB platform code, for example Windows = win, Nintendo Switch = swi, PlayStation 4 = ps4, Android = and). "Any platform" adds no filter.

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

A raw filter of the VNDB Kana API as a JSON array, combined with AND with every other filter above. A single condition is \[name, operator, value], for example \["tag","=","g50"]. Combine conditions with "and" / "or", for example \["and",\["lang","=","en"],\["released",">=","2020"],\["length","=",4]]. Names include lang, olang, platform, released, rating, votecount, length, devstatus, tag, developer, release and character. Operators: = and != everywhere, >= > <= < only on numeric and date fields (VNDB names the field that does not accept one). Reference: https://api.vndb.org/kana#filters. VNDB rejects unknown names; the run then ends with one free error row that quotes VNDB.

## `extraFields` (type: `array`):

Add heavier columns to every visual novel row: titles (every language), relations (sequels, prequels, side stories), screenshots (links and content flags), staff (credits), voiceActors (character and actor) and editions. They come from the same request, so they cost no extra rows; they only make the rows bigger. Leave empty for the lean default rows.

## `vnIds` (type: `array`):

VNDB IDs of specific visual novels to fetch in detail, for example v11 or 11 (the number in a vndb.org/v11 URL). Up to 50 IDs are fetched per request. Combine with Characters per VN and Releases per VN to get their characters and releases too.

## `includeCharacters` (type: `boolean`):

Also scrape every character of each visual novel returned by the search or listed in VN IDs: name, role, sex, gender, age, birthday, measurements, blood type, traits and portrait. Each character is a separate billed row and counts towards Max Items.

## `includeReleases` (type: `boolean`):

Also scrape every release edition of each visual novel returned by the search or listed in VN IDs: date, languages, platforms, age rating, official or fan patch flag, uncensored flag, engine, voiced level, media, publishers and store links. Each release is a separate billed row and counts towards Max Items.

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

Maximum number of rows to return across visual novels, characters and releases. Free Apify users are limited to 10 rows per run; paid users can set up to 1,000,000.

## Actor input object example

```json
{
  "searchQuery": "",
  "sortBy": "rating",
  "sortDirection": "auto",
  "minVotes": 100,
  "releasedAfter": "",
  "language": "any",
  "originalLanguage": "any",
  "platform": "any",
  "filters": [],
  "extraFields": [],
  "vnIds": [],
  "includeCharacters": false,
  "includeReleases": false,
  "maxItems": 10
}
```

# Actor output Schema

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

Key fields per row

## `fullData` (type: `string`):

Complete dataset with all fields

# 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 = {
    "searchQuery": "",
    "releasedAfter": "",
    "filters": [],
    "maxItems": 10
};

// Run the Actor and wait for it to finish
const run = await client.actor("recordsdata/vndb-visual-novel-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 = {
    "searchQuery": "",
    "releasedAfter": "",
    "filters": [],
    "maxItems": 10,
}

# Run the Actor and wait for it to finish
run = client.actor("recordsdata/vndb-visual-novel-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 '{
  "searchQuery": "",
  "releasedAfter": "",
  "filters": [],
  "maxItems": 10
}' |
apify call recordsdata/vndb-visual-novel-scraper --silent --output-dataset

```

## MCP server setup

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