:TITLE:Public Database API :INC:index :SUB:Introduction
This document describes the public API of VNDB and is intended to be read by
programmers. This API allows programs and websites to access (parts of) the
VNDB database without actually visiting the website.
In addition to this real-time API, we also provide some information in the
form of database dumps.
The following limits are enforced by the server, in order to limit the server resources and prevent abuse of this service.
These limits may sound strict, but in practice you won't have to worry much about it. As long as your application properly waits when the server replies with a "throttle" error, everything will be handled automatically. In the event that your application does require more resources, don't hesitate to ask.
These notes should be obvious, but I'll point it out anyway.
Like the disclaimer, these notes should be obvious, but it can't hurt to state them anyway.
The VNDB API uses the JSON format for data in various places, this document assumes
you are familiar with it. See JSON.org for a quick
overview and RFC 4627
for the glory details.
The words object, array, value, string,
number and integer refer to the JSON data types. In addition the following
definitions are used in this document:
A message is formatted as a command or response name, followed by any number of
arguments, followed by the End Of Transmission character (04 in hexadecimal).
Arguments are separated by one or more whitespace characters, and any sequence
of whitespace characters is allowed before and after the message.
The command or response name is an unescaped string containing only lowercase
alphabetical ASCII characters, and indicates what kind of command or response
this message contains.
An argument can either be an unescaped string (not containing whitespace), any
JSON value, or a filter string. The following two examples demonstrate a
'login' command, with an object as argument. Both messages are equivalent, as
the whitespace is ignored. '0x04' is used to indicate the End Of Transmission
character.
login {"protocol":1,"username":"ayo"}0x04
login { "protocol" : 1, "username" : "ayo" } 0x04The 0x04 byte will be ommitted in the other examples in this document. It is however still required.
Some commands accept a filter string as argument. This argument is formatted
similar to boolean expressions in most programming languages. A filter consists
of one or more expressions, separated by the boolean operators "and" or
"or" (lowercase). Each filter expression can be surrounded by parentheses to
indicate precedence, the filter argument itself must be surrounded by parentheses.
An expression consists of a field name, followed by an
operator and a value. The field name must consist entirely of
lowercase alphanumeric characters and can also contain an underscore. The
operator must be one of the following characters: =, !=, <, <=, >,
>= or ~. The value can be any valid JSON value. Whitespace
characters are allowed, but not required, between all expressions, field names,
operators and values.
The following two filters are equivalent:
(title~"osananajimi"or(id=2))
( id = 2 or title ~ "osananajimi" )
More complex filters are also possible:
((platforms = ["win", "ps2"] or languages = "ja") and released > "2009-01-10")
See the individual commands for more details.
:SUB:The 'login' commandlogin {"protocol":1,"client":"test","clientver":0.1,"username":"ayo","password":"hi-mi-tsu!"}
Every client is required to login before issuing other commands. The login command accepts a JSON object as argument. This object has the following members:
The server replies with either 'ok' (no arguments), or 'error' (see below). Note that logging in using a username or password is optional, but some commands are only available when logged in.
:SUB:The 'dbstats' commandThis command gives the global database statistics that are visible in the main menu of the site. The command is simply:
dbstats
And the response has the following format:
dbstats stats
Where stats is a JSON object with integer values. Example response:
dbstats {"users":49084, "threads":3998, "tags":1627, "releases":28071, "producers":3456, "chars":14046, "posts":52470, "vn":13051, "traits":1272}:SUB:The 'get' command
This command is used to fetch data from the database. It accepts 4 arguments: the type of data to fetch (e.g. visual novels or producers), what part of that data to fetch (e.g. only the VN titles, or the descriptions and relations as well), a filter expression, and lastly some options.
get type flags filters options
type and flags are unescaped strings. The accepted values for type are documented below. flags is a comma-separated list of flags indicating what info to fetch. The filters, available flags and their meaning are documented separately for each type. The last options argument is optional, and influences the behaviour of the returned results. When present, options should be a JSON object with the following members (all are optional):
The following example will fetch basic information and information about the related anime of the visual novel with id = 17:
get vn basic,anime (id = 17)
The server will reply with a 'results' message, this message is followed by a JSON object describing the results. This object has three members: 'num', which is an integer indicating the number of results returned, 'more', which is true when there are more results available (i.e. increasing the page option described above will give new results) and 'items', which contains the results as an array of objects. For example, the server could reply to the previous command with the following message:
results {"num":1, "more":false, "items":[{ "id": 17, "title": "Ever17 -the out of infinity-", "original": null, "released": "2002-08-29", "languages": ["en","ja","ru","zh"], "platforms": ["drc","ps2","psp","win"],"anime": [] }]}
Note that the actual result from the server can (and likely will) be formatted differently and that the order of the members may not be the same. What each member means and what possible values they can have differs per type and is documented below.
:SUBSUB:get vnThe following members are returned from a 'get vn' command:
Member | Flag | Type | null | Description |
id | - | integer | no | Visual novel ID |
title | basic | string | no | Main title |
original | basic | string | yes | Original/official title. |
released | basic | date (string) | yes | Date of the first release. |
languages | basic | array of strings | no | Can be an empty array when nothing has been released yet. |
orig_lang | basic | array of strings | no | Language(s) of the first release. Can be an empty array. |
platforms | basic | array of strings | no | Can be an empty array when unknown or nothing has been released yet. |
aliases | details | string | yes | Aliases, separated by newlines. |
length | details | integer | yes | Length of the game, 1-5 |
description | details | string | yes | Description of the VN. Can include formatting codes as described in d9.3. |
links | details | object | no |
Contains the following members: "wikipedia", string, name of the related article on the English Wikipedia. "encubed", string, the URL-encoded tag used on encubed. "renai", string, the name part of the url on renai.us. All members can be null when no links are available or known to us. |
image | details | string | yes | HTTP link to the VN image. |
image_nsfw | details | boolean | no | Whether the VN image is flagged as NSFW or not. |
anime | anime | array of objects | no |
(Possibly empty) list of anime related to the VN, each object has the following members: "id", integer, AniDB ID "ann_id", integer, AnimeNewsNetwork ID "nfo_id", string, AnimeNfo ID "title_romaji", string "title_kanji", string "year", integer, year in which the anime was aired "type", string All members except the "id" can be null. Note that this data is courtesy of AniDB, and may not reflect the latest state of their information due to caching. |
relations | relations | array of objects | no |
(Possibly empty) list of related visual novels, each object has the following members: "id", integer "relation", string, relation to the VN "title", string, (romaji) title "original", string, original/official title, can be null. |
tags | tags | array of arrays | no |
(Possibly empty) list of tags linked to this VN. Each tag is represented as
an array with three elements: tag id (integer), score (number between 0 and 3), spoiler level (integer, 0=none, 1=minor, 2=major) Only tags with a positive score are included. Note that this list may be relatively large - more than 50 tags for a VN is quite possible. General information for each tag is available in the tags dump. Keep in mind that it is possible that a tag has only recently been added and is not available in the dump yet, though this doesn't happen often. |
popularity | stats | number | no | Between 0 (unpopular) and 100 (most popular). |
rating | stats | number | no | Bayesian rating, between 1 and 10. |
votecount | stats | integer | no | Number of votes. |
Sorting is possible on the 'id', 'title' and 'released' fields.
'get vn' accepts the following filter expressions:
Field | Value | Operators | |
id | integer array of integers |
= != > >= < <= = != |
When you need to fetch info about multiple VNs, it is recommended to do so in one command using an array of integers as value. e.g. (id = [7,11,17]). |
title | string | = != ~ | |
original | null string |
= != = != ~ |
|
firstchar | null string |
= != = != |
Filter by the first character of the title, similar to the VN browser interface. The character must either be a lowercase 'a' to 'z', or null to match all titles not starting with an alphabetic character. |
released | null date (string) |
= != = != > >= < <= |
Note that matching on partial dates (released = "2009") doesn't do what you want, use ranges instead, e.g. (released > "2008" and released <= "2009"). |
platforms | null string array of strings |
= != |
|
languages | null string array of strings |
= != |
|
orig_lang | string array of strings |
= != | |
search | string | ~ | This is not an actual field, but performs a search on the titles of the visual novel and its releases. Note that the algorithm of this search may change and that it can use a different algorithm than the search function on the website. |
Returned members:
Member | Flag | Type | null | Description |
id | - | integer | no | Release ID |
title | basic | string | no | Release title (romaji) |
original | basic | string | yes | Original/official title of the release. |
released | basic | date (string) | yes | Release date |
type | basic | string | no | "complete", "partial" or "trial" |
patch | basic | boolean | no | |
freeware | basic | boolean | no | |
doujin | basic | boolean | no | |
languages | basic | array of strings | no | |
website | details | string | yes | Official website URL |
notes | details | string | yes | Random notes, can contain formatting codes as described in d9.3 |
minage | details | integer | yes | Age rating, 0 = all ages. |
gtin | details | string | yes | JAN/UPC/EAN code. This is actually an integer, but formatted as a string to avoid an overflow on 32bit platforms. |
catalog | details | string | yes | Catalog number. |
platforms | details | array of strings | no | Empty array when platform is unknown. |
media | details | array of objects | no |
Objects have the following two members: "medium", string "qty", integer, the quantity. null when it is not applicable for the medium. An empty array is returned when the media are unknown. |
vn | vn | array of objects | no | Array of visual novels linked to this release. Objects have the following members: id, title and original. These are the same as the members of the "get vn" command. |
producers | producers | array of objects | no |
(Possibly empty) list of producers involved in this release. Objects have the following members: "id", integer "developer", boolean, "publisher", boolean, "name", string, romaji name "original", string, official/original name, can be null "type", string, producer type |
Sorting is possible on the 'id', 'title' and 'released' fields.
Accepted filters:
Field | Value | Operators | |
id | integer array of integers |
= != > >= < <= = != |
|
vn | integer | = | Find releases linked to the given visual novel ID. |
producer | integer | = | Find releases linked to the given producer ID. |
title | string | = != ~ | |
original | null string |
= != = != ~ |
|
released | null date (string) |
= != = != > >= < <= |
Note about released filter for the vn type also applies here. |
patch | boolean | = | |
freeware | boolean | = | |
doujin | boolean | = | |
type | string | = != | |
gtin | int | = != | Value can also be escaped as a string (if you risk an integer overflow otherwise) |
catalog | string | = != | |
languages | string array of strings |
= != |
Returned members:
Member | Flag | Type | null | Description |
id | - | integer | no | Producer ID |
name | basic | string | no | (romaji) producer name |
original | basic | string | yes | Original/official name |
type | basic | string | no | Producer type |
language | basic | string | no | Primary language |
links | details | object | no |
External links, object has the following members: "homepage", official homepage, "wikipedia", title of the related article on the English wikipedia. Both values can be null. |
aliases | details | string | yes | Comma separated list of alternative names |
description | details | string | yes | Description/notes of the producer, can contain formatting codes as described in d9.3 |
relations | relations | array of objects | no |
(possibly empty) list of related producers, each object has the following members: "id", integer, producer ID, "relation", string, relation to the current producer, "name", string, "original", string, can be null |
Sorting is possible on the 'id' and 'name' fields.
The following filters are recognised:
Field | Value | Operators | |
id | integer array of integers |
= != > >= < <= = != |
|
name | string | = != ~ | |
original | null string |
= != = != ~ |
|
type | string | = != | |
language | string array of strings |
= != | |
search | string | ~ | Not an actual field. Performs a search on the name, original and aliases fields. |
Returned members:
Member | Flag | Type | null | Description |
id | - | integer | no | Character ID |
name | basic | string | no | (romaji) name |
original | basic | string | yes | Original (kana/kanji) name |
gender | basic | string | yes | "m" (male), "f" (female) or "b" (both) |
bloodt | basic | string | yes | Blood type, "a", "b", "ab" or "o" |
birthday | basic | array | no | Array of two numbers: day of the month (1-31) and the month (1-12). Either can be null. |
aliases | details | string | yes | Alternative names, separated with a newline. |
description | details | string | yes | Description/notes, can contain formatting codes as described in d9.3. May also include [spoiler] tags! |
image | details | string | yes | HTTP link to the character image. Always (supposed to be) SFW. |
bust | meas | integer | yes | cm |
waist | meas | integer | yes | cm |
hip | meas | integer | yes | cm |
height | meas | integer | yes | cm |
weight | meas | integer | yes | kg |
traits | traits | array of arrays | no | (Possibly empty) list of traits linked to this character. Each trait is represented as an array of two elements: The trait id (integer) and the spoiler level (integer, 0-2). General information for each trait is available in the traits dump. |
Sorting is possible on the 'id' and 'name' fields.
The following filters are recognised:
Field | Value | Operators | |
id | integer array of integers |
= != > >= < <= = != |
|
name | string | = != ~ | |
original | null string |
= != = != ~ |
|
search | string | ~ | Not an actual field. Performs a search on the name, original and aliases fields. |
vn | id | = | Find characters linked to the given visual novel ID. Note that this may also include characters that are normally hidden by spoiler settings. |
Provides access to the votes of the logged in user. As such, this command is only available when logged in as a user.
Returned members:
Member | Flag | Type | null | Description |
vn | basic | integer | no | Visual Novel ID |
vote | basic | integer | no | In the range of 10 (lowest) to 100 (highest). These are displayed on the site as a fractional number between 1 and 10. |
added | basic | integer | no | Unix timestamp of when this vote has been added. |
The returned list is always sorted on the 'vn' field.
The following filters are recognised:
Field | Value | Operators | |
uid | integer | = | This filter must be present. The special value '0' is recognized as the currently logged in user. |
Note: It's possible that a user has voted on a VN that has been deleted. The
vote is still included this list, but a 'get vn' command on its id will not
return anything.
Note#2: This command will not return any results for users who have their vote
list hidden from the public in their preferences, except when the user itself
has logged into the API and the uid filter is 0.
Provides access to the VN list of the logged in user. As such, this command is only available when logged in as a user.
Returned members:
Member | Flag | Type | null | Description |
vn | basic | integer | no | Visual Novel ID |
status | basic | integer | no | 0=Unknown, 1=playing, 2=finished, 3=stalled, 4=dropped. |
added | basic | integer | no | Unix timestamp of when this item has been added. |
notes | basic | string | yes | User-set notes |
The returned list is always sorted on the 'vn' field.
The following filters are recognised:
Field | Value | Operators | |
uid | integer | = | This filter must be present, and currently must be '0' (= logged in user) |
The notes mentioned under 'get votelist' also apply here.
:SUBSUB:get wishlistProvides access to the wish list of the logged in user. As such, this command is only available when logged in as a user.
Returned members:
Member | Flag | Type | null | Description |
vn | basic | integer | no | Visual Novel ID |
priority | basic | integer | no | 0=high, 1=medium, 2=low, 3=blacklist. |
added | basic | integer | no | Unix timestamp of when this item has been added. |
The returned list is always sorted on the 'vn' field.
The following filters are recognised:
Field | Value | Operators | |
uid | integer | = | This filter must be present, and currently must be '0' (= logged in user) |
The notes mentioned under 'get votelist' also apply here.
:SUB:The 'set' commandThe set command can be used to modify stuff in the database. It can only be used when logged in as a user. The command has the following syntax:
set type id fields
Here, type is similar to the type argument to the 'get' command,
id is the (integer) identifier of the database entry to change, and
fields is an object with the fields to set or modify. If the
fields object is not present, the set command works as a 'delete'. The
interpretation of the id and fields arguments depend on the
type, and are documented in the sections below.
But before that, let me present some examples to get a feel on what the
previous paragraph meant. The following example adds a '10' vote on v17, or changes the vote to a 10 if a previous vote was
already present:
set votelist 17 {"vote":100}
And here's how to remove the previous vote:
set votelist 17
'set' replies with a simple 'ok' on success, or with an 'error' (see below) on failure. Note that, due to my laziness, no error is currently returned if the identifier does not exist. So voting on a VN that does not exist will return an 'ok', but no vote is actually added. This behaviour may change in the future. Note that this API doesn't care whether the VN has been deleted or not, so you can manage votes and stuff for deleted VNs (Which isn't very helpful, because 'get vn' won't return a thing for deleted VNs).
:SUBSUB:set votelistThis command facilitates adding, removing and modifying votes. The identifier argument is the visual novel ID, and the following fields are recognized:
Field | Type | Description |
vote | integer | Same as the 'vote' member returned by 'get votelist', in the range 10 to 100. This field has no default; it must always be present. |
The 'added' member returned by 'get votelist' is, as its name implies, only set when the vote is added. Changing an existing vote will not update the 'added' field.
:SUBSUB:set vnlistThis command facilitates adding, removing and modifying your VN list. The identifier argument is the visual novel ID, and the following fields are recognized:
Field | Type | Description |
status | integer | Same as the 'status' member returned by 'get vnlist'. Default: 0 |
notes | string | Same as the 'notes' member returned by 'get vnlist'. An empty string is considered equivalent to 'null'. A newline is currently not allowed because the web interface won't handle them well. Default: null. |
Sames notes about the 'added' member for 'set votelist' applies here.
Also note that, when removing a vnlist item, any releases associated with the
VN will be removed from the users' list as well. The release list
functionality is not currently exposed to the API, so this will only be
visible when the web interface is used.
This command facilitates adding, removing and modifying VNs from your wishlist. The identifier argument is the visual novel ID, and the following fields are recognized:
Field | Type | Description |
priority | integer | Same as the 'priority' member returned by 'get wishlist'. |
Sames notes about the 'added' member for 'set votelist' applies here.
Every command to the server can receive an 'error' response, this response has one argument: a JSON object containing at least a member named "id", which identifies the error, and a "msg", which contains a human readable message explaining what went wrong. Other members are also possible, depending on the value of "id". Example error message:
error {"id":"parse", "msg":"Invalid command or argument"}
Note that the value of "msg" is not directly linked to the error identifier: the message explains what went wrong in more detail, there are several different messages for the same id. The following error identifiers are currently defined:
This section lists the changes made in each version of the VNDB code. Check out the announcements board for more information about updates.
2.23