: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.

Design goals
Design overview
Limits

The following limits are enforced by the server, in order to limit the server resources and prevent abuse of this service.


Connection info:
Host
api.vndb.org (primary), beta.vndb.org (available for testing)
Port (tcp)
19534 ('VN')

Disclaimer

These notes should be obvious, but I'll point it out anyway.


Implementation tips

Like the disclaimer, these notes should be obvious, but it can't hurt to state them anyway.

:SUB:Request/response syntax

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:

request or command
Message sent from the client to the server.
response
Message sent from the server to the client.
whitespace
Any sequence of the following characters: space, tab, line feed and carriage return. (hexadecimal: 20, 09, 10, 0D, respectively). This is in line with the definition of whitespace in the JSON specification.
date
A string signifying a date (in particular: release date). The following formats are used: "yyyy" (when day and month are unknown), "yyyy-mm" (when day is unknown) "yyyy-mm-dd", and "tba" (To Be Announced). If the year is not known and the date is not "tba", the special value null is used.

Message format

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"
 }
 0x04
The 0x04 byte will be ommitted in the other examples in this document. It is however still required.

Filter string syntax

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' command
 login {"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:

protocol
An integer that indicates which protocol version the client implements. Must be 1.
client
A string identifying the client application. Between the 3 and 50 characters, must contain only alphanumeric ASCII characters, space, underscore and hyphens. When writing a client, think of a funny (unique) name and hardcode it into your application.
clientver
A positive number indicating the software version of the client.
username
String containing the username of the person using the client.
password
String, password of that user in plain text.

The server replies with either 'ok' (no arguments), or 'error' (see below).

: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):

page
integer, used for pagination. Page 1 (the default) returns the first 10 results (1-10), page 2 returns the following 10 (11-20), etc.
sort
string, the field to order the results by. The accepted field names differ per type, the default sort field is the ID of the database entry.
reverse
boolean, default false. Set to true to reverse the order of the results.

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 vn

The 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.
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. Please note that hotlinking is not allowed, so make sure to leave the HTTP Referer header empty when fetching the image.
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.

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
= !=
= != ~
 
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.
:SUBSUB:get release

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
= !=  
:SUBSUB:get producer

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 title, original and aliases fields.
:SUB:The 'error' response

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:

parse
Syntax error or unknown command.
missing
A JSON object argument is missing a required member. The name of which is given in the additional "field" member.
badarg
A JSON value is of the wrong type or in the wrong format. The name of the incorrect field is given in a "field" member.
needlogin
Need to be logged in to issue this command.
throttled
You have used too many server resources within a short time, and need to wait a bit before sending the next command. The type of throttle is given in the "type" member, and the "minwait" and "fullwait" members tell you how long you need to wait before sending the next command and when you can start bursting again (this is the recommended waiting time), respectively. Both values are in seconds, with one decimal after the point.
auth
(login) Incorrect username/password combination.
loggedin
(login) Already logged in. Only one successful login command can be issues on one connection.
sesslimit
(login) Too many open sessions for the current user.
gettype
(get) Unknown type argument to the 'get' command.
getinfo
(get) Unknown info flag to the 'get' command. The name of the unrecognised flag is given in an additional "flag" member.
filter
(get) Unknown filter field or invalid combination of field/operator/argument type. Includes three additional members: "field", "op" and "value" of the incorrect expression.
:SUB:Change Log

This section lists the changes made in each version of the VNDB code. Check out the announcements board for more information about updates.

2.12