FreeCovers.net

What is the FreeCovers API

The FreeCovers API has been created to allow folks to easily add content to their site, by integrating our content into their design.

The API allows full-freedom in how you use the content you retrieve, and is a great way to add that extra something to your site.

How to use the API

The API accepts REST requests and returns results as a simple XML file.

To receive an XML file with search results, send a request to a url formatted like this:

http://www.freecovers.net/api/search/:search_phrase:

Note that all sample code in this page is written in PHP and uses the SimpleXML functions.

Here is an example of constructing a url for a cover search:

<?php
$search_phrase = 'terror twilight';
$xml_request_url = 'http://www.freecovers.net/api/search/'.urlencode($search_phrase);
?>

To retrieve the xml results file, simply send a query to the url we constructed in the previous step:

$xml = new SimpleXMLElement($xml_request_url, null, true);

The results you will receive in XML will take this form:

<rsp stat="ok">
<title>
<name>Pavement - Terror Twilight</name>
<id>c481c3a34958fe24483cff939148e4d9</id>
<added>2007-03-11 22:40:48</added>
<uploader>i said woof</uploader>
<category>Music CD</category>
<image>http://www.freecovers.net/thumb/0/c481c3a34958fe24483cff939148e4d9/preview.jpg</image>
<covers>
<cover>
<type>front</type>
<width>1600</width>
<height>800</height>
<filesize>2709598</filesize>
<url>http://www.freecovers.net/view/0/c481c3a34958fe24483cff939148e4d9/Pavement_-_Terror_Twilight-front.html</url>
<thumbnail>http://www.freecovers.net/thumb/0/c481c3a34958fe24483cff939148e4d9/front.jpg</thumbnail>
<preview>http://www.freecovers.net/preview/0/c481c3a34958fe24483cff939148e4d9/big.jpg</preview>
</cover>
<cover>
<type>back</type>
<width>1025</width>
<height>800</height>
<filesize>1263268</filesize>
<url>http://www.freecovers.net/view/1/c481c3a34958fe24483cff939148e4d9/Pavement_-_Terror_Twilight-back.html</url>
<thumbnail>http://www.freecovers.net/thumb/1/c481c3a34958fe24483cff939148e4d9/back.jpg</thumbnail>
<preview>http://www.freecovers.net/preview/1/c481c3a34958fe24483cff939148e4d9/big.jpg</preview>
</cover>
</covers>
</title>
</rsp>

Now all you have to do is go over the results file and format your output.

foreach ($xml as $title) {
echo 'Title: '.$title->name;
echo 'Category: '.$title->category;
echo 'Upload date: '.$title->added;
echo 'Image: '.$title->image;
foreach ($title->covers->cover as $cover) {
echo 'Cover type:'.$cover->type;
echo 'Resolution:'.$cover->width.'x'.$cover->height;
echo 'Filesize:'.$cover->filesize;
echo 'Download page:'.$cover->url;
echo 'Thumbnail:'.$cover->thumbnail;
}
}
?>

Limiting results by category

You can limit the results returned to just one category of titles - such as Xbox 360, Music CD, or Wii - by adding the category name to the end of the request url. There is a list of our categories at the bottom of this page.

For example, a search for Radiohead covers:

http://www.freecovers.net/api/search/radiohead

Becomes a search for Radiohead Music DVD covers:

http://www.freecovers.net/api/search/radiohead/Music+DVD

Complete working example

The following example connects to the site, retrieves all results for "terror twilight" and displays them.

<?php
$search_phrase = 'terror twilight';
$xml_request_url = 'http://www.freecovers.net/api/search/'.urlencode($search_phrase);
$xml = new SimpleXMLElement($xml_request_url, null, true);
if (isset($xml->err)) {
echo $xml->err['msg'];
} else {
foreach ($xml as $title) {
echo 'Title: '.$title->name;
echo 'Category: '.$title->category.': '.$title->subcategory;
echo 'Upload date: '.$title->added;
echo 'Image: '.$title->image;
foreach ($title->covers->cover as $cover) {
echo 'Cover type:'.$cover->type;
echo 'Resolution:'.$cover->width.'x'.$cover->height;
echo 'Filesize:'.$cover->filesize;
echo 'Download page:'.$cover->url;
echo 'Thumbnail:'.$cover->thumbnail;
}
}
}
?>

And that's it… Simple as that.

Just remember to use the urlencode function!

Categories are:

Anime DVD
Blu-Ray Movie
DVD Movie
HD-DVD Movie
GameCube
Music CD
Music DVD
Other
Other Console
PC Apps
PC Games
Playstation
Playstation 2
Playstation 3
PSP
Soundtrack
TV Series
VCD
VHS
Wii
Xbox
Xbox 360