Difference between revisions of "HTTP API Definition"

From AniDB
Jump to navigation Jump to search
m (Data)
m (Data)
Line 95: Line 95:
 
<code><pre>
 
<code><pre>
 
<?xml version="1.0" encoding="utf-8" ?>
 
<?xml version="1.0" encoding="utf-8" ?>
<anime id="1">
+
<anime aid="1">
 
   <titles>
 
   <titles>
 
       <!-- should we include all titles or are official+main title enough? -->
 
       <!-- should we include all titles or are official+main title enough? -->
Line 112: Line 112:
 
   </date>
 
   </date>
 
   <categories>
 
   <categories>
       <category id="233" weight="6">Dynamic::Plot Continuity</category>
+
       <category cid="233" weight="6">Dynamic::Plot Continuity</category>
       <category id="4" weight="4">Elements::Action</category>
+
       <category cid="4" weight="4">Elements::Action</category>
 
       ...
 
       ...
 
   <categories>
 
   <categories>
 
   <producers>
 
   <producers>
       <producer id="34" type="Financial Production">Bandai Visual</producer>
+
       <producer cid="34" type="Financial Production">Bandai Visual</producer>
       <producer id="108" type="Music Production">BeSTACK</producer>
+
       <producer cid="108" type="Music Production">BeSTACK</producer>
 
       ...
 
       ...
 
   </producers>
 
   </producers>

Revision as of 00:50, 11 February 2009

Early Draft

Note: This is still a very early draft and has not yet been implemented!

General

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

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

Flooding

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.

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. For more information on client registration visit UDP_API_Definition.


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.


Example: URL: http://.../animedb.pl?show=xmlapi&client=clientname&clienver=13&...

Anime Search

Allows lookup of AniDB anime ids (AIDs) by anime title. Additionally AniDB also provides a daily dump with all anime titles which can be used to implement client-side searches, see: API.

Access

Base URL: TBA

Parameters:

  • query={string} [required]
    • the query string to search for.

Example: URL: http://.../animedb.pl?show=xmlapi&...&t=search&query=sometitle


Data

<?xml version="1.0" encoding="utf-8" ?>
<search>
   <anime aid="1">
      <titles>
         <!-- always includes the main title as well as all official titles, synonyms and short titles are not listed -->
         <title type="main" lang="x-jat">Seikai no Monshou</title>
         <title type="official" lang="ja">星界の紋章</title>
         <title type="official" lang="en">Crest of the Stars</title>
         <title type="official" lang="fr">Crest of the Stars</title>
         <title type="official" lang="pl">Crest of the Stars</title>
      </titles>
   </anime>
   <anime aid="2">
      <titles>
         ...
      </titles>
   </anime>
   ...
</search>

Anime Data

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

Access

Base URL: TBA

Parameters:

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


Example: URL: http://.../animedb.pl?show=xmlapi&...&t=anime&aid=1832


Data

<?xml version="1.0" encoding="utf-8" ?>
<anime aid="1">
   <titles>
      <!-- should we include all titles or are official+main title enough? -->
      <title type="main" lang="x-jat">Seikai no Monshou</title>
      <title type="official" lang="ja">星界の紋章</title>
      <title type="official" lang="en">Crest of the Stars</title>
      <title type="official" lang="fr">Crest of the Stars</title>
      <title type="official" lang="pl">Crest of the Stars</title>
   </titles>
   <type>TV Series</type>
   <episodecount>13</episodecount>
   <date>
      <!-- note: dates can also be YYYY-MM-?? and YYYY-??-?? -->
      <from>1999-01-03</from>
      <till>1999-03-28</till>
   </date>
   <categories>
      <category cid="233" weight="6">Dynamic::Plot Continuity</category>
      <category cid="4" weight="4">Elements::Action</category>
      ...
   <categories>
   <producers>
      <producer cid="34" type="Financial Production">Bandai Visual</producer>
      <producer cid="108" type="Music Production">BeSTACK</producer>
      ...
   </producers>
   <relations>
      <!-- relations are always listed with official transcription title -->
      <relation type="sequel" aid="4">Seikai no Senki</type>
      <relation type="prequel" aid="6">Seikai no Danshou</type>
      <relation type="summary" aid="1623">Seikai no Monshou Movie</type>
   </relations>
   <ratings>
      <rating type="permanent" count="2333">8.54</rating>
      <rating type="temporary" count="82">7.61</rating>
      <rating type="review" count="9">9.01</rating>
   </ratings>
   <images>
      <image size="full">http://img5.anidb.net/pics/anime/440.jpg</image>
      <image size="small">http://img5.anidb.net/pics/anime/thumbs/150/440.jpg-thumb.jpg</image>
      <image size="tiny">http://img5.anidb.net/pics/anime/thumbs/50/440.jpg-thumb.jpg</image>
   </images>
   <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>
</anime>