UDP API Definition: Difference between revisions

Revision as of 15:40, 13 January 2006

Author: Exp
Version: 0.03 - 13.01.2006
Version number used for protover parameter: "3"

Updated versions of this document, notifications and official clients:

If you want to recieve a notification mail every time a new version of the API Specs is released or want to have your client linked/hosted by anidb drop Exp a line.

IMPORTANT: If you are writing a client please post your client name and your email address here RIGHT NOW. Thanks!

Changelog

0.03 - 13.01.2006
ANIME, EPISODE, GROUP, STATS, TOP, UPTIME, MYLISTSTATS, VOTE and RANDOM commands added
it is now possible to use html escaped code in mylist fields, and '='
updated epno in default file name (for new specials)
... (a lot of stuff already forgotten)

0.02c - 10.10.2004
LOGOUT now requires the session string too
Note on 6xx server errors and tags added

0.02b - 14.08.2004
503 INVALID SESSION changed to 506 INVALID SESSION
BUGFIX: 200 message on AUTH did not contain a session key
BUGFIX: 1 internal bug fixed

0.02 - 13.08.2004
new session key needs to be send with each command
random udp ports no longer required
FILE, MYLIST, MYLISTDEL, MYLISTADD commands added
Some textparts of return values changed
additional documentation added
check the caching section!

0.01b - 12.08.2004
added NOTIFYLIST, NOTIFYGET, NOTIFYACK, SENDMSG commands

0.01 - 10.08.2004
initial version

Formats used in this Spec

{vartype varname} - Specifies what shall be inserted at this point and its type
[...] - Everything between [ and ] is optional

Used types

int2 - 2byte Integer (in string representation)
int4 - 4byte Integer (in string representation)
str - String (NOTE: might be as long as 5000 bytes !!!, via udp api no string is likely to extend >1500 bytes)

Content Encoding

Current character encoding used by the api: unknown
Escape scheme for option values: html form encoding + newline

this means you have to encode at least & and = in your option values in html form encoding style before sending them to the api server. All other html form encodings are optional.

All newlines should be replaced by <br>

escape scheme for returned data fields: ', | and newline

newlines are encoded as <br>, | is not allowed in data fields and ' is encoded as ?.

Basics

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.

IDs

All IDs start at 1 (not 0). A normal table index (id) may never be 0 (there are some exceptions where an entry with id=0 exists, however those represent unknown values) It is possible for table entries to have id fields (i.e. gid) with a value of 0. Those are to be interpreted as "NONE" or "NULL". An ID is NEVER reused. That means after an entry is deleted no new entry will ever have that ID again.

IMPORTANT:

A client should ignore any additional trailing data fields it doesn't expect. Additional fields are going to be added to the output of some commands from time to time. Those additional fields will simply be appended to the end of the existing output.

A client should be written in a way so that it is not affected by such new fields.

NOTE:

Due to the length contraints of an UDP package API replies might be truncated at the end if they exceed the max. length of ~1500 bytes. Such events are not handled specially, the data will simply be sent truncated.

Server / UDP Connection:

The Client has to send data packets to:

Server: api.anidb.info

Port: 9000/UDP

IMPORTANT:

Maintenance

While in daily maintenance the AniDB API will reply with

601 ANIDB OUT OF SERVICE - TRY AGAIN LATER

to all commands.

If a client recieves such a return value it should wait at least 30 minutes before trying again.

NOTE:

6xx messages do not always return the tags given with the command which caused the error!

Connection Problems

There are many ways for a client to end up banned or the API might currently be handling too many concurrent connections. If a client does not get any reply to an AUTH command it should start to increase the retry delay exponentially with every failed login attempt. (i.e. try again after 30 seconds if the first login attempt failed, if the second fails too retry after 2 minutes, then 5 minutes, then 10 minutes, then 30 minutes, ... until you reach a retry delay of ~2-4h.)

Local Port

A client should select a fixed local port >1024 at install time and reuse it for local UDP Sockets. If the API sees too many different UDP Ports from one IP within ~1 hour it will ban the IP. (So make sure you're reusing your UDP ports also for testing/debuging!)

The local port may be hardcoded, however, an option to manually specify another port should be offered.

The servername and port should not be hardcoded into a frontend but should be read from a configuration file. The network communication is packet and line based. Each ANIDB API command is exactly one UDP packet containing one line. Results are send as one packet but may consist out of multiple lines. A return value always starts with a 3 byte result code followed by a human redable version of the result code. Be aware that important data fields may be returned directly after the return code (see: 230 code). The meaning for all result codes can be found in this document. If there is more than one entry returned, it's one entry per line. Lines are terminated by a \n (no dos linefeed \r). The elements of a format string are seperated by a "|" character.

Flood Protection

To prevent high server load the UDP API server enforces a strict flood protection policy.

Short Term:

A Client MUST NOT send more than 0.5 packets per second.

The server will start to enforce the limit after the first 5 packets have been recieved.

Long Term:

A Client MUST NOT send more than one packet every 30 seconds over an extended amount of time.

Once a client exceeds a rate limit all further UDP packets from that client will be dropped without feedback until the client's packet rate is back down to acceptable levels.

NOTE:

Dropped packets are still taken into account for the packet rate. Meaning if you continuously send packets your client will be banned forever.

Generally clients should be written in a way to minimize server and network load. You should always keep that in Mind. Abusive clients may be banned completly.

NOTE:

If you suddenly stop getting replies from the AniDB API or you normally don't have a noteable packetloss and from one point on you suddenly note a high packetloss percentage you have most likely entered a critical flood ratio.

If the AniDB API isn't answering at all it might either be down or you have been banned, this is normally caused by vialoating the API specs (i.e. too many connections using different ports from one ip, too many auth failures, ...) (usually lasts 30 minutes). If you're experiencing packet loss you have probably reached the rate limit and the API starts to randomly drop incoming packets from your IP. (can be solved by enforcing a delay between multiple commands when you're sending a batch)

Tag option

The api will add a user defined string at the beginning of each reply line seperated with a space, if desired. To enable this you have to add the tag={str usertag} option to a command. A tag is only valid for the command it was send with, meaning it is not persistent, if you want to have tags in front of all reply lines you will have to append the tag option to each command you send to the server. Tags are ment to enable a client to handle more than one request/reply at a time.

Usage example:

 AUTH user=baka&pass=baka&protover=25&client=someclient&clientver=1&tag=abc123
 abc123 200 Jxqxb LOGIN ACCEPTED

or

 LOGOUT s=Jxqxb&tag=byebye
 byeybe 203 LOGGED OUT

NOTE:

The tag option is valid for all api commands and is thus not explicitly listed in the description of each command.

Caching

To minimize server and network load a client should use local caching in order to prevent repeated API requests for the same data.

A client should locally cache FILE/EP/ANIME/GROUP/... info whereever possible for extended amounts of time. (I.e. if a client is used to scan a local folder with anime files and add them via API to a users mylist then it shall only ask for all files in the first run and cache the info for all files known to AniDB. If run again over the same folder it shall only check those files which were unknown to anidb at the time of the last check.)

Later versions of the API might enforce this by banning clients which ask for the same information more than once every week/month.

Server Errors

At any time the API might return a fatal error of the form:

6xx ERROR DESCRIPTION

Possible codes are 600-699.

Occurances of 6xx errors (other than 601) should be reported to me.

NOTE:

6xx messages do not always return the tags given with the command which caused the error!

Authing Commands

NOTE:

_ANY_ command which requires parameters may return: 505 ILLEGAL INPUT OR ACCESS DENIED

AUTH: Authing to the AnimeDB

Command String:

AUTH user={str username}&pass={str password}&protover={int4 apiversion}&client={str clientname}&clientver={int4 clientversion}

Possible Replies:

200 {str session_key} LOGIN ACCEPTED
201 {str session_key} LOGIN ACCEPTED - NEW VERSION AVAILABLE
500 LOGIN FAILED
503 CLIENT VERSION OUTDATED
504 CLIENT BANNED - {str reason}
505 ILLEGAL INPUT OR ACCESS DENIED
601 ANIDB OUT OF SERVICE - TRY AGAIN LATER

IMPORTANT! POSSIBLE RETURN CODE AT ANY POINT OF THE API PROTOCOL:

501 LOGIN FIRST
502 ACCESS DENIED
506 INVALID SESSION

Info:

The session_key is a String containing only a-z,A-Z,0-9 chars of a length of 4-8 characters.

It has to be stored by the client and needs to be sent as parameter with every command which requires the user to logged in.

The session_key String is appended as parameter "s", i.e. "PUSH notify=1&msg=1&s={str session_key}".
On a 500 LOGIN FAILED message the client should request the user to enter username and password again.
In case of a 501 LOGIN FIRST message the client should silently resend an auth command and send the failed command again.
A 502 ACCESS DENIED message should abort the current action on the client side and display a message to the user.
A 506 INVALID SESSION means that either the session key parameter "s" was not provided with a command that requires it or the session key is no longer valid. The client should reissue an AUTH command.

NOTE:

A frontend shall expect 501 and 502 messages to be returned on ANY command.

NOTE:

Anidb usernames are always lowercase and may only contain characters (a-z) and numbers (0-9).

The client should silently convert all entered usernames to lowercase before sending them to the API.
The client should send the apiversion of the AnimeDB API version it supports as value of the protover parameter.
The client MAY NOT send anything but the version of the API Specs the author used to write the client! (as it is stated at the top of this file @ "Version number used for protover parameter")

The API will compare that value to it's own version of the API and if the version of the client is older the API will decide wheter the changes were significant enough to deny the old client access to the DB.

The clientname shall be a lowercase string containing only the chars a-z of 4-16 chars length which identifies the client. (i.e. mykickassclient)
The clientversion shall be a number starting with 1, increased on every change in the client.

clientname and clientversion might be used by the API to distinguish between different clients and client versions if that should ever become nessecary.

IMPORTANT:

DO NOT use the clientname of another existing client.
ALWAYS increase the clientversion number if you release a new client version.

A Login and its assigned session_key is valid until the virtual UDP connection times out or until a LOGOUT command is issued.
The virtual UDP connection times out if no data was recieved from the client for 35 minutes.
A client should issue a NOTIFY command once every 30 minutes to keep the connection alive should that be required.
If the client does not use any of the notification/push features of the API it should NOT keep the connection alive, furthermore it should explicitly terminate the connection by issueing a LOGOUT command once it finished it's work.
If it is very likely that another command will be issued shortly (within the next 20 minutes) a client may keep the current connection open, until it times out on it's own, by not sending a LOGOUT command.
The client shall notify the user if it recieved a 201 message at login.

This means a new version of the client is available, however the old version is still supported otherwise a client banned message would have been returned.

The user should get a popup message on 503 and 504 messages telling him to update his client software.

(NOTE: 504 means that this version of the client is banned, not the user!)

IMPORTANT:

Make sure your client handels ALL possible AUTH return codes before giving out any versions!

LOGOUT: Logout

Command String:

LOGOUT

Possible Replies:

203 LOGGED OUT
403 NOT LOGGED IN

Info:

This command only works if you are already logged in.
A logout should ALWAYS be issued if the client is currently logged in and is either exiting or not expecting to send/recieve any anidb api packets for the next >= 30 minutes.

Notify Commands

PUSH: UDP Notification Registration

Command String:

PUSH notify={bool push_file_added_notifications}&msg={bool push_msg_added_notifications}

Possible Replies:

270 NOTIFICATION ENABLED

OR (if both values are 0)

370 NOTIFICATION DISABLED

Note:

This command only works if you are logged in.
With this command you can register your client as an observer for anidb notification and message events for the current user. If you are registered for one or both events the anidb server will send an UDP packet (format see below) on each change which affects the current user. The UDP packet is sent to the ip and port from which the AUTH command was recieved.
UDP packets are resend 3 times, if the client does not acknowlege them. After that the client is logged out and no further notifies will be sent.
On recieving any of the above packets the client has to issue a PUSHACK command with the notify_packet_id provided in the notification packet.

Notification Packet Format:

File Added Notify:

 271 {int4 notify_packet_id} NOTIFICATION
 {int4 aid}|{int4 date}|{int4 count}|{str animetitle}

aid is the id of the affected anime

date is the time of the event (in seconds since 1.1.1970)

count is the number of events pending for this anime

animetitle is the name of the affected anime

Message Added Notify:

 272 {int4 notify_packet_id} NOTIFICATION
 {int2 type}|{int4 date}|{int4 senderuid}|{str sendername}|{str subject}

type is the type of the message (0=normal msg, 1=annonymous, 2=system msg, 3=mod msg)

date is the time the message was sent (in seconds since 1.1.1970)

senderuid/sendername are the user id and username of the sender

subject is the message subject

PUSHACK: UDP Notification Acknowledge

Command String:

PUSHACK nid={int4 notify_packet_id}

Possible Replies:

280 PUSHACK CONFIRMED
380 NO SUCH PACKET PENDING

Info:

This command only works if you are logged in.
see: PUSH

NOTIFY: Notifications

Command String:

NOTIFY

Possible Replies:

290 NOTIFICATION

{int4 pending_notifies}|{int4 pending_msgs}

501 LOGIN FIRST

Info:

This command only works if you are logged in.
pending_notifies number of animes which have pending notifications for this user.
pending_msgs number of unread anidb messages for this user.
A client which has registered to recieve UDP notification packets should issue this command once every 30 minutes to keep the connection alive and to ensure that it has not been logged out by the API server yet.
If the client did send a NOTIFY within the last 35 minutes and it was confirmed by AniDB then recieving a 501 LOGIN FIRST message for the next NOTIFY command shows that AniDB logged the client out bc it did not respond to a PUSH Notification packet.
There is no command to retrieve missed PUSH Notifications.

NOTE:

This command MUST NOT be issued more than once every 20 minutes.

NOTIFYLIST: List Notification/Message IDs

Command String:

NOTIFYLIST

Possible Replies:

291 NOTIFYLIST

{str type}|{int4 id}

...

501 LOGIN FIRST

Info:

This command only works if you are logged in.
type is:

M for message entries

N for notification entries

id is the identifier for the notification/message as required by NOTIFYGET.
NOTIFYLIST returns one line per entry, if no entries are available only the first line of the reply is returned.

NOTE:

This command MUST NOT be issued regulary but should only be triggered by either a push message recieved by the client or a reply to a NOTIFY command which tells you that there are messages/notifications waiting.

NOTIFYGET: Get Notification/Message

Command String:

NOTIFYGET type={str type}&id={int4 id}

Possible Replies:

292 NOTIFYGET

[if type = M]

{int4 id}|{int4 from_user_id}|{str from_user_name}|{int4 date}|{int4 type}|{str title}|{str body}

[if type = N]

{int4 aid}|{int4 type}|{str count}|{int4 date}|{str anime_name}

393 NO SUCH ENTRY
505 ILLEGAL INPUT OR ACCESS DENIED
501 LOGIN FIRST

Info:

This command only works if you are logged in.
type is:

M for message entries

N for notification entries

id is the identifier for the notification/message as required by NOTIFYGET.
for message entries (M):

date is the time of the event (in seconds since 1.1.1970)

type is the type of the message (0=normal msg, 1=annonymous, 2=system msg, 3=mod msg)

for notification entries (N):

aid is the id of the affected anime

type is the notification type (0=all, 1=new, 2=group)

count is the number of events pending for this anime

date is the time of the event (in seconds since 1.1.1970)

NOTIFYACK: Ack Notification/Message

Command String:

NOTIFYACK type={str type}&id={int4 id}

Possible Replies:

282 NOTIFYACK SUCCESSFUL
382 NO SUCH ENTRY
505 ILLEGAL INPUT OR ACCESS DENIED
501 LOGIN FIRST

Info:

This command only works if you are logged in.
This command will mark a message read or clear a notification.
type is:

M for message entries

N for notification entries

Data Commands

ANIME: Retrieves data for a specific anime

Command String:
by aid

ANIME aid={int4 id}

by name

ANIME aname={str anime name}

Possible Replies:

230 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}

330 NO SUCH ANIME

Info:

Synonyms and short names are separated with '
Category names are separated with ',' and ordered by weight (desc).
No support for genres.
By name: must be perfect match of romaji/kanji/english/other/synonym/short name.
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|東京ミュウミュウ||||TMM'mew|Cat Girls

 > ANIME aname=ナルト&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)

EPISODE: Retrieves data for a specific episode

Command String:
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:

240 EPISODE

{int4 eid}|{int4 aid}|{int4 length}|{int4 rating}|{int4 votes}|{str epno}|{str eng}|{str romaji}|{str kanji}

340 NO SUCH EPISODE

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: Retrieves data for a specific group

Command String:
by gid

GROUP gid={int4 gid}

by name/shortname

GROUP gname={str group name}

Possible Replies:

250 GROUP

{int4 gid}|{int4 rating}|{int4 votes}|{int4 acount}|{int fcount}|{str name}|{str short}|{str irc}|{str url}

350 NO SUCH GROUP

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: Retrieve File Data

Command String: 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:

220 FILE

{int4 fid}|{int4 aid}|{int4 eid}|{int4 gid}|{int4 state}|{int4 size}|{str ed2k}|{str anidbfilename}

220 FILE

{int4 fid}|...(data list)

320 NO SUCH FILE

Info:

fid, aid, eid, gid are the unique ids for the file, anime, ep, group entries at anidb.

You can use those to create links to the corresponding pages at anidb.

anidbfilename is the anidb filename for the file.

However this name does not contain all the extra information of the filenames on AniDB and might be composed slightly different.

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.

State:

bit / int value 	meaning
1 / 1 		FILE_CRCOK: file matched official crc (displayed with green background in anidb)
2 / 2 		FILE_CRCERR: file DID NOT match official crc (displayed with red background in anidb)
3 / 4 		FILE_ISV2: file is version 2
4 / 8 		FILE_ISV3: file is version 3
5 / 16 		FILE_ISV4: file is version 4
6 / 32 		FILE_ISV5: file is version 5

examples:
state ==== 9 ==> FILE_CRCOK+FILE_ISV3 ==> file matched official crc and is version 3
state ==== 0 ==> - ==> file was not crc checked and is version 1
state ==== 34 ==> FILE_CRCERR+FILE_ISV5 ==> file DID NOT match official crc and is version 5
state ==== 1 ==> FILE_CRCOK ==> file matched official crc and is version 1
state ==== 8 ==> FILE_ISV3 ==> file was not crc checked and is version 3

fcode:

Bit	Decimal	Data field	Bit	Decimal	Data field
0	1	not used	16	65536	str dub language
1	2	int4 aid	17	131072	str sub language
2	4	int4 eid	18	262144	str quality
3	8	int4 gid	19	524288	str source
4	16	int4 lid	20	1048576	str audio codec
5	32	not used	21	2097152	int4 audio bitrate
6	64	not used	22	4194304	str video codec
7	128	not used	23	8388608	int4 video bitrate
8	256	int2 status	24	16777216	str video resolution
9	512	int4 size	25	33554432	str file type (extension)
10	1024	str ed2k	26	67108864	int4 length in seconds
11	2048	str md5	27	134217728	not used
12	4096	str sha1	28	268435456	not used
13	819	str crc32	29	536870912	not used
14	16384	not used	30	1073741824	not used
15	32768	not used	31	-2147483648	not used

acode:

Bit	Decimal	Data field	Bit	Decimal	Data field
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)
2	4	not used	18	262144	str year
3	8	not used	19	524288	str type
4	16	not used	20	1048576	str romaji name
5	32	not used	21	2097152	str kanji name
6	64	not used	22	4194304	str english name
7	128	not used	23	8388608	str other name
8	256	str epno	24	16777216	str short name list
9	512	str ep name	25	33554432	str synonym list
10	1024	str ep romaji name	26	67108864	str category list
11	2048	str ep kanji name	27	134217728	not used
12	4096	not used	28	268435456	not used
13	819	not used	29	536870912	not used
14	16384	not used	30	1073741824	not used
15	32768	not used	31	-2147483648	not used

Examples: (html escaped code intended)

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

Mylist Commands

MYLIST: Retrieve Mylist Data

Command String: by lid: (mylist id)

MYLIST lid={int4 lid}

by fid:

MYLIST fid={int4 fid}

by size+ed2k hash:

MYLIST size={int4 size}&ed2k={str ed2khash}

by anime + group + epno

MYLIST aname={str anime name}&gname={str group name}&epno={int4 episode number}
MYLIST aname={str anime name}&gid={int4 group id}&epno={int4 episode number}
MYLIST aid={int4 anime id}&gname={str group name}&epno={int4 episode number}
MYLIST aid={int4 anime id}&gid={int4 group id}&epno={int4 episode number}

Possible Replies:

221 MYLIST

{int4 lid}|{int4 fid}|{int4 eid}|{int4 aid}|{int4 gid}|{int4 date}|{int2 state}|{int4 viewdate}|{str storage}|{str source}|{str other}

322 MULTIPLE FILES FOUND

{str anime title}|{int episodes}|{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}

321 NO SUCH ENTRY

Info:

The state field provides information about the location and sharing state of a file in mylist.
If files are added after hashing, a client should specify the state as 1 (on hdd) (if the user doesn't explicitly select something else).
eps is a list of episodes, e.g. "1-12,14-16,T1"

States:

 0 - unknown - state is unknown or the user doesn't want to provide this information
 1 - on hdd - the file is stored on hdd (but is not shared)
 2 - on cd - the file is stored on cd
 3 - deleted - the file has been deleted or is not available for other reasons (i.e. reencoded)

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

MYLISTADD: Add file to mylist

Command String: by lid: (mylist id, edit only)

MYLISTADD lid={int4 lid}&edit=1[&state={int2 state}&viewed={boolean viewed}&source={str source}&storage={str storage}&other={str other}]

by fid:

MYLISTADD fid={int4 fid}[&state={int2 state}&viewed={boolean viewed}&source={str source}&storage={str storage}&other={str other}][&edit=1]

by size+ed2k hash:

MYLISTADD size={int4 size}&ed2k={str ed2khash}[&state={int2 state}&viewed={boolean viewed}&source={str source}&storage={str storage}&other={str other}][&edit=1]

by anime + group + epno

MYLISTADD aname={str anime name}[&gname={str group name}&epno={int4 episode number}][&state={int2 state}&viewed={boolean viewed}&source={str source}&storage={str storage}&other={str other}][&edit=1]
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}][...]

Possible Replies:

320 NO SUCH FILE
330 NO SUCH ANIME
350 NO SUCH GROUP

when edit=0

210 MYLIST ENTRY ADDED

{int4 number of entries added}

310 FILE ALREADY IN MYLIST
322 MULTIPLE FILES FOUND

{int4 fid 1}|{int4 group name 1}

...

{int4 fid n}|{int4 group name n}

when edit=1

311 MYLIST ENTRY EDITED
311 MYLIST ENTRY EDITED

{int4 number of entries edited}

411 NO SUCH MYLIST ENTRY

Info:

All data except lid/fid/size+hash is optional.
Viewed should be 0 for unwatched files and 1 for watched files.
Other is the only field which may contrain newlines, but they have to be stored as
If edit is 1 then an existing entry, if found, will be updated with the given values.
For state values refer to: MYLIST
If you want to change an existing entry and already know it's mylist id (lid) please use the lid-version of this command. It put less load on the server.
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

NOTE:

Currently this command does not update the internal caches of AniDB. Using this command will lead to wrong stats values/counts being displayed in your Mylist & co @ AniDB for upto 24h.

NOTE:

Currently this command will replace all mylist fields this commands supports, even if they were not specified by the client. I.e. an update with "MYLISTADD lid={int4 lid}&edit=1&viewed=1" will reset the state,source,storage and other fields to their default values.

NOTE:

Currently this command will reset the date of the file watched despite the state of the entry was already maked as "viewed".

MYLISTDEL: Remove file from mylist

Command String: by lid: (mylist id)

MYLISTDEL lid={int4 lid}

by fid:

MYLISTDEL fid={int4 fid}

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:

211 ENTRY DELETED

{int4 number of entries}

411 NO SUCH ENTRY

Info:

Currently this command does not update the internal caches of AniDB. Using this command will lead to wrong stats values/counts being displayed in your Mylist & co @ AniDB for upto 24h.
epno=0 means all eps (default), negative numbers means upto. (-12 -> upto 12)
group is optional
command will delete all enties found

MYLISTSTATS : Retrieve mylist stats

Command String:

MYLISTSTATS

Possible Replies:

222 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

VOTE: Vote for a specifed anime, episode or group

Command String:
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:

260 VOTED

{str aname/ename/gname}

261 VOTE FOUND

{str aname/ename/gname}|{vote value}

262 VOTE UPDATED

{str aname/ename/gname}|{old vote value}

263 VOTE REVOKED

{str aname/ename/gname}|{revoked vote value}

360 NO SUCH VOTE
361 INVALID VOTE TYPE
362 INVALID VOTE VALUE
363 PERMVOTE NOT ALLOWED

{str aname}

364 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: Get a random anime

Command String:

RANDOMANIME type={int4 type}

Possible Replies:

230 ANIME ... (see ANIME)

Info:

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

Misc Commands

PING: Ping Command

Command String:

PING

Possible Replies:

300 PONG

Info:

May be used by a frontend to determin if the API is sill available.
May be executed even if not yet logged in.

UPTIME

Command String:

UPTIME

Possible Replies:

208 UPTIME

{int4 udpserver uptime in sec}

STATS

Command String:

STATS

Possible Replies:

206 STATS

{int4 animes)|{int4 eps}|{int4 files}|{int4 groups}|{int4 users}|{int4 creqs}

TOP

Command String:

TOP

Possible Replies:

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

SENDMSG: Send Message

Command String:

SENDMSG to={str username}&title={str title}&body={str body}

Possible Replies:

294 SENDMSG SUCCESSFUL
394 NO SUCH USER
501 LOGIN FIRST

Note:

This command only works if you are logged in.
This command allows you to send an AniDB message.

IMPORTANT:

title must not be longer than 100 chars.

body must not be longer than 1200 chars.

Fatal Errors

At anypoint int the retrieval process you have to expect the following output:

6xx INTERNAL SERVER ERROR

ERROR: {str errormessage}

OR

6xx INTERNAL SERVER ERROR - {str errormessage}

Such errors should be reported back to Epoximator. (xx is a number between 00 and 99)

If you supply an unknown or unimplemented command you will get an error:

598 UNKNOWN COMMAND

RETURN CODES

/*
 * 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

/*
 * SERVER SIDE FAILURE 6XX
 */

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

UDP API Definition: Difference between revisions

Revision as of 15:40, 13 January 2006

Changelog

Formats used in this Spec

Used types

Content Encoding

Basics

General

IDs

Server / UDP Connection:

Connection Problems

Local Port

Flood Protection

Tag option

Caching

Server Errors

Authing Commands

AUTH: Authing to the AnimeDB

LOGOUT: Logout

Notify Commands

PUSH: UDP Notification Registration

PUSHACK: UDP Notification Acknowledge

NOTIFY: Notifications

NOTIFYLIST: List Notification/Message IDs

NOTIFYGET: Get Notification/Message

NOTIFYACK: Ack Notification/Message

Data Commands

ANIME: Retrieves data for a specific anime

EPISODE: Retrieves data for a specific episode

GROUP: Retrieves data for a specific group

FILE: Retrieve File Data

Mylist Commands

MYLIST: Retrieve Mylist Data

MYLISTADD: Add file to mylist

MYLISTDEL: Remove file from mylist

MYLISTSTATS : Retrieve mylist stats

VOTE: Vote for a specifed anime, episode or group

RANDOM: Get a random anime

Misc Commands

PING: Ping Command

UPTIME

STATS

TOP

SENDMSG: Send Message

Fatal Errors

RETURN CODES

Navigation menu