:TITLE:Public Database API
This API is currently in development, pretty much everything is subject to change without notice.
This document describes the public API of VNDB and is intended to be read by
programmers. The API allows programs and websites to access (parts of) the VNDB
database without actually visiting a page on the website.
The following limits are enforced by the server, in order to limit the server resources and prevent abuse of this service.
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 int 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" and
"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 things 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 must have the following members:
The server replies with either 'ok' (no arguments), or 'error' (see below).
:SUB:The 'get' commandThis command is used to fetch data from the database. It accepts 3 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), and lastly a filter expression.
get type flags filters
Type and flags are unescaped strings. The only type currently accepted is 'vn'. 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 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 two members: 'num', which is an integer indicating the number of results returned, 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, "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.
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. |
platforms | basic | array of strings | no | Can be an empty array when unknown or nothing has been released yet. |
aliases | details | string | yes | Comma-separated list of aliases. |
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. |
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. |
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 |
= != = != ~ |
|
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 |
= != |
|
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. |
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: