Home
Contact
My last uploads
Register
Login
Album list
Last comments
Most viewed
Top rated
My Favorites
Search
Contributors
API
Programmers API
Table of Content
About this
The API is intended to give developers the opportunity to user our data. It will providing you with XML formed search results and a way to download images which you can use in your software.
What you need to use the API
To use our data in your applications you will have to:
- Contact api@htbackdrops.com
and get a free key that will enable you to access the API.
Please include a valid username to htbackdrops.com, the name of your application and - if available - a website URL. - Respect our servers and do as little queries as you can.
- Let your users know where the data comes from. We want this community to grow and what better target audiance is there than the people who use a product? :)
Once you acquired an API key you can access the API through the URLs provided below by replacing <YOUR_API_KEY> with your actual key.
Feel free to use "TESTKEY" for testing purposes. Downloads are limited to thumbnail size with this key.
Usage
How To Find Images
You can perform a search by utilizing the following URL:
http://htbackdrops.com/api/<YOUR_API_KEY>/searchXML
and get XML formed search results (example).
You can use POST or GET method to perform a search using the arguments listed below. You even can provide a json encoded array containing any of the arguments.
To do so just use the argument json_input.
E.g. "searchXML?json_input={"keywords":"madonna"}"
How To Download Images
The search will return a set of matched images including an image ID (pid) which you can use to download the image in various sizes by using:
http://htbackdrops.com/api/<YOUR_API_KEY>/download/<PICTURE_ID>/thumbnail (max. width and height of 125px)
http://htbackdrops.com/api/<YOUR_API_KEY>/download/<PICTURE_ID>/intermediate (max. width and height of 800px)
http://htbackdrops.com/api/<YOUR_API_KEY>/download/<PICTURE_ID>/fullsize (original full-size image)
Arguments to use for a search
| Keyword Limiters | |||
| Argument | Type | Option | Example |
| keywords Keywords to search for |
String seperate keywords with spaces |
you can prepend any keyword with + or - +: The keyword must be in the result. -: The keyword mustn't be in the result. |
"keywords=madonna pink" Every result will contain atleast one of the keywords. "keywords=madonna -pink" Every result will contain "madonna" but not "pink". "keywords=madonna +pink" Every result will contain "pink" and maybe madonna. "keywords=-madonna +pink" Every result will contain "pink" but not "madonna". "keywords=+madonna +pink" Every result will contain "pink" and "madonna". This can also be achived by using the default_operator variable (see below) e.g. "keywords=madonna pink&default_operator=and" |
| default_operator Operator to connect keywords with |
String | Allowed: and, or Default: or |
"default_operator=and" |
| fields Fields to search in |
String seperate multiple fields with "," |
Allowed: all, title, keywords, caption Allowed MusicBrainz: mb_name, mb_alias, mb_tag Default: title,caption,keywords |
"fields=title,mb_name,mb_alias" |
| mbid ID for MusicBrainz |
String | "mbid=79239441-bfd5-4981-a70c-55c3f15c1287" This will select all images for artist Madonna. |
|
| Output Limiters | |||
| Argument | Type | Option | Example |
| inc What information to return in the results |
String seperate multiples with "," |
Allowed: keywords, caption, rating Allowed MusicBrainz: mb_name, mb_aliases, mb_tags Default: keywords, caption, rating |
"inc=rating,mb_aliases" |
| limit Limit to this many results |
Integer | Default: 500 | "limit=20" |
| offset Offset of results to start from |
Integer | Default: 0 | "offset=20" |
| encoding Set the output encoding |
String | Allowed: UTF-8, iso-8859-1 Default: UTF-8 |
"encoding=iso-8859-1" |
| cid Category ID to search in |
Integer seperate multiple IDs with "," |
See category list | "cid=5" or "cid=5,6" This is an upstream selection option for album IDs. "cid=1" has the same effect as "aid=1,5,26". |
| aid Album ID to search in |
Integer seperate multiple IDs with "," |
See category list | "aid=1" or "aid=1,5,26" |
| File Attribute Limiters | |||
| Argument | Type | Option | Example |
| new_since Only return newer files |
Unix timestamp |
"new_since=1284008400" will return only files added after 09/09/2010. We advice you to use the servertime timestamp returned with every search. |
|
| modified_since Only return modified files |
Unix timestamp |
"modified_since=1284008400" will return only files modified after 09/09/2010. This works just like new_since but the timestamp in the database is updated more frequently e.g. on upload approval and name changes. We advice you to use the servertime timestamp returned with every search. |
|
| max_filesize Limits filesize of results. |
Integer Has to be in bytes. |
"max_filsize=102400" for a max filsize of 100kb |
|
| dmax_w Limits maximum picture width to x pixel |
Integer | "dmax_h=1920" | |
| dmax_h Limits maximum picture height to x pixel |
Integer | "dmax_h=1080" | |
| dmin_w Limits minimum picture width to x pixel |
Integer | "dmin_h=1920" | |
| dmin_h Limits minimum picture height to x pixel |
Integer | "dmin_h=1080" | |
| dratio Limits picture pixel ratio to x:y |
String | "dratio=16:9" | |
Category / Album List
| Category / Album List | ||
| Argument | Title | |
| cid=2 | Games | |
| aid=2 | Game Backdrops (16:9) | |
| aid=29 | Game Boxes | |
| aid=30 | Other | |
| cid=3 | Generic / Other | |
| aid=28 | Applications | |
| aid=32 | Comic | |
| aid=7 | Games - Generic | |
| aid=14 | Home Theaters | |
| aid=12 | Misc | |
| aid=8 | Movies - Generic | |
| aid=9 | Music - Generic | |
| aid=13 | Photo Backdrops | |
| aid=10 | Settings - Generic | |
| aid=27 | Splash Screens | |
| aid=23 | Stand-Up Comedians | |
| aid=11 | TV - Generic | |
| cid=4 | Generic / Other - Weather | |
| aid=17 | Cloudy/Snow-Rain Mix | |
| aid=18 | Hail | |
| aid=21 | Haze/Rain | |
| aid=19 | Icy/Clouds Rain-Snow | |
| aid=20 | Icy/Haze Rain | |
| aid=22 | Icy/Rain | |
| aid=3 | Other | |
| aid=15 | Rain/Lightning | |
| aid=33 | Sunny | |
| aid=16 | Windy/Rain | |
| cid=5 | Music Artist | |
| aid=5 | Music Artist Thumbnails (1:1) | |
| aid=1 | Music Artist Backdrops (16:9) | |
| aid=26 | Other | |
Workflow suggestion for Music Artist search
To get the best results when searching for images associated to an music artist we advice you to stick to the following workflow:
Use these arguments to search:
- keywords=Artist+Name
- default_operator=and
- aid=1,5,26
- fields=title,keywords,caption,mb_name,mb_alias
- inc=keywords,caption,mb_name,mb_aliases
By doing this we will not only look for an image titled like your Artist Name but also check for matches in the associated MusicBrainz database for known aliases. A complete GET request looks like this:
http://htbackdrops.com/api/TESTKEY/searchXML?keywords=madonna&default_operator=and&aid=1,5,26&fields=title,keywords,caption,mb_name,mb_alias&inc=keywords,caption,mb_name,mb_aliasesCompare your artist name agains XML result fields title, mb_name, mb_sort_name and every field of the mb_aliases node.
Contribute
If you are willing to contribute classes or code snippets in any programming language, that will make it easier for others to get startet, we would love to put them here. Just contact us at api@htbackdrops.com.
Snippets & Examples
| Language | Contributor | Description | Licence | |
| C# (Visual Studio 2010 Project) | thermacore | Simple Visual Studio Project to get you started. It will search for a keyword, download a random image from the result and show it as the applications background. | Free to use | Download |