UDP API Definition: Difference between revisions

'''Version:''' 0.03.730 (2015-03-25)<br>

** Content newlines are encoded as &lt;br /&gt;, ' is encoded as ` and | is encoded as /.

The network communication is ''packet'' and ''line'' based. Each AniDB API command is exactly one UDP packet containing one line. Results are sent 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 readable version of the result code. Be aware that important data fields may be returned directly after the return code (see: 200,201,209,271,272,504).

* Occurrences of these errors (except 601 and 602) should be reported to [[User:Ommina|Ommina]].

A session between the server and a client is identified by the ''IP and port'' used by the client. So when the port (or IP) changes within a session the client has to authenticate again. If a client is behind a NAT router it can’t actually control the local port used for the connection. The router will normally ''translate'' the port to support several computers on a LAN to share the Internet connection. The public port (as determined by the router and seen by the server) which has been assigned to the connection will only be reserved for as long as it is in use. This means that the router will usually ''deallocate the port after a fixed timeout period'' (eg. five, ten or 15 minutes). Once that happens the client will no longer be able to receive UDP messages from the server (the messages will be discarded as undeliverable by the router) and a new port will be selected once the client tries to send a message to the server (which will result in a new connection session - '''Note:''' This could get you banned!, see above). So in order to keep a session over a NAT router alive, the client has to ping the server within the router's deallocation period to prevent a timeout.

The client can decide whether it is behind a NAT router or not by adding <tt>nat=1</tt> to the AUTH command. This will cause the response to include the IP and port as seen by the server. If the port differs from the port reported by the local socket, the connection subject to NAT and the client should issue PING commands in regular intervals. Please do not send pings more often than is necessary to keep NAT connections alive.

** A Client MUST NOT send more than 0.5 packets per second (that's one packet every two seconds, not two packets a second!)

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

* AUTH user={str username}&pass={str password}&protover={int4 apiversion}&client={str clientname}&clientver={int4 clientversion}[&nat=1&comp=1&enc={str encoding}&mtu={int4 mtu value}&imgserver=1]

Will cause all future messages from the server, except the first (the reply to the ENCRYPT command itself), to be encrypted (128 bit [[Wikipedia:Advanced Encryption Standard|AES]]). The client will also have to encrypt all future requests sent to the server. All non-encrypted messages will be discarded by the server. The encryption key is the [[Wikipedia:MD5|MD5]] hash of a special ''UDP API Key'' (defined in the users profile) concatenated with the salt string as given in the reply to the ENCRYPT message. A normal AUTH message is still necessary to authenticate and should follow the ENCRYPT command once the API has acknowledged the encryption.

* ''API Key'' is the one defined in the {{AniDBLink|profile|profile settings page}}.

* The encryption key is md5(api_key_of_user+''salt'').

* Category fields are separated with ',' and ordered by weight (desc). ''However'', be aware that categories are no longer used nor updated internally, and category responses are only returned to avoid breaking older clients.  Use tags as a replacement. 

* '''Note:''' The character id list is the first data to be truncated if needed. And then: tag list, synonym list, short name list. This applies to the FILE command too.

  <tr><td colspan="5" align="center"><b>amask</b></td></tr>

   <td align="center"><b>Byte 1</b></td>

   <td align="center"><b>Byte 2</b></td>

   <td align="center"><b>Byte 3</b></td>

   <td align="center"><b>Byte 4</b></td>

   <td align="center"><b>Byte 5</b></td>

   <td align="center"><b>Byte 6</b></td>

   <td align="center"><b>Byte 7</b></td>

     <td><b>Bit</b></td>

     <td align="right"><b>Dec</b></td>

     <td><b>Data Field</b></td>

     <tr bgcolor="#eeeeee">

     <td>int dateflags</td>

     <tr bgcolor="#eeeeee">

     <tr bgcolor="#eeeeee">

     <tr bgcolor="#eeeeee">

     <td><i>retired</i></td>

     <td><i>retired</i></td>

     <td><b>Bit</b></td>

     <td align="right"><b>Dec</b></td>

     <td><b>Data Field</b></td>

     </tr>

     <tr bgcolor="#eeeeee">

     <tr bgcolor="#eeeeee">

     <tr bgcolor="#eeeeee">

     <tr bgcolor="#eeeeee">

     <td><b>Bit</b></td>

     <td align="right"><b>Dec</b></td>

     <td><b>Data Field</b></td>

     <tr bgcolor="#eeeeee">

     <tr bgcolor="#eeeeee">

     <td>int air date</td>

     <tr bgcolor="#eeeeee">

     <td>int end date</td>

     <tr bgcolor="#eeeeee">

     <td><i>retired</i></td>

     <td><b>Bit</b></td>

     <td align="right"><b>Dec</b></td>

     <td><b>Data Field</b></td>

     <tr bgcolor="#eeeeee">

     <td>int vote count</td>

     <tr bgcolor="#eeeeee">

     <td>int temp vote count</td>

     <tr bgcolor="#eeeeee">

     <td>int review count</td>

     <tr bgcolor="#eeeeee">

     <td><b>Bit</b></td>

     <td align="right"><b>Dec</b></td>

     <td><b>Data Field</b></td>

     <tr bgcolor="#eeeeee">

     <td><i>retired</i></td>

     <td>int ANN id</td>

     <tr bgcolor="#eeeeee">

     <td>int allcinema id</td>

     <tr bgcolor="#eeeeee">

     <td>str tag name list</td>

     <td>int tag id list</td>

     <tr bgcolor="#eeeeee">

     <td>int tag weight list</td>

     <td>int date record updated</td>

     <td><b>Bit</b></td>

     <td align="right"><b>Dec</b></td>

     <td><b>Data Field</b></td>

     <tr bgcolor="#eeeeee">

     <td>int character id list</td>

     <td><i>retired</i></td>

     <tr bgcolor="#eeeeee">

     <td><i>retired</i></td>

     <td><i>retired</i></td>

     <tr bgcolor="#eeeeee">

     <tr bgcolor="#eeeeee">

     <td><b>Bit</b></td>

     <td align="right"><b>Dec</b></td>

     <td><b>Data Field</b></td>

     <tr bgcolor="#eeeeee">

     <tr bgcolor="#eeeeee">

     <tr bgcolor="#eeeeee">

     <tr bgcolor="#eeeeee">

   12     alternative setting

=== CALENDAR: Get Upcoming Titles ===

 

'''Command String:'''

* CALENDAR

* 297 CALENDAR

{int aid}|{int startdate}|{int dateflags}/n

 

 

* 397 CALENDAR EMPTY

* Takes no parameters (other than the session string)

* Titles returned are filtered by the 'show adult' preference of the logged in user.  That is, users who have elected to hide adult content will have it hidden here as well.

* Do not depend on the command always returning exactly 50 titles; there may not always be 25 future titles pending, depending on the user's 'adult' preferences, and the date in relation to the relation to the current anime season.

* Date flags are used to indicated an unknown value (unknown month, day, year)

** bit0 set == Startdate, Unknown Day

** bit3 set == Enddate, Unknown Month, Day

** bit5 set == Startdate, Unknown Year

** bit6 set == Enddate, Unknown Year

 

=== CHARACTER: Get Character Information ===

* CHARACTER charid={int characterid}

'''Possible Replies:'''

* 235 CHARACTER

: {int charid}|{str character name kanji}|{str character name transcription}|{str pic}|{anime blocks}|{int episode list}|{int last update date}|{int2 type}|{str gender}

 

: An 'anime block' is {int anime id},{int appearance},{int creatorid},{boolean is_main_seiyuu} repeated as many times as necessary, separated by a single quote ( ' ).

* 335 NO SUCH CHARACTER

* If no seiyuu is associated with the character for a given aid, the 'creatorid' and 'is_main_seiyuu' fields will be empty, but the commas will remain.

* An empty episode list is "undefined": no episode values have been added.

* ''appearance'' values: 0='appears in', 1='cameo appearance in', 2='main character in', 3='secondary cast in'

* ''type'' can be one of: (Note: this is subject to changes so don't rely on this mapping)

** 4 => 'Vessel'  

* ''gender'' can be one of: (Note: this is subject to changes so don't rely on this mapping)

** "M" => 'Male'

** "F" => 'Female'

** "I" => 'Intersexual'

** "D" => 'Dimorphic'

** "-" => 'none/does not apply'

** "?" => 'unknown'

 

  488|ニコ・ロビン|Nico Robin|14789.jpg|4097,2,1900,1'69,2,1901,0'6199,0,1900,1'5691,0,1900,1'2644,0,,'4851,0,1900,1||1236938094

=== CREATOR: Get Creator Information ===

* CREATOR creatorid={int creatorid}

 

'''Possible Replies:'''

 

 

'''Info:'''

* ''type'' values: 1='person', 2='company', 3='collaboration'

 

 

  718|GAINAX|Gainax|2|10092.png||http://www.gainax.co.jp/|Gainax|Gainax|1237048093

 

=== EPISODE: Retrieve Episode Data ===

'''Command String:'''<br>

 

'''Possible Replies:'''

 

'''Info:'''

* Returned 'epno' includes special character (only if special) and padding (only if normal).

* The ''type'' is the raw episode type, used to indicate numerically what the special character will be

** 1: regular episode (no prefix), 2: special ("S"), 3: credit ("C"), 4: trailer ("T"), 5: parody ("P"), 6: other ("O")

 

  > EPISODE eid=1&s=xxxxx

  < 240 EPISODE

 

  > EPISODE aname=Seikai no Monshou&epno=2&s=xxxxx

  < 240 EPISODE

 

 

'''Command String:'''<br>

* FILE fid={int4 id}&fmask={hexstr fmask}&amask={hexstr amask}

* FILE size={int8 size}&ed2k={str ed2khash}&fmask={hexstr fmask}&amask={hexstr amask}

* FILE aname={str anime name}&gname={str group name}&epno={int4 episode number}&fmask={hexstr fmask}&amask={hexstr amask}

* FILE aname={str anime name}&gid={int4 group id}&epno={int4 episode number}&fmask={hexstr fmask}&amask={hexstr amask}

* FILE aid={int4 anime id}&gid={int4 group id}&epno={int4 episode number}&fmask={hexstr fmask}&amask={hexstr amask}

 

: {int4 fid 0}|{int4 fid 1}|...|{int4 fid n}

 

* fmask and amask are hexidecimal strings where each bit corresponds to a data field related to the specified file (see below). The data list received is sorted and returned in the same order as the tables: top to bottom, left to right, with fmask preceding amask.  There is '''no''' provision to retrieve all fields.  Further, requesting a 'unusued' or 'reserved' bit will return an "illegal input" error.

* "audio codec" and "audio bitrate" will return multiple values if there are multiple audio streams present in the file.  Values will be separated by a single quote. 

* For byte 1, bit 2 (other episodes): episode IDs will be followed by an integer '''percentage''' that indicate the percentage of the related episode this file covers. Typically 100%, there are cases where it will be 50, 30, or other values.  This value provides no indication where, within an episode, the file represents.  That is, 50% could mean the file covers the first half of the episode, the second half, or some 50% range in between.

'''State:'''

<pre>

bit / int value meaning

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

7 / 64 FILE_UNC: file is uncensored

8 / 128 FILE_CEN: file is censored

 

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

</pre>

 

<table border="0" cellpadding="0" cellspacing="2">

<tr><td colspan="4" align="center">'''fmask:'''</td></tr>

<tr>

  <td align="center">'''Byte 1'''</td>

  <td align="center">'''Byte 2'''</td>

  <td align="center">'''Byte 3'''</td>

  <td align="center">'''Byte 4'''</td>

  <td align="center">'''Byte 5'''</td>

</tr>

<tr>

     <tr bgcolor="#eeeeee">

     <td>unused</td>

     <td>int4 aid</td>

     <tr bgcolor="#eeeeee">

     <td>int4 eid</td>

     <td>int4 gid</td>

     <tr bgcolor="#eeeeee">

     <td>int4 mylist id</td>

     <td>list other episodes</td>

     <tr bgcolor="#eeeeee">

     <td>int2 IsDeprecated</td>

     <td>int2 state</td>

     <td>int8 size</td>

     <tr bgcolor="#eeeeee">

     <td>str ed2k</td>

     <td>str md5</td>

     <tr bgcolor="#eeeeee">

     <td>str sha1</td>

     <td>str crc32</td>

     <tr bgcolor="#eeeeee">

     <td>video colour depth</td>

     <tr bgcolor="#eeeeee">

     <td>reserved</td>

   <td>

   <table>

     <tr>

     <td>'''Bit'''</td>

     <td align="right">'''Dec'''</td>

     <tr bgcolor="#eeeeee">

     <td>str quality</td>

     <td>str source</td>

     <tr bgcolor="#eeeeee">

     <td>str audio codec list</td>

     <td>int4 audio bitrate list</td>

     <tr bgcolor="#eeeeee">

     <td>str video codec</td>

     <td>int4 video bitrate</td>

     <tr bgcolor="#eeeeee">

     <td>str video resolution</td>

     <td>str file type (extension)</td>

     <td>str dub language</td>

     <tr bgcolor="#eeeeee">

     <td>str sub language</td>

     <td>int4 length in seconds</td>

     <tr bgcolor="#eeeeee">

     <td>str description</td>

     <td>int4 aired date</td>

     <tr bgcolor="#eeeeee">

     <td>unused</td>

     <td>unused</td>

     <tr bgcolor="#eeeeee">

     <td>str anidb file name</td>

     <tr bgcolor="#eeeeee">

     <td>int4 mylist state</td>

     <td>int4 mylist filestate</td>

     <tr bgcolor="#eeeeee">

     <td>int4 mylist viewed</td>

     <td>int4 mylist viewdate</td>

     <tr bgcolor="#eeeeee">

     <td>str mylist storage</td>

     <td>str mylist source</td>

     <tr bgcolor="#eeeeee">

     <td>str mylist other</td>

 

   <td>

   <table>

     <tr>

     <tr bgcolor="#eeeeee">

     <td>int4 anime total episodes</td>

     <tr>

     <td>int4 highest episode number</td>

     <tr bgcolor="#eeeeee">

     <td>str year</td>

     <tr>

     <td>str type</td>

     <tr bgcolor="#eeeeee">

     <td>str related aid list</td>

     <tr>

     <td>str related aid type</td>

     <tr bgcolor="#eeeeee">

     <td>str category list</td>

     <tr>

     <td>reserved</td>

  <td>

  <table>

    <td>'''Bit'''</td>

    <td align="right">'''Dec'''</td>

    <td>'''Data Field'''</td>

    <td>7</td>

    <td align="right">128</td>

    <td>str romaji name</td>

    <td>str kanji name</td>

    <td>str english name</td>

    </tr>

    <tr bgcolor="#eeeeee">

    <td>4</td>

    <td align="right">16</td>

    <td>str other name</td>

    </tr>

    <td>3</td>

    <td align="right">8</td>

    </tr>

    <tr bgcolor="#eeeeee">

    <td>2</td>

    <td align="right">4</td>

    <td>str synonym list</td>

    <td align="right">2</td>

    <tr bgcolor="#eeeeee">

    <td>'''Bit'''</td>

    <td align="right">'''Dec'''</td>

    <td>'''Data Field'''</td>

    <td align="right">128</td>

    <td>6</td>

    <td align="right">64</td>

    <tr bgcolor="#eeeeee">

    <td>str ep romaji name</td>

    <tr bgcolor="#eeeeee">

    <td>3</td>

    <td align="right">8</td>