Please use v3 of the API, you can find the documentation here

Usage

Summary

Returns the requested artwork for a specific show

 

URL

http://api.fanart.tv/webservice/series/apikey/thetvdb_id/format/type/sort/limit/

Updates

You can now get a list of all the shows that have been updated since you last checked, you can then match this list against local shows and just update those instead of checking for every single show

http://api.fanart.tv/webservice/newtv/apikey/timestamp/

If you omit the timestamp then shows updated in the last 2 days will be returned, if included it must be a valid UNIX timestamp

Supported formats

  • json
  • php

 

Required Parameters

  • apikey
    login to view your apikey
  • thetvdb_id
    You can find a shows id from thetvdb.com

 

Optional Parameters

The following parameters are optional but if you want to change any from the default value you must specify all optional parameters before the one you are changing (so if you are changing just format you don’t have to specify type, but if you want to change the sort you MUST also specify the format and type)

  • format
    Returns the results in the requested format
    json (default) / php (returns a php serialized object)
  • type
    Returns the requested image types
    all (default) / clearlogo / clearart / characterart / tvthumb / seasonthumb
  • sort
    1 – Sorted by most popular image then newest(default)
    2 – Sorted by newest uploaded image
    3 – Sorted by oldest uploaded image
  • limit
    Value is either 1 (1 image) or 2 (all images – default), for example, when automatically downloading images you might only want to return the first result so the user doesn’t have to provide input, whereas with a manual download you might want the user to see all the options.

 

Additional info

    • preview
      When you add the “/preview” suffix to the artwork url you get the reduced in size sample image. This causes the reduce the traffic load on the site en the example images show much faster. This is the prefered way of pre-showing images because this will not increase the download counter.

      http://fanart.tv/tv/75682/clearlogo/bones-4e764b27c454d.png/preview

Image size of preview: width=200

  • textless images will be returned as 00 (that is zero zero) as the value for the lang attribute.

 

Example requests:

http://api.fanart.tv/webservice/series/211215efd1b535c7dfa31fb60f15ef14/70346/

http://api.fanart.tv/webservice/series/211215efd1b535c7dfa31fb60f15ef14/70346/JSON/all/1/1/

 

Examples

Example JSON Response

http://127.0.0.1/webservice/series/211215efd1b535c7dfa31fb60f15ef14/75682/json/

{
"series":"Bones",
"clearlogos":[
{
"id":"13571",
"url":"http:\/\/fanart.tv\/tv\/75682\/clearlogo\/bones-4e764b27c454d.png",
"lang":"ar",
"likes":"0"
},
{
"id":"2112",
"url":"http:\/\/fanart.tv\/tv\/75682\/clearlogo\/Bones-75682.png",
"lang":"en",
"likes":"0"
}
],
"cleararts":[
{
"id":"11780",
"url":"http:\/\/fanart.tv\/tv\/75682\/clearart\/bones-4df372a733e83.png",
"lang":"en",
"likes":"0"
},
{
"id":"4302",
"url":"http:\/\/fanart.tv\/tv\/75682\/clearart\/B_75682 (2).png",
"lang":"en",
"likes":"0"
},
{
"id":"14248",
"url":"http:\/\/fanart.tv\/tv\/75682\/clearart\/bones-4eaad22395670.png",
"lang":"en",
"likes":"0"
},
{
"id":"4303",
"url":"http:\/\/fanart.tv\/tv\/75682\/clearart\/B_75682.png",
"lang":"en",
"likes":"0"
},
{
"id":"14236",
"url":"http:\/\/fanart.tv\/tv\/75682\/clearart\/bones-4ea9d3aa69c05.png",
"lang":"en",
"likes":"0"
},
{
"id":"4304",
"url":"http:\/\/fanart.tv\/tv\/75682\/clearart\/B_75682 (0).png",
"lang":"en",
"likes":"0"
},
{
"id":"4301",
"url":"http:\/\/fanart.tv\/tv\/75682\/clearart\/B_75682 (3).png",
"lang":"en",
"likes":"0"
},
{
"id":"14250",
"url":"http:\/\/fanart.tv\/tv\/75682\/clearart\/bones-4eab178bc58f5.png",
"lang":"en",
"likes":"0"
}
],
"tvthumbs":[
{
"id":"4321",
"url":"http:\/\/fanart.tv\/tv\/75682\/tvthumb\/B_75682.jpg",
"lang":"en",
"likes":"0"
},
{
"id":"4318",
"url":"http:\/\/fanart.tv\/tv\/75682\/tvthumb\/B_75682 (4).jpg",
"lang":"en",
"likes":"0"
},
{
"id":"4322",
"url":"http:\/\/fanart.tv\/tv\/75682\/tvthumb\/B_75682 (1).jpg",
"lang":"en",
"likes":"0"
},
{
"id":"4319",
"url":"http:\/\/fanart.tv\/tv\/75682\/tvthumb\/B_75682 (3).jpg",
"lang":"en",
"likes":"0"
},
{
"id":"4323",
"url":"http:\/\/fanart.tv\/tv\/75682\/tvthumb\/B_75682 (0).jpg",
"lang":"en",
"likes":"0"
},
{
"id":"4320",
"url":"http:\/\/fanart.tv\/tv\/75682\/tvthumb\/B_75682 (2).jpg",
"lang":"en",
"likes":"0"
},
{
"id":"4317",
"url":"http:\/\/fanart.tv\/tv\/75682\/tvthumb\/B_75682 (5).jpg",
"lang":"en",
"likes":"0"
}
],
"seasonthumbs":[
{
"id":"4308",
"url":"http:\/\/fanart.tv\/tv\/75682\/seasonthumb\/Bones (7).jpg",
"lang":"en",
"likes":"0",
"season":"3"
},
{
"id":"4305",
"url":"http:\/\/fanart.tv\/tv\/75682\/seasonthumb\/B_75682.jpg",
"lang":"en",
"likes":"0",
"season":"6"
},
{
"id":"4315",
"url":"http:\/\/fanart.tv\/tv\/75682\/seasonthumb\/Bones (1).jpg",
"lang":"en",
"likes":"0",
"season":"1"
},
{
"id":"4312",
"url":"http:\/\/fanart.tv\/tv\/75682\/seasonthumb\/Bones (4).jpg",
"lang":"en",
"likes":"0",
"season":"4"
},
{
"id":"4309",
"url":"http:\/\/fanart.tv\/tv\/75682\/seasonthumb\/Bones (6).jpg",
"lang":"en",
"likes":"0",
"season":"2"
},
{
"id":"4306",
"url":"http:\/\/fanart.tv\/tv\/75682\/seasonthumb\/Bones (9).jpg",
"lang":"en",
"likes":"0",
"season":"5"
},
{
"id":"4316",
"url":"http:\/\/fanart.tv\/tv\/75682\/seasonthumb\/Bones (0).jpg",
"lang":"en",
"likes":"0",
"season":"0"
},
{
"id":"4313",
"url":"http:\/\/fanart.tv\/tv\/75682\/seasonthumb\/Bones (3).jpg",
"lang":"en",
"likes":"0",
"season":"3"
},
{
"id":"4310",
"url":"http:\/\/fanart.tv\/tv\/75682\/seasonthumb\/Bones.jpg",
"lang":"en",
"likes":"0",
"season":"1"
},
{
"id":"4307",
"url":"http:\/\/fanart.tv\/tv\/75682\/seasonthumb\/Bones (8).jpg",
"lang":"en",
"likes":"0",
"season":"4"
},
{
"id":"4314",
"url":"http:\/\/fanart.tv\/tv\/75682\/seasonthumb\/Bones (2).jpg",
"lang":"en",
"likes":"0",
"season":"2"
},
{
"id":"4311",
"url":"http:\/\/fanart.tv\/tv\/75682\/seasonthumb\/Bones (5).jpg",
"lang":"en",
"likes":"0",
"season":"5"
}
]
}

 

Example PHP Response

http://127.0.0.1/webservice/series/211215efd1b535c7dfa31fb60f15ef14/75682/php/

a:5:{s:6:"series";s:5:"Bones";s:10:"clearlogos";a:2:{i:0;a:4:{s:2:"id";s:5:"13571";s:3:"url";s:59:"http://fanart.tv/tv/75682/clearlogo/bones-4e764b27c454d.png";s:4:"lang";s:2:"ar";s:5:"likes";s:1:"0";}i:1;a:4:{s:2:"id";s:4:"2112";s:3:"url";s:51:"http://fanart.tv/tv/75682/clearlogo/Bones-75682.png";s:4:"lang";s:2:"en";s:5:"likes";s:1:"0";}}s:9:"cleararts";a:8:{i:0;a:4:{s:2:"id";s:5:"11780";s:3:"url";s:58:"http://fanart.tv/tv/75682/clearart/bones-4df372a733e83.png";s:4:"lang";s:2:"en";s:5:"likes";s:1:"0";}i:1;a:4:{s:2:"id";s:4:"4302";s:3:"url";s:50:"http://fanart.tv/tv/75682/clearart/B_75682 (2).png";s:4:"lang";s:2:"en";s:5:"likes";s:1:"0";}i:2;a:4:{s:2:"id";s:5:"14248";s:3:"url";s:58:"http://fanart.tv/tv/75682/clearart/bones-4eaad22395670.png";s:4:"lang";s:2:"en";s:5:"likes";s:1:"0";}i:3;a:4:{s:2:"id";s:4:"4303";s:3:"url";s:46:"http://fanart.tv/tv/75682/clearart/B_75682.png";s:4:"lang";s:2:"en";s:5:"likes";s:1:"0";}i:4;a:4:{s:2:"id";s:5:"14236";s:3:"url";s:58:"http://fanart.tv/tv/75682/clearart/bones-4ea9d3aa69c05.png";s:4:"lang";s:2:"en";s:5:"likes";s:1:"0";}i:5;a:4:{s:2:"id";s:4:"4304";s:3:"url";s:50:"http://fanart.tv/tv/75682/clearart/B_75682 (0).png";s:4:"lang";s:2:"en";s:5:"likes";s:1:"0";}i:6;a:4:{s:2:"id";s:4:"4301";s:3:"url";s:50:"http://fanart.tv/tv/75682/clearart/B_75682 (3).png";s:4:"lang";s:2:"en";s:5:"likes";s:1:"0";}i:7;a:4:{s:2:"id";s:5:"14250";s:3:"url";s:58:"http://fanart.tv/tv/75682/clearart/bones-4eab178bc58f5.png";s:4:"lang";s:2:"en";s:5:"likes";s:1:"0";}}s:8:"tvthumbs";a:7:{i:0;a:4:{s:2:"id";s:4:"4321";s:3:"url";s:45:"http://fanart.tv/tv/75682/tvthumb/B_75682.jpg";s:4:"lang";s:2:"en";s:5:"likes";s:1:"0";}i:1;a:4:{s:2:"id";s:4:"4318";s:3:"url";s:49:"http://fanart.tv/tv/75682/tvthumb/B_75682 (4).jpg";s:4:"lang";s:2:"en";s:5:"likes";s:1:"0";}i:2;a:4:{s:2:"id";s:4:"4322";s:3:"url";s:49:"http://fanart.tv/tv/75682/tvthumb/B_75682 (1).jpg";s:4:"lang";s:2:"en";s:5:"likes";s:1:"0";}i:3;a:4:{s:2:"id";s:4:"4319";s:3:"url";s:49:"http://fanart.tv/tv/75682/tvthumb/B_75682 (3).jpg";s:4:"lang";s:2:"en";s:5:"likes";s:1:"0";}i:4;a:4:{s:2:"id";s:4:"4323";s:3:"url";s:49:"http://fanart.tv/tv/75682/tvthumb/B_75682 (0).jpg";s:4:"lang";s:2:"en";s:5:"likes";s:1:"0";}i:5;a:4:{s:2:"id";s:4:"4320";s:3:"url";s:49:"http://fanart.tv/tv/75682/tvthumb/B_75682 (2).jpg";s:4:"lang";s:2:"en";s:5:"likes";s:1:"0";}i:6;a:4:{s:2:"id";s:4:"4317";s:3:"url";s:49:"http://fanart.tv/tv/75682/tvthumb/B_75682 (5).jpg";s:4:"lang";s:2:"en";s:5:"likes";s:1:"0";}}s:12:"seasonthumbs";a:12:{i:0;a:5:{s:2:"id";s:4:"4308";s:3:"url";s:51:"http://fanart.tv/tv/75682/seasonthumb/Bones (7).jpg";s:4:"lang";s:2:"en";s:5:"likes";s:1:"0";s:6:"season";s:1:"3";}i:1;a:5:{s:2:"id";s:4:"4305";s:3:"url";s:49:"http://fanart.tv/tv/75682/seasonthumb/B_75682.jpg";s:4:"lang";s:2:"en";s:5:"likes";s:1:"0";s:6:"season";s:1:"6";}i:2;a:5:{s:2:"id";s:4:"4315";s:3:"url";s:51:"http://fanart.tv/tv/75682/seasonthumb/Bones (1).jpg";s:4:"lang";s:2:"en";s:5:"likes";s:1:"0";s:6:"season";s:1:"1";}i:3;a:5:{s:2:"id";s:4:"4312";s:3:"url";s:51:"http://fanart.tv/tv/75682/seasonthumb/Bones (4).jpg";s:4:"lang";s:2:"en";s:5:"likes";s:1:"0";s:6:"season";s:1:"4";}i:4;a:5:{s:2:"id";s:4:"4309";s:3:"url";s:51:"http://fanart.tv/tv/75682/seasonthumb/Bones (6).jpg";s:4:"lang";s:2:"en";s:5:"likes";s:1:"0";s:6:"season";s:1:"2";}i:5;a:5:{s:2:"id";s:4:"4306";s:3:"url";s:51:"http://fanart.tv/tv/75682/seasonthumb/Bones (9).jpg";s:4:"lang";s:2:"en";s:5:"likes";s:1:"0";s:6:"season";s:1:"5";}i:6;a:5:{s:2:"id";s:4:"4316";s:3:"url";s:51:"http://fanart.tv/tv/75682/seasonthumb/Bones (0).jpg";s:4:"lang";s:2:"en";s:5:"likes";s:1:"0";s:6:"season";s:1:"0";}i:7;a:5:{s:2:"id";s:4:"4313";s:3:"url";s:51:"http://fanart.tv/tv/75682/seasonthumb/Bones (3).jpg";s:4:"lang";s:2:"en";s:5:"likes";s:1:"0";s:6:"season";s:1:"3";}i:8;a:5:{s:2:"id";s:4:"4310";s:3:"url";s:47:"http://fanart.tv/tv/75682/seasonthumb/Bones.jpg";s:4:"lang";s:2:"en";s:5:"likes";s:1:"0";s:6:"season";s:1:"1";}i:9;a:5:{s:2:"id";s:4:"4307";s:3:"url";s:51:"http://fanart.tv/tv/75682/seasonthumb/Bones (8).jpg";s:4:"lang";s:2:"en";s:5:"likes";s:1:"0";s:6:"season";s:1:"4";}i:10;a:5:{s:2:"id";s:4:"4314";s:3:"url";s:51:"http://fanart.tv/tv/75682/seasonthumb/Bones (2).jpg";s:4:"lang";s:2:"en";s:5:"likes";s:1:"0";s:6:"season";s:1:"2";}i:11;a:5:{s:2:"id";s:4:"4311";s:3:"url";s:51:"http://fanart.tv/tv/75682/seasonthumb/Bones (5).jpg";s:4:"lang";s:2:"en";s:5:"likes";s:1:"0";s:6:"season";s:1:"5";}}}

Example code

PHP Examples

Using JSON

$request = file_get_contents("http://api.fanart.tv/webservice/series/211215efd1b535c7dfa31fb60f15ef14/80348/json/");
$art = json_decode($request);
foreach($art->clearlogos as $logo) {
echo $logo->url."
"
;
}

Using PHP Serialized array

$request = file_get_contents("http://fanart.tv/webservice/series/211215efd1b535c7dfa31fb60f15ef14/80348/php/");
$art = unserialize($request);
foreach($art["clearlogos"] as $logo) {
echo $logo["url"]."
"
;
}

JSON Examples

Using python

class FTV_TVProvider():

def __init__(self):
self.name = 'fanart.tv - TV API'
self.api_key = 'you API key here'
self.url = "http://api.fanart.tv/webservice/series/%s/%s/json/all/1/2"
self.imagetypes = ['clearlogo', 'clearart', 'tvthumb', 'seasonthumb', 'characterart']

def get_image_list(self, media_id):
data = get_json(self.url % (self.api_key,media_id))
image_list = []
# Get fanart
# split "name" and "data"
for title, value in data.iteritems():
# run through specified types
for art in self.imagetypes:
# if type has been found
if value.has_key(art):
# Run through all the items
for item in value[art]:
info = {}
info['url'] = urllib.quote(item['url'], ':/') # Original image url
info['preview'] = info['url'] + "/preview" # Create a preview url for later use
info['id'] = item['id']
info['type'] = art
if item.has_key('season'):
info['season'] = item['season']
else:
info['season'] = 'n/a'
# language and votes
info['language'] = item['lang']
info['votes'] = item['likes']
# Add data to list
if info:
image_list.append(info)