HTTP API Definition

From AniDB
Jump to navigation Jump to search

General

The HTTP XML API is only a small part of the AniDB API framework, please refer to API for an overview.

Clients

If you want to create a client you have to register it here and here.

Encoding

All content is UTF8 encoded and gzip compressed (you may have to handle the decompressing yourself, if your HTTP library doesn't support compression of HTTP data). Transfer is in chunks, which are part of HTTP 1.1. This is the case even when your client requested uncompressed HTTP 1.0.

Flooding and Caching

All users of this API should employ heavy local caching. Requesting the same dataset multiple times on a single day can get you banned. The same goes for request flooding. You should not request more than one page every two seconds on average.

Anti Leech Protection

The API should not be used to "download" AniDB. If such attempts are detected you will get banned.

Parameters

These parameters apply to all HTTP XML API pages and should always be added to the request URLs.

All users of the HTTP XML API need to be registered and have to provide their registered client identifier and version number on each request.

Parameters:

  • client={string} [required]
    • client identification string, needs to be a registered client identifier, see:
  • clientver={integer} [required]
    • client version number, needs to be valid client version number for the given client identification string.
  • protover={integer} [required]
    • protocol version in use. Possible values: 1
  • request={string} [required]
    • HTTP XML datapage requested. See following sections.


Example: URL: http://api.anidb.net:9001/httpapi?client={str}&clientver={int}&protover=1

Data Commands

Anime

Allows retrieval of non-file or episode related information for a specific anime by AID (AniDB anime id).

Search

AniDB offers a daily updated dump of all anime titles which can be used to support client sided anime search features.

This file can also be used for anime title to AID lookups.

http://anidb.net/api/animetitles.dat.gz
http://anidb.net/api/animetitles.xml.gz

Alternatively there is a ready to use search using these dumps available by a third party: [1] (thx to eloyard)

Access

Base URL: http://api.anidb.net:9001/httpapi?request=anime

Parameters:

  • request=anime
  • aid={integer} [required]
    • AniDB anime id of the anime you want to retrieve data for.


Note The tags node presently contains both 'spoiler' and 'localspoiler' attributes. Both represent the same value. Clients should use 'localspoiler'; in time, 'spoiler' will be removed.


Example: URL: http://api.anidb.net:9001/httpapi?request=anime&client={str}&clientver={int}&protover=1&aid={int}

Data
<?xml version="1.0" encoding="UTF-8"?>
<anime id="1" restricted="false">
   <type>TV Series</type>
   <episodecount>13</episodecount>
   <startdate>1999-01-04</startdate>
   <enddate>1999-03-29</enddate>
   <titles>
      <title xml:lang="x-jat" type="main">Seikai no Monshou</title>
      <title xml:lang="zh-Hans" type="syn">星界之纹章</title>
      <title xml:lang="en" type="short">CotS</title>
      <title xml:lang="x-jat" type="short">SnM</title>
      <title xml:lang="ja" type="official">星界の紋章</title>
      <title xml:lang="en" type="official">Crest of the Stars</title>
      <title xml:lang="fr" type="official">Crest of the Stars</title>
      <title xml:lang="pl" type="official">Crest of the Stars</title>
   </titles>
   <relatedanime>
      <anime id="4" type="Sequel">Seikai no Senki</anime>
      <anime id="6" type="Prequel">Seikai no Danshou</anime>
      <anime id="1623" type="Summary">Seikai no Monshou Tokubetsuhen</anime>
   </relatedanime>
   <url>http://www.sunrise-inc.co.jp/seikai/</url>
   <creators>
      <name id="4495" type="Original Work">Morioka Hiroyuki</name>
   </creators>
   <description>Jinto Lin`s life changes forever when the Humankind Empire Abh takes over his home planet of Martine without firing a single shot. He is soon sent off to study the Abh language and culture and to prepare himself for his future as a nobleman — a future he never dreamed of. Or wanted.Now, Jinto is entering the next phase of his training, and he is about to meet his first Abh, the lovely Lafiel. But Jinto is about to learn that she is more than she appears to be. And together they will have to fight for their very lives.</description>
   <ratings>
      <permanent count="2953">8.53</permanent>
      <temporary count="96">7.58</temporary>
      <review count="11">8.75</review>
   </ratings>
   <picture>440.jpg</picture>
   <categories>
      <category id="174" parentid="8" hentai="false" weight="500">
         <name>Space Travel</name>
         <description>Space Travel usually refers going to space or travelling there with or without a spacecraft. There are different forms of space travel like Interplanetary travel, Interstellar travel or Intergalactic travel. Since it isn`t possible to travel faster than light, most anime series involve some sort "sub-space travel mechanism" as a way to travel faster than light.</description>
      </category>
      <category id="274" parentid="268" hentai="false" weight="400">
         <name>Novel</name>
         <description>Note that novel means book with words in paper, so no comics and no "visual novels", which should go under manga and dating-sim - visual Novel/erotic game respectively.&#13;
&#13;
Note that it can be applied to novels as we know them but also the typical light novels for teens and young adults, which are common in Japan and aside from being short include a number of illustrations. </description>
      </category>
   </categories>
   <tags>
      <tag id="136" approval="20" spoiler="false" update="2009-05-23">
         <name>space opera</name>
         <count>71</count>
      </tag>
      <tag id="175" approval="17" spoiler="false" update="2008-03-13">
         <name>space elves</name>
         <count>12</count>
      </tag>
      <tag id="389" approval="15" spoiler="false" update="2008-06-03">
         <name>war setting</name>
         <count>64</count>
      </tag>
      <tag id="393" approval="18" spoiler="false" update="2008-06-03">
         <name>space battles</name>
         <count>43</count>
         <description>There are space battles in this anime. Usually between Earth forces and some alien invader, but ship to ship skirmishes in deep space are just as common.</description>
      </tag>
   </tags>
   <characters>
      <character id="7493" type="appears in" update="2009-05-28">
         <name>Gosroth</name>
         <description>The Resii Gothroth.The first Abh ship lost in the war.</description>
         <episodes>1,1012</episodes>
         <picture>26147.jpg</picture>
      </character>
      <character id="7501" type="appears in" update="2009-05-28">
         <name>Planet Martine</name>
         <description>The homeworld of Jinto</description>
         <episodes>1</episodes>
      </character>
      <character id="7503" type="appears in" update="2009-05-28">
         <name>Rock Lynn</name>
         <description>The former president of Martine, later made count of the Hyde system, after striking a deal with the Abh (in episode 1)</description>
         <episodes>1</episodes>
         <picture>26165.jpg</picture>
      </character>
   </characters>
   <episodes>
      <episode id="1" update="2005-03-10">
         <epno>1</epno>
         <length>24</length>
         <airdate>1999-01-03</airdate>
         <rating votes="17">5.66</rating>
         <title xml:lang="ja">侵略</title>
         <title xml:lang="en">Invasion</title>
         <title xml:lang="fr">Invasion</title>
         <title xml:lang="x-jat">shinryaku</title>
      </episode>
      <episode id="2" update="2005-03-11">
         <epno>2</epno>
         <length>24</length>
         <airdate>1999-01-10</airdate>
         <rating votes="12">6.66</rating>
         <title xml:lang="ja">星たちの眷族</title>
         <title xml:lang="en">Kin of the Stars</title>
         <title xml:lang="fr">Les parents des Étoiles</title>
         <title xml:lang="x-jat">Hoshi-tachi no Kenzoku</title>
      </episode>
   </episodes>
</anime>

Errors

According to ommina the API does not use HTTP return code. Instead you will get XML consisting of one tag with a textual description. 

<error>Banned</error>

Category List

Access

Base URL: http://api.anidb.net:9001/httpapi?request=categorylist

Parameters:

  • request=categorylist
    • The current AniDB category tree. This tree is fairly static, with only rare changes. Request a new list only if you have good reason to believe there has been changes.

Example: URL: http://api.anidb.net:9001/httpapi?client={str}&clientver={int}&protover=1&request=categorylist 

<categorylist>
   <category id="80" parentid="3">
      <name>18 Restricted</name>
         <description>This isn`t really an "Audience".

         While some anime might feature sexual content they still might not be porn. Only use it when the content is clearly *not* intended for minors.    
         </description>
   </category>
   <category id="4" parentid="313">
      <name>Action</name>
   </category>

...

   <category id="37" parentid="30">
      <name>Yuri</name>
         <description>Yuri refers to anime that portray lesbian (female/female) sex. Do not confuse this with the Shoujo Ai category under Romance, which only portrays girl/girl relationships, but generally not anything pornographic. This is real female/female porn.</description>
   </category>
</categorylist>

Random Recommendation

This command mirrors the type of data provided on the main web page. Use this instead of scraping the HTML. Please note, however, that the 'random recommendations' are, in fact, random. Please do not expect random results here to match random results there.

Access

Base URL: http://api.anidb.net:9001/httpapi?request=randomrecommendation

Parameters:

  • request=randomrecommendation

Example: URL: http://api.anidb.net:9001/httpapi?client={str}&clientver={int}&protover=1&request=randomrecommendation 

<randomrecommendation>
    <recommendation>
        <anime id="7899" restricted="false">
            <type>TV Series</type>
            <episodecount>13</episodecount>
            <startdate>2010-10-04</startdate>
            <enddate>2010-12-27</enddate>
            <title xml:lang="x-jat" type="main">Arakawa Under the Bridge 2</title>
            <picture>54734.jpg</picture>
            <ratings>
                <permanent count="781">623</permanent>
                <recommendations>8</recommendations>
            </ratings>
        </anime>
    </recommendation>

...

<randomrecommendation>

Random Similar

This command mirrors the type of data provided on the main web page. Use this instead of scraping the HTML. Please note, however, that the 'random similar' are, in fact, random. Please do not expect random results here to match random results there.

Access

Base URL: http://api.anidb.net:9001/httpapi?request=randomsimilar

Parameters:

  • request=randomsimilar

Example: URL: http://api.anidb.net:9001/httpapi?client={str}&clientver={int}&protover=1&request=randomsimilar 

<randomsimilar>
    <similar>
        <source aid="7056" restricted="false">
            <title xml:lang="x-jat" type="main">Aoi Bungaku Series</title>
            <picture>37124.jpg</picture>
        </source>
        <target aid="3654" restricted="false">
            <title xml:lang="x-jat" type="main">Ayakashi: Japanese Classic Horror</title>
            <picture>44085.jpg</picture>
        </target>
    </similar>

...

</randomsimilar>

Hot Anime

This command mirrors the type of data provided on the main web page. Use this instead of scraping the HTML. Unlike the two random result commands, the results here will match the results as supplied by the main web page (with some possible variance of a few hours, depending on cache life.)

Access

Base URL: http://api.anidb.net:9001/httpapi?request=hotanime

Parameters:

  • request=hotanime

Example: URL: http://api.anidb.net:9001/httpapi?client={str}&clientver={int}&protover=1&request=hotanime 

<hotanime>
    <anime id="8556" restricted="false">
        <episodecount>12</episodecount>
        <startdate>2012-01-10</startdate>
        <title xml:lang="x-jat" type="main">Another</title>
        <ratings>
            <permanent count="248">6.61</permanent>
            <temporary count="261">7.88</temporary>
            <review count="1">4.33</review>
        </ratings>
        <picture>79963.jpg</picture>
    </anime>

...

</hotanime>

Main

A one-stop command returning the combined results of random recommendation, random similar, and hot anime. Use this command instead of scraping the HTML, and if you need more than one of the individual replies.

Access

Base URL: http://api.anidb.net:9001/httpapi?request=main

Parameters:

  • request=main

Example: URL: http://api.anidb.net:9001/httpapi?client={str}&clientver={int}&protover=1&request=main 

<main>
    <hotanime>
        <anime id="8556" restricted="false">
            <episodecount>12</episodecount>
            <startdate>2012-01-10</startdate>
            <title xml:lang="x-jat" type="main">Another</title>
            <ratings>
                <permanent count="248">6.61</permanent>
                <temporary count="261">7.88</temporary>
                <review count="1">4.33</review>
            </ratings>
            <picture>79963.jpg</picture>
        </anime>

        ...

    </hotanime>
    <randomsimilar>
        <similar>
            <source aid="8107" restricted="false">
                <title xml:lang="x-jat" type="main">A Channel: The Animation</title>
                <picture>59870.jpg</picture>
            </source>
            <target aid="4777" restricted="false">
                <title xml:lang="x-jat" type="main">Lucky Star</title>
                <picture>65555.jpg</picture>
            </target>
        </similar>

        ...

    <randomsimilar>
    <randomrecommendation>
        <recommendation>
            <anime id="44" restricted="false">
                <type>OVA</type>
                <episodecount>1</episodecount>
                <startdate>2000-05-24</startdate>
                <enddate>2000-05-24</enddate>
                <title xml:lang="x-jat" type="main">Amon Devilman Mokushiroku</title>
                <picture>14016.jpg</picture>
                <ratings>
                    <permanent count="317">387</permanent>
                    <recommendations>1</recommendations>
               </ratings>
           </anime>
       </recommendation>

       ....

    </randomrecommendation>
</main>

User Data Commands

User Mylist Summary

Access

Base URL: http://api.anidb.net:9001/httpapi?request=mylistsummary&user={str anidb username}&pass={str anidb password}

Parameters:

  • request=mylistsummary
    • Returns a list of the user's anime list in summary form, roughly matching the data in the "my list" page of the web interface.
  • user={str username}&pass={str password}
    • The user name and password of the desired user. This is their main password, not the API password specified in the profile.

Example: URL: http://api.anidb.net:9001/httpapi?client={str}&clientver={int}&protover=1&request=mylistsummary&user={str}&pass={str} 

<mylistsummary uid="40237">
    <mylistitem aid="5841" state="2">
        <episodecount>22</episodecount>
        <seencount>22</seencount>
        <specialcount>9</specialcount>
        <seenspecialcount>4</seenspecialcount>
    </mylistitem>
<mylistsummary>
Retrieved from "https://wiki.anidb.net/index.php?title=HTTP_API_Definition&oldid=16745"