UDP API DEV: Difference between revisions

From AniDB
Jump to navigation Jump to search
mNo edit summary
No edit summary
Line 1: Line 1:
'''UDP DEF V0.03 DEV'''
{{TOCright}}
* chii powr / minichii
 
'''[[UDP_API_Definition|UDP API]] DEVELOPMENT'''
* add feature requests here
* feel free to edit / comment / whatever
* feel free to edit / comment / whatever
* do use discussion
* [[User:Exp|Exp]] will approve / disapprove
* [[User:Epoximator|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:'''<br>
Retrieves most info available for a specific anime defined by either id or name.
'''Command String:'''<br>
by aid
* ANIME aid={int4 id}
by name
* ANIME aname={str anime name}


== Data Commands ==
=== [[UDP_API_Definition#ANIME:_Retrieves_data_for_a_specific_anime|ANIME]] ===
'''Possible Replies:'''
'''Possible Replies:'''
* XXX NO SUCH ANIME
* XXX ANIME
: {int4 aid}|{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 type}|{str romaji}|{str kanji}|{str english}|{str other}|{str short names}|{str synonyms}|{str category list}
* XXX ANIME BEST MATCH
* XXX ANIME BEST MATCH
: ...
: ...
'''Info:'''
* Synonyms and short names are separated with '
* Category names are separated with ',' and ordered by weight (desc).
* No support for genres.
* By title: returns the most likely anime, i.e. only one
* NOTE: The category list is the first data to be truncated if needed. And then: synonym list, short name list. This applies for the FILE command too.
'''Examples:''' (html escaped code intended)
  > ANIME aname=tmm&s=xxxxx
  < 230 ANIME
  161|52|50|0|715|57|777|35|816|1|2002-2003|TV|Tokyo Mew Mew|&#26481;&#20140;&#12511;&#12517;&#12454;&#12511;&#12517;&#12454;||||TMM'mew|Cat Girls
 
  > ANIME aname=&#12490;&#12523;&#12488;&s=xxxxx
  < 230 ANIME
  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)
'''Comments:'''<br>
'''Comments:'''<br>
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. --[[User:Rar|Rar]] 04:51, 30 Oct 2005 (CET)
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. --[[User:Rar|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? --[[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 ===
=== [[UDP_API_Definition#EPISODE:_Retrieves_data_for_a_specific_episode|EPISODE]] ===
'''Description:'''<br>
=== [[UDP_API_Definition#GROUP:_Retrieves_data_for_a_specific_group|GROUP]] ===
Retrieves most info available for a specific episode defined by either id or anime name/id + epno.
=== [[UDP_API_Definition#FILE:_Retrieve_File_Data|FILE]] ===
 
'''Command String:'''<br>
by eid
* EPISODE eid={int4 eid}
by anime and episode number
* EPISODE aname={str anime name}&epno={int4 episode number}
* EPISODE aid={int4 anime id}&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}
'''Info:'''
* length is in minutes
* epno includes special character (only if special) and padding (only if normal)
'''Examples:''' (html escaped code intended)
  > EPISODE eid=1&s=xxxxx
  < 240 EPISODE
  1|1|24|400|4|01|Invasion|shinryaku|侵略
 
  > EPISODE aname=Seikai no Monshou&epno=2&s=xxxxx
  < 240 EPISODE
  2|1|24|750|2|02|Kin of the Stars|Hoshi-tachi no Kenzoku|星たちの眷族
 
=== GROUP : new ===
'''Description:'''<br>
Retrieves most info available for a specific group defined by either id or name.
 
'''Command String:'''<br>
by gid
* GROUP gid={int4 gid}
by name/shortname
* GROUP gname={str group 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 gname=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:'''<br>
Retrieves most available info for a specific file defined by id, size + ed2k or anime + group + epno.
 
'''Command String:'''<br>
by fid:
* FILE fid={int4 id}[&fcode={int4}&acode={int4}]
by size+ed2k hash:
* FILE size={int4 size}&ed2k={str ed2khash}[&fcode={int4}&acode={int4}]
by anime, group and epno
* FILE aname={str anime name}&gname={str group name}&epno={int4 episode number}[&fcode={int4}&acode={int4}]
* FILE aname={str anime name}&gid={int4 group id}&epno={int4 episode number}[&fcode={int4}&acode={int4}]
* FILE aid={int4 anime id}&gname={str group name}&epno={int4 episode number}[&fcode={int4}&acode={int4}]
* FILE aid={int4 anime id}&gid={int4 group id}&epno={int4 episode number}[&fcode={int4}&acode={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}|...(data list)
* XXX NO SUCH FILE
 
'''Info:'''
* fcode and acode is integers 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 tables (and fcode before acode). {f|a}code=-1 means retrieve all fields.
 
'''fcode:'''
{| cellpadding="0" align="center"
! width="40"|Bit
! width="80"|Decimal
! width="140"|Data field
! width="50"|-
! width="40"|Bit
! width="80"|Decimal
! width="140"|Data field
|- style="background-color: #eee;"
|0 ||1 || not used || || 16 || 65536 || str dub language
|-
|1 ||2 || int4 aid || || 17 || 131072 || str sub language
|- style="background-color: #eee;"
|2 ||4 || int4 eid || || 18 || 262144 || str quality
|-
|3 ||8 || int4 gid ||  || 19 || 524288 || str source
|- style="background-color: #eee;"
|4 ||16 || int4 lid || || 20 || 1048576 || str audio codec
|-
|5 ||32 || not used || || 21 || 2097152 || int4 audio bitrate
|- style="background-color: #eee;"
|6 ||64 || not used || || 22 || 4194304 || str video codec
|-
|7 ||128 || not used || || 23 || 8388608 || int4 video bitrate
|- style="background-color: #eee;"
|8 ||256 || int2 status || || 24 || 16777216 || str video resolution
|-
|9 ||512 || int4 size || || 25 || 33554432 || str file type (extension)
|- style="background-color: #eee;"
|10 ||1024 || str ed2k || || 26 || 67108864 || int4 length in seconds
|-
|11 ||2048 || str md5 || || 27 || 134217728 || not used
|- style="background-color: #eee;"
|12 ||4096 || str sha1 || || 28 || 268435456 || not used
|-
|13 ||819 || str crc32 || || 29 || 536870912 || not used
|- style="background-color: #eee;"
|14 ||16384 || not used || || 30 || 1073741824 || not used
|-
|15 ||32768 || not used || || 31 || -2147483648 || not used
|}
'''acode:'''
{| cellpadding="0" align="center"
! width="40"|Bit
! width="80"|Decimal
! width="140"|Data field
! width="50"|-
! width="40"|Bit
! width="80"|Decimal
! width="140"|Data field
|- style="background-color: #eee;"
|0 ||1 || str group name || || 16 || 65536 || int4 anime total episodes
|-
|1 ||2 || str group short name || || 17 || 131072 || int4 last episode nr (highest, not special)
|- style="background-color: #eee;"
|2 ||4 || not used || || 18 || 262144 || str year
|-
|3 ||8 || not used ||  || 19 || 524288 || str type
|- style="background-color: #eee;"
|4 ||16 || not used || || 20 || 1048576 || str romaji name
|-
|5 ||32 || not used || || 21 || 2097152 || str kanji name
|- style="background-color: #eee;"
|6 ||64 || not used || || 22 || 4194304 || str english name
|-
|7 ||128 || not used || || 23 || 8388608 || str other name
|- style="background-color: #eee;"
|8 ||256 || str epno || || 24 || 16777216 || str short name list
|-
|9 ||512 || str ep name || || 25 || 33554432 || str synonym list
|- style="background-color: #eee;"
|10 ||1024 || str ep romaji name || || 26 || 67108864 || str category list
|-
|11 ||2048 || str ep kanji name || || 27 || 134217728 || not used
|- style="background-color: #eee;"
|12 ||4096 || not used || || 28 || 268435456 || not used
|-
|13 ||819 || not used || || 29 || 536870912 || not used
|- style="background-color: #eee;"
|14 ||16384 || not used || || 30 || 1073741824 || not used
|-
|15 ||32768 || not used || || 31 || -2147483648 || not used
|}
'''Examples:''' (html escaped code intended)
<pre>
> 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&fdata=-1&adata=-1&s=xxxxx
< 220 FILE
15201|74|445|41|0|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 aname=narutaru&gname=triad&amp;aone&epno=2&s=xxxxx
< t001 220 FILE
15459|782|8772|380|1|171298816|2c8a3b53d94d8579b9b81941c549e108|Narutaru - 02 - Catastrophe During the Daytime - [Triad & AonE].avi
</pre>
'''Comments:'''<br>
'''Comments:'''<br>
Pass a list of fields (limit e.g. 10 entries)
Pass a list of fields (limit e.g. 10 entries)
Line 237: Line 25:
: 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 : not planned ===
== Mylist Commands ==
=== G4A : not planned ===
=== STITLE : not planned ===
 
== Mylist General ==
 
=== MYLIST : extend ===
'''Command String:'''<br>
by anime + group + epno
* MYLIST aname={str anime name}&gname={str group name}&epno={int epno}
'''Possible Replies:'''<br>
when multiple files found
* XXX MULTIPLE FILES FOUND
: {str eps with state unknown}|{str eps with state on hhd}|{str eps with state on cd}|{str eps with state deleted}|{str watched eps}|{str group 1 short name}|{str eps for group 1}|...|{str group N short name}|{str eps for group N}
'''Info:'''
* eps is a list of episodes, e.g. "1-12,14-16,T1"
'''Example:'''
  > MYLIST aname=gits sac&s=xxxxx
  <322 MULTIPLE FILES FOUND
  |1-26,S2-S27|1-26|||V-A|S2-S27|LMF|20-26|KAA|1-12,21-23|anime_fin|1-26|AonE|1-19|Anime-MX|1-3,17-20
 
=== MYLISTSTATS : new ===
'''Description:'''<br>
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:'''<br>
Votes for a specifed anime, episode or group defined by id or name (epno).
 
'''Command String:'''<br>
by id
* VOTE type={int2 type}&id={int4 id}[&value={int4 vote value}&epno={int4 episode number}]
by name
* VOTE type={int2 type}&name={string name}[&value={int4 vote value}&epno={int4 episode number}]
 
'''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=group
* for episode voting add epno on type=1
* value: negative number means revoke, 0 means retrieve (default), 100-1000 are valid vote values, rest is illegal
* votes will be updated automatically (no questions asked)
* tmpvoting when there exist a perm vote is not possible
 
=== 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:'''<br>
by anime + group + epno
* MYLISTADD aname={str anime name}[&gname={str group name}&epno={int4 episode number}][...]
* MYLISTADD aname={str anime name}[&gid={int4 group id}&epno={int4 episode number}][...]
* MYLISTADD aid={int4 anime id}[&gname={str group name}&epno={int4 episode number}][...]
* MYLISTADD aid={int4 anime id}[&gid={int4 group id}&epno={int4 episode number}][&state={int2 state}&viewed={boolean viewed}&source={str source}&storage={str storage}&other={str other}][&edit=1]
'''Possible Replies:'''<br>
when edit=1
* XXX MYLIST ENTRY EDITED
: {int4 number of entries edited}
when edit=0
* XXX MYLIST ENTRY ADDED
: {int4 number of entries added}
* XXX MULTIPLE FILES FOUND
: {int4 fid 1}|{int4 group name 1}
: ...
: {int4 fid n}|{int4 group name n}
'''Info:'''
* epno=0 means all eps (default), negative numbers means upto. (-12 -> upto 12)
* group is optional only when edit=1, meaning you can't add every file for an anime
 
=== MYLISTDEL : extend ===
'''Command String:'''<br>
by anime + group + epno
* MYLISTDEL aname={str anime name}[&gname={str group name}&epno={int4 episode number}]
* MYLISTDEL aname={str anime name}[&gid={int4 group id}&epno={int4 episode number}]
* MYLISTDEL aid={int4 anime id}[&gname={str group name}&epno={int4 episode number}]
* MYLISTDEL aid={int4 anime id}[&gid={int4 group id}&epno={int4 episode number}]
'''Possible Replies:'''<br>
* XXX ENTRY DELETED
: {int4 number of entries}
'''Info:'''
* epno=0 means all eps (default), negative numbers means upto. (-12 -> upto 12)
* group is optional
* command will delete all enties found
 
== 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
 
<pre>
/*
* POSITVE 2XX
*/
LOGIN_ACCEPTED =200, //C
LOGIN_ACCEPTED_NEW_VER =201, //C
LOGGED_OUT =203, //C
STATS =206, //N
TOP =207, //N
UPTIME =208, //N
 
MYLIST_ENTRY_ADDED =210, //C
ENTRY_DELETED =211, //C
 
FILE =220, //C
MYLIST =221, //C
MYLIST_STATS =222, //N
 
ANIME =230, //N
ANIME_BEST_MATCH =231, //N
RANDOMANIME =232, //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
MULTIPLE_FILES_FOUND =322, //N
 
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
ALREADY_PERMVOTED =364, //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


/*
=== MYLIST ===
* SERVER SIDE FAILURE 6XX
=== MYLISTSTATS ===
*/
=== MYLISTLATEST ===
=== VOTE ===
=== RANDOM ===
=== MYLISTADD ===
=== MYLISTDEL ===


INTERNAL_SERVER_ERROR =600, //C
== Misc Commands ==
ANIDB_OUT_OF_SERVICE =601, //C
=== STATS ===
API_VIOLATION =666, //C
=== UPTIME ===
</pre>
=== TOP ===
=== LATEST ===




[[Category:Development]]
[[Category:Development]]

Revision as of 17:22, 13 January 2006

UDP API DEVELOPMENT

  • add feature requests here
  • feel free to edit / comment / whatever

Data Commands

ANIME

Possible Replies:

  • XXX ANIME BEST MATCH
...

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

GROUP

FILE

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)

Mylist Commands

MYLIST

MYLISTSTATS

MYLISTLATEST

VOTE

RANDOM

MYLISTADD

MYLISTDEL

Misc Commands

STATS

UPTIME

TOP

LATEST

Retrieved from "https://wiki.anidb.net/index.php?title=UDP_API_DEV&oldid=4868"