Usuage
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
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"
}
]
}
"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."
";
}
$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"]."
";
}
$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)
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)