UDP API DEV: Difference between revisions

From AniDB
Jump to navigation Jump to search
No edit summary
Line 22: Line 22:
* Exceptions are 200,201,271,272,504,? which returns additional data in the first line.
* Exceptions are 200,201,271,272,504,? which returns additional data in the first line.
== Data ==
== Data ==
=== ANIME : new ? high ===
=== ANIME : new ===
'''Description:'''<br>
'''Description:'''<br>
Retrieves most info available for a specific anime defined by either id or name.
Retrieves most info available for a specific anime defined by either id or name.
Line 46: Line 46:
   239|0|140|2|1000|10|855|3750|803|36|2002-2005|TV|Naruto|&#12490;&#12523;&#12488;||&#1504;&#1488;&#1512;&#1493;&#1496;&#1493;|NARUTO§&#1606;&#1575;&#1585;&#1608;&#1578;&#1608;|naruto tv§ntv|Action,Shounen,Past,...(cut)
   239|0|140|2|1000|10|855|3750|803|36|2002-2005|TV|Naruto|&#12490;&#12523;&#12488;||&#1504;&#1488;&#1512;&#1493;&#1496;&#1493;|NARUTO§&#1606;&#1575;&#1585;&#1608;&#1578;&#1608;|naruto tv§ntv|Action,Shounen,Past,...(cut)
'''Info:'''
'''Info:'''
* Login is required. (?)
* Synonyms and short names are separated with '§'
* Synonyms and short names are separated with '§'
* Genre names are separated with ',' and ordered by weight (desc).
* Genre names are separated with ',' and ordered by weight (desc).
Line 56: Line 55:
: On second thought, is a wide search really wanted or is 'WHERE lower(name)=' good enough?. About encodings, do you care to elaborate? --[[User:Epoximator|Epoximator]] 18:24, 25 November 2005 (CET)
: On second thought, is a wide search really wanted or is 'WHERE lower(name)=' good enough?. About encodings, do you care to elaborate? --[[User:Epoximator|Epoximator]] 18:24, 25 November 2005 (CET)


=== EPISODE : new ? high ===
=== EPISODE : new ===
'''Description:'''<br>
'''Description:'''<br>
Retrieves most info available for a specific episode defined by either id or anime name/id + epno.
Retrieves most info available for a specific episode defined by either id or anime name/id + epno.
Line 81: Line 80:
* epno includes special character and padding (only if not special atm)
* epno includes special character and padding (only if not special atm)


=== GROUP : new ? high ===
=== GROUP : new ===
'''Description:'''<br>
'''Description:'''<br>
Retrieves most info available for a specific group defined by either id or name.
Retrieves most info available for a specific group defined by either id or name.
Line 101: Line 100:
   < 250 GROUP
   < 250 GROUP
   566|860|398|48|503|Anime-Legion|A-L|#anime-legion@irc.irchighway.net|http://www.anime-legion.net
   566|860|398|48|503|Anime-Legion|A-L|#anime-legion@irc.irchighway.net|http://www.anime-legion.net
'''Info:'''
* Login is required. (?)


=== FILE: extend ? high ===
=== FILE: extend ===
'''Description:'''<br>
'''Description:'''<br>
Retrieves most available info for a specific file defined by id, size + ed2k or anime + group + epno.
Retrieves most available info for a specific file defined by id, size + ed2k or anime + group + epno.
Line 194: Line 191:
: I think it's a good idea. Modified a bit. --[[User:Epoximator|Epoximator]] 13:38, 26 November 2005 (CET)
: I think it's a good idea. Modified a bit. --[[User:Epoximator|Epoximator]] 13:38, 26 November 2005 (CET)


=== A4G : new ? questionable ===
=== A4G : not planned ===
=== G4A : new ? questionable ===
=== G4A : not planned ===
=== STITLE : new ? questionable ===
=== STITLE : not planned ===
:* included in ANIME?


== Mylist General ==
== Mylist General ==


=== MYLISTSTATS : new ? medium ===
=== MYLISTSTATS : new ===
'''Description:'''<br>
'''Description:'''<br>
Retrieves the most relevant figures related to your user account.
Retrieves the most relevant figures related to your user account.
Line 214: Line 210:
* all fields are int
* all fields are int


=== MYLISTLATEST : new ? not planned ===
=== MYLISTLATEST : not planned ===
'''Command String:'''
:* MYLISTLATEST
 
'''Possible Replies:'''
:* XXX MYLIST LATEST
:: {int4 fid}
:: {int4 fid}
:: ...


'''Info:'''
=== VOTE : new ===
:* Only once pr update ?
 
 
=== VOTE : new ? high ===
'''Description:'''<br>
'''Description:'''<br>
Votes for a specifed anime, episode or group defined by id or name.  
Votes for a specifed anime, episode or group defined by id or name.  
Line 262: Line 246:
* ename is '{str anime name}|{int4 epno}'
* ename is '{str anime name}|{int4 epno}'


=== RANDOM : new ? low ===
=== RANDOM : new ===
'''Command String:'''
'''Command String:'''
* RANDOMANIME type={int4 type}
* RANDOMANIME type={int4 type}
Line 272: Line 256:
* type: 0=from db, 1=watched, 2=unwatched, 3=all mylist
* type: 0=from db, 1=watched, 2=unwatched, 3=all mylist


=== CREQ : new ? not planned ===
=== CREQ : not planned ===
'''Command String:'''
* CREQ
 
'''Possible Replies:'''
* XXX CREQ
: ...


== Mylist Edit ==
== Mylist Edit ==
Line 342: Line 320:
* 'Hide myself in IRC stats' applies for this too.
* 'Hide myself in IRC stats' applies for this too.


=== LATEST : new ? not planned ===
=== LATEST : not planned ===


== RETURN CODES ==
== RETURN CODES ==

Revision as of 15:50, 1 December 2005

UDP DEF V0.03 DEV

  • chii powr / minichii
  • feel free to edit / comment / whatever
  • do use discussion
  • Exp will approve / disapprove
  • Epoximator will implement

General

  • All commands except PING requires login, meaning session tag must be set (s=xxxxx).
  • Possible return codes for all commands:
  • 600 INTERNAL SERVER ERROR
  • 601 ANIDB OUT OF SERVICE - TRY AGAIN LATER
  • 505 ILLEGAL INPUT OR ACCESS DENIED
  • 598 UNKNOWN COMMAND (sort of)
  • Additional return codes for all commands that require login:
  • 501 LOGIN FIRST
  • 506 INVALID SESSION
  • General return data:
 {three digit return code} {str return string}\n
 {data field 0}|{data field 1}|...|{data field n}
  • Exceptions are 200,201,271,272,504,? which returns additional data in the first line.

Data

ANIME : new

Description:
Retrieves most info available for a specific anime defined by either id or name.

Command String:
by aid

  • ANIME aid={int4 id}

by name

  • ANIME name={str name}

Possible Replies:

  • XXX NO SUCH ANIME
  • XXX ANIME
{int4 aid}|{int2 type}|{int4 eps}|{int4 ep count}|{int4 special cnt}|{int4 rating}|{int4 votes}|{int4 tmprating}|{int4 tmpvotes}|{int4 review rating average}|{int4 reviews}|{str year}|{str romaji}|{str kanji}|{str english}|{str other}|{str synonyms}|{str short names}{str genre list}
  • XXX ANIME BEST MATCH
{int4 aid}|{int2 type}|{int4 eps}|{int4 ep count}|{int4 special cnt}|{int4 rating}|{int4 votes}|{int4 tmprating}|{int4 tmpvotes}|{int4 review rating average}|{int4 reviews}|{str year}|{str romaji}|{str kanji}|{str english}|{str other}|{str synonyms}|{str short names}{str genre list}

Examples: (html escaped code intended)

 > ANIME name=tmm&s=xxxxx
 < 230 ANIME
 161|52|50|0|715|57|777|35|816|1|2002-2003|TV|Tokyo Mew Mew|東京ミュウミュウ||||TMM§mew|Cat Girls
 > ANIME name=ナルト&s=xxxxx
 < 230 ANIME
 239|0|140|2|1000|10|855|3750|803|36|2002-2005|TV|Naruto|ナルト||נארוטו|NARUTO§ناروتو|naruto tv§ntv|Action,Shounen,Past,...(cut)

Info:

  • Synonyms and short names are separated with '§'
  • Genre names are separated with ',' and ordered by weight (desc).
  • Categories?
  • By title: returns the most likely anime, i.e. only one

Comments:
I'd like this command to cope with a couple of different encodings when passed a title, and be explicit over whether it finds only one result or does a best-match guess. --Rar 04:51, 30 Oct 2005 (CET)

On second thought, is a wide search really wanted or is 'WHERE lower(name)=' good enough?. About encodings, do you care to elaborate? --Epoximator 18:24, 25 November 2005 (CET)

EPISODE : new

Description:
Retrieves most info available for a specific episode defined by either id or anime name/id + epno.

Command String:
by eid

  • EPISODE eid={int4 eid}

by anime and episode number

  • EPISODE anime={int4/str anime name or aid}&epno={int4 episode number}

Possible Replies:

  • XXX NO SUCH EPISODE
  • XXX EPISODE
{int4 eid}|{int4 aid}|{int4 length}|{int4 rating}|{int4 votes}|{str epno}|{str eng}|{str romaji}|{str kanji}

Examples:

 > EPISODE eid=1
 < 240 EPISODE
 1|1|24|400|4|01|Invasion|shinryaku|侵略
 
 > EPISODE anime=Seikai no Monshou&epno=2
 < 240 EPISODE
 2|1|24|750|2|02|Kin of the Stars|Hoshi-tachi no Kenzoku|星たちの眷族

Info:

  • length is in minutes
  • epno includes special character and padding (only if not special atm)

GROUP : new

Description:
Retrieves most info available for a specific group defined by either id or name.

Command String:
by gid

  • GROUP gid={int4 gid}

by name/shortname

  • GROUP name={str name}

Possible Replies:

  • XXX NO SUCH GROUP
  • XXX GROUP
{int4 gid}|{int4 rating}|{int4 votes}|{int4 acount}|{int fcount}|{str name}|{str short}|{str irc}|{str url}

Examples:

 > GROUP gid=1&s=xxxxx
 < 250 GROUP
 1|621|28|29|222|Animehaven|AH|#animehaven@irc.enterthegame.com|http://www.theanimehaven.com
 > GROUP name=a-l&s=xxxxx
 < 250 GROUP
 566|860|398|48|503|Anime-Legion|A-L|#anime-legion@irc.irchighway.net|http://www.anime-legion.net

FILE: extend

Description:
Retrieves most available info for a specific file defined by id, size + ed2k or anime + group + epno.

Command String:
by fid:

  • FILE fid={int4 id}[&code={int4}]

by size+ed2k hash:

  • FILE size={int4 size}&ed2k={str ed2khash}[&code={int4}]

by anime, group and epno

  • FILE anime={int4/str anime name or aid}&group={int4/str group name or gid}&epno{int4 episode number}[&code={int4}]

Possible Replies:

  • XXX FILE
{int4 fid}|{int4 aid}|{int4 eid}|{int4 gid}|{int4 lid}|{int4 state}|{int4 size}|{str ed2k}|{str default file name}
  • XXX FILE
{int4 fid}|{int4 aid}|{int4 eid}|{int4 gid}|{int4 lid}|...(data list)
  • XXX NO SUCH FILE

Info:

  • code is an integer where each bit corresponds to a data field related to the specified file (se below). The data list received is sorted in the same order as the table. code=-1 means retrieve all fields.

Code:

Bit Decimal Data field - Bit Decimal Data field
0 1 int2 state 16 65536 str epno
1 2 int4 size 17 131072 str ep name
2 4 str ed2k 18 262144 str ep japname
3 8 str md5 19 524288 not ep kanjiname
4 16 str sha1 20 1048576 int2 episodes
5 32 str crc 21 2097152 int2 ep count
6 64 str dub 22 4194304 str year
7 128 str sub 23 8388608 str anime type
8 256 str quality 24 16777216 str title romaji
9 512 str source 25 33554432 str title kanji
10 1024 str audio info 26 67108864 str title english
11 2048 str video info 27 134217728 str title other
12 4096 str video resolution 28 268435456 str synonyms
13 8192 str file type 29 536870912 str short names
14 16384 str group name 30 1073741824 str genre list
15 32768 str group short name 31 -2147483648 not used

Examples:

> FILE fid=15201&s=xxxxx
< 220 FILE
15201|74|445|41|1|242772540|a53c401ed95eaa502ba85acde773040c|Ai yori Aoshi - 1 - Relation - [Zhentarim DivX].ogm

> FILE fid=15201&data=-1&s=xxxxx
< 220 FILE
15201|74|445|41|1|242772540|a53c401ed95eaa502ba85acde773040c|a69c9ca88822338685f163db95da8231|842fc9060b4338757d0197a9f7bf0c79cf39a549|01ffc5f4|842fc9060b4338757d0197a9f7bf0c79cf39a549|dual (jap/eng)|english|very high|DVD|Ogg Vorbis|101|DivX5|1182|640x480|ogm|Zhentarim DivX|zx|24|24|2002|TV|Ai yori Aoshi|藍より青し|Bluer than Indigo|Azul||aya1§AYA§AiAo|

> FILE fid=83532&data=17006624&s=xxxxx
< 220 FILE
83532|896|26316|374|e1980142|KAA|S3|Ayu Mayu Theater 03|Kimi ga Nozomu Eien

> FILE anime=narutaru&group=triad&aone&epno=2&s=xxxxx
< t001 220 FILE
15459|782|8772|380|1|171298816|2c8a3b53d94d8579b9b81941c549e108|Narutaru - 02 - Catastrophe During the Daytime - [Triad & AonE].avi

Comments:
Pass a list of fields (limit e.g. 10 entries) and return content. This makes it possible to request new fields in the database without breaking API for older clients. On updates, only the list of possible fields need to be extendet. -- --Dinoex

I think it's a good idea. Modified a bit. --Epoximator 13:38, 26 November 2005 (CET)

A4G : not planned

G4A : not planned

STITLE : not planned

Mylist General

MYLISTSTATS : new

Description:
Retrieves the most relevant figures related to your user account.

Command String:

  • MYLISTSTATS

Possible Replies:

  • XXX MYLIST STATS

{animes}|{eps}|{files}|{size of files}|{added animes}|{added eps}|{added files}|{added groups}|{leech %}|{lame %}|{viewed % of db}|{mylist % of db}|{viewed % of mylist}|{number of viewed eps}|{votes}|{reviews}

Info:

  • all fields are int

MYLISTLATEST : not planned

VOTE : new

Description:
Votes for a specifed anime, episode or group defined by id or name.

Command String:
by id

  • VOTE type={int2 type}&id={int4 id}&value={int4 vote value}

by name

  • VOTE type={int2 type}&name={string name}&value={int4 vote value}

Possible Replies:

  • XXX VOTED
{str aname/ename/gname}
  • XXX VOTE FOUND
{str aname/ename/gname}|{vote value}
  • XXX VOTE UPDATED
{str aname/ename/gname}|{old vote value}
  • XXX VOTE REVOKED
{str aname/ename/gname}|{revoked vote value}
  • XXX NO SUCH VOTE
  • XXX INVALID VOTE TYPE
  • XXX INVALID VOTE VALUE
  • XXX PERMVOTE NOT ALLOWED
{str aname}
  • XXX ALREADY PERMVOTED
{str aname/ename/gname}

Info:

  • type: 1=anime, 2=anime tmpvote, 3=episode, 4=group
  • value: negative number means revoke, 0 means retrieve, 100-1000 are valid vote values, rest is illegal
  • votes will be updated automatically (that is no questions asked)
  • tmpvoting when there exist a perm vote is not possible
  • ename is '{str anime name}|{int4 epno}'

RANDOM : new

Command String:

  • RANDOMANIME type={int4 type}

Possible Replies:

  • XXX ANIME ... (see ANIME)

Info:

  • type: 0=from db, 1=watched, 2=unwatched, 3=all mylist

CREQ : not planned

Mylist Edit

MYLISTADD : extend

Command String:
by anime + group + epno

  • MYLISTADD anime={int/str anime name or aid}&group={int/str group name or gid}&epno={int4 episode number}[&state={int2 state}&viewed={boolean viewed}&source={str source}&storage={str storage}&other={str other}][&edit=1]

Possible Replies:

  • XXX MULTIPLE FILES FOUND
{int4 fid 1}|{int4 group name 1}
...
{int4 fid n}|{int4 group name n}


MYLISTDEL : extend

Command String:
by anime + group + epno

  • MYLISTDEL anime={int/str anime name or aid}&group={int/str group name or gid}&epno={int4 episode number}

Possible Replies:

  • XXX MULTIPLE FILES FOUND
{int4 fid 1}|{int4 group name 1}
...
{int4 fid n}|{int4 group name n}

Misc

STATS : new

Command String:

  • STATS

Possible Replies:

  • XXX STATS
{int4 animes)|{int4 eps}|{int4 files}|{int4 groups}|{int4 users}|{int4 creqs}

UPTIME : new

Command String:

  • UPTIME

Possible Replies:

  • XXX UPTIME
{int4 udpserver uptime in sec}

TOP : new

Command String:

  • TOP

Possible Replies:

  • XXX TOP
{str longest mylist}|{int count}
{str largest mylist}|{int count}
{str most lame files}|{int count}
{str most indep. user}|{int count}
{str biggest leecher}|{int count}
{str most anime added}|{int count}
{str most eps added}|{int count}
{str most files added}|{int count}
{str most groups added}|{int count}
{str most votes}|{int count}
{str most reviews}|{int count}

Info:

  • 'Hide myself in IRC stats' applies for this too.

LATEST : not planned

RETURN CODES

  • C : current, do not change
  • N : new
/*
 * POSITVE 2XX
 */
LOGIN_ACCEPTED				=200, //C
LOGIN_ACCEPTED_NEW_VER			=201, //C
LOGGED_OUT				=203, //C

MYLIST_ENTRY_ADDED			=210, //C
ENTRY_DELETED				=211, //C

FILE					=220, //C
MYLIST					=221, //C

ANIME					=230, //N
ANIME_BEST_MATCH			=231, //N
EPISODE					=240, //N
GROUP					=250, //N

VOTED					=260, //N
VOTE_FOUND				=261, //N
VOTE_UPDATED				=262, //N
VOTE_REVOKED				=263, //N

NOTIFICATION_ENABLED			=270, //C
PUSHACK_CONFIRMED			=280, //C
NOTIFYACK_SUCCESSFUL_M			=281, //C
NOTIFYACK_SUCCESSFUL_N			=282, //C
NOTIFICATION				=290, //C
NOTIFYLIST				=291, //C
NOTIFYGET_MESSAGE			=292, //C
NOTIFYGET_NOTIFY			=293, //C
SENDMSG_SUCCESSFUL			=294, //C

/*
 * AFFIRMATIVE/NEGATIVE 3XX
 */
PONG					=300, //C
FILE_ALREADY_IN_MYLIST			=310, //C
MYLIST_ENTRY_EDITED			=311, //C
NO_SUCH_FILE				=320, //C
NO_SUCH_ENTRY				=321, //C

NO_SUCH_ANIME				=330, //N
NO_SUCH_EPISODE				=340, //N
NO_SUCH_GROUP				=350, //N

NO_SUCH_VOTE				=360, //N
INVALID_VOTE_TYPE			=361, //N
INVALID_VOTE_VALUE			=362, //N
PERMVOTE_NOT_ALLOWED			=363, //N

NOTIFICATION_DISABLED			=370, //C
NO_SUCH_PACKET_PENDING			=380, //C
NO_SUCH_ENTRY_M				=381, //C
NO_SUCH_ENTRY_N				=382, //C

NO_SUCH_MESSAGE				=392, //C
NO_SUCH_NOTIFY				=393, //C
NO_SUCH_USER				=394, //C

NO_SUCH_DATA_ENTRY			=396, //N

/*
 * NEGATIVE 4XX
 */

NOT_LOGGED_IN				=403, //C
NO_SUCH_MYLIST_FILE			=410, //C
NO_SUCH_MYLIST_ENTRY			=411, //C


/*
 * CLIENT SIDE FAILURE 5XX
 */

LOGIN_FAILED				=500, //C
LOGIN_FIRST				=501, //C
ACCESS_DENIED				=502, //C
CLIENT_VERSION_OUTDATED			=503, //C
CLIENT_BANNED				=504, //C
ILLEGAL_INPUT_OR_ACCESS_DENIED		=505, //C
INVALID_SESSION				=506, //C
BANNED_FOR_FLOODING			=507, //C
UNKNOWN_COMMAND				=598, //C

/*
 * SERVER SIDE FAILURE 6XX
 */

INTERNAL_SERVER_ERROR			=600, //C
ANIDB_OUT_OF_SERVICE			=601, //C
API_VIOLATION				=666, //C