HTTP API Definition
| Important! | 2015-02-23
Portions of the HTTP API have changed! A new version of the HTTP API will be deployed. The primary change are the transition to the new tag design, rolled out late last year. A fair bit has changed. While some concessions have been made to avoid breaking existing clients, such concessions will only last a number of weeks, not forever. Outdated nodes and attributes are scheduled to be removed on or very near 2015-06-01 (roughly three months from now.) So far:
The 'id', 'localspoiler', 'globalspoiler' and 'updated' attributes, 'name' and 'description' nodes will remain. If your client is going to blow up with the removal of the above values, please considering taking this opportunity to make it less blowupy. |
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
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. |
| Important! | The meaning of the <temporary> vote node has changed since the HTTP API was put in place. To help keep clients compatible, the node will not be removed short term, but client consumers should be aware that this value now represents the mean of all votes (both permanent and temporary). |
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.
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>
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>