HUKD REST API 2.0
Introduction
As many of you will already know, there are ever increasing numbers of ways for people to interact with information... social networking applications, smartphone applications, desktop widgets, blog widgets, and much more. With the introduction of the new HotUKDeals API, we are hoping that members of our site will help us further develop tools for the community. The hope is that we can encourage people to make new, and interesting ways of accessing Hotukdeals data. The deals and information on Hotukdeals are user driven, created and maintained by the community for the benefit of the community, and we are hoping that these new developments will allow members to help our community continue to grow and benefit from these new ways of accessing information.
We'd appreciate if people could send us feedback, requests and comments on their experience with using the API so we will be able to make improvements.Development related suggestions, concerns, and comments can be shared in this thread.
Getting a Key
To get an API key, visit the following url:
http://www.hotukdeals.com/rest-api (you must be logged in)
and fill out a few details about yourself, and give a brief description about how you will be using the API. One thing to note is, the number of API calls you can make per month is limited. This is to prevent malicious users from over burdening HUKD servers. It is therefore recommended that you keep your key private. Should you require more then the initial allotment for your key, please contact us and we may be able to come to an arrangement.
REST Architecture
The HUKD API uses a fairly standard REST architecture to allow users to retrieve data in either JSON or XML format. Requests/responses are done using the HTTP protocol. To access the API, you will be able to make HTTP requests to the following url:
http://api.hotukdeals.com/rest_api/v2/
The "v2" represents version 2 of the API, and this will increase incrementally as newer versions of the API are released to ensure that API updates generally won't require any changes to websites using older versions of the API.
Simply visiting the above URL will return the following response (in XML):
<api_response>
<error>Your api key is invalid.</error>
</api_response>
No key was specified in that call, so an error was returned, if a key is added to the url by adding the html parameter "output" (ie http://api.hotukdeals.com/rest_api/v2/?key=xxxxx) you will receive the following response:
<api_response>
<deals>
<api_item>
<title>Deal title</title>
<deal_link>http://link to the deal</deal_link>
<mobile_deal_link>
http://m.link to the mobile site deal
</mobile_deal_link>
<deal_image>
http://link to the deals' image (small version)
</deal_image>
<description>description of the deal</description>
<submit_time>formatted string representation</submit_time>
<hot_time>
string, present if deal gone hot
</hot_time>
<poster_name>username of poster</poster_name>
<temperature>deal temperature, as a decimal</temperature>
<timestamp>
unix timestamp of when deal was submitted
</timestamp>
<expired>true or false</expired>
<forum>
<name> forum name </name>
<url_name> url friendly forum name </url_name>
</forum>
<category>
<name> category name </name>
<url_name> url friendly category name </url_name>
</category>
<merchant>
<name> merchant name </name>
<url_name> url friendly merchant name </url_name>
</merchant>
<deal_image_highres>
http://link to the deals' image (high res version)
</deal_image_highres>
</api_item>
etc...
</deals>
<total_results>1000</total_results>
</api_response>
The above example is a standard XML response from the API. Deals are contained in the <deals> node, and each deal is represented by an <api_item> node. Every response in addition to the deals also contains a <total_results> node, which has the total number of results that can be retrieved using the current filter options.
Filter options can be set using different html parameters in the HTTP GET request. The list of availiable parameters is as follows:
- output
-
This parameter is used to determine what type of output you would like to receive in the response.
Omitting this parameter will default to xml output. Currently the possible options are:
json,xml - forum
-
This parameter is used to determine what forum you would like to see deals from. It uses the special
"url name" for the forums. Omitting this parameter will default to all deals. The possible options
are:
all,deals,vouchers,freebies,competitions,deal-requests,for-sale-trade,misc, andfeedback - category
-
This parameter is used to determine what category you would like to see deals from. It uses the special
"url name" for the different categories. Omitting this parameter will default to all deals. The possible
options are:
computers,audiovisual,entertainment,fashion,home,mobiles,travel,groceries,kids,other-deals,gaming,restaurant - merchant
- This parameter is used to determine what merchant you would like to see deals from, it uses the special url name for merchants. To determine what the url name for a particular merchant is, replace all non alphanumeric characters with a hypen ( - max one between two words). For example the merchant "bob & charlie" would become "bob-charlie".
- tag
- This parameter allows you to retrieve deals with particular tags, it also takes special url names, which can be made by replacing all non alphanumeric characters with hypens (max one between two words).
- username
- This parameter allows you to retrieve deals from particular users, valid values for this parameter are valid HUKD user names.
- online_offline
-
This parameter allows you to filter between online and offline deals. Omitting this parameter will default
to all deals. The possible values are:
online,offline. Note: If used in combination with thesearchparameter, onlyonlineis available. - order
-
This parameter determines the order the deals are returned in. There are 3 possible options:
new: this will order the deals by submission date in descending orderdiscussed: this will order the deals by the last posted in date in descending orderhot: this will order the deals by the date they were voted hot by the users, in descending order - page
- This parameter, along with the results_per_page parameter allows you to paginate your results. You pass it the page number of the page you would like to view, so for example, "2" would give you the second set of results for a given filter configuration. (Note: Only the first 1000 results of any filter will be accessible).
- results_per_page
- This parameter allows you to specify how many deals per request you would like returned. This value cannot be more then 500 and the default is 20.
- min_temp
- This parameter allows you to specify the minimum temperature rating of deals that are returned.
- exclude_expired
-
This parameter allows you to prevent expired deals from being returned.Set to
trueto exclude expired deals. - search
-
This parameter allows you to perform a search for a keyword or phrase and takes precedence over other parameters.It can be used in combination with the following parameters:
output, forum, category, online_offline (see note in parameter description), page, results_per_page, exclude_expired. Any other parameters will be ignored.
Thanks for using the HotUKDeals API! We are excited that you're interested in using the API but ask that you follow the guidelines below. Please understand that the guideline rules are not exclusive and if we decide your use of the API is not acceptable we will disable your access.
- (a) Use the API only on the site disclosed to us in your application.
- (b) Have a privacy policy prominently displayed which outlines how you use and store data from your visitors including third party advertisements, data collection and cookie placement.
- (c) Prominently attribute and link to the HotUKDeals site as the source of data in your application and note that the application is not endorsed or certified by HotUKDeals.
- (a) Use the API for any application that replicates or attempts to replicate the HotUKDeals user experience
- (b) Use an unreasonable amount of bandwidth or API requests or any use which places unreasonable stress on the HotUKDeals servers.
- (c) Cache or store HotUKDeals data other than a reasonable period needed to provide your service.
- (d) Use the API for any application associated with spyware, adware or other malicious code.
- (e) Use "hotukdeals" or variants thereof in your url or hostname of the application.
- (f) Use the API for commercial purposes unless prior written consent is obtained from HotUKDeals.
- (g) Display the HotUKDeals logo or mark more prominently than the logo or mark that primarily describes your application.
- (a) HotUKDeals is committed to providing free and open access for commercial and non-commercial applications. However, for uses that are intensive or commercial in nature we reserve the right to charge fees for use or access to the API.
- (b) HotUKDeals makes no guarantees regarding the stability, uptime or quality of data from the API. We do not guarantee support nor future access to the API. At any time the support and access for the API may be suspended or discontinued without notice or liability. Your use of the API is at your own discretion and risk and you agree to be responsible for any damage that results from the use of the API, including but not restricted to, any damage to your computer system(s) or loss of data.
- (c) You agree to hold harmless and indemnify HotUKDeals and any related party, affiliate, partner, or employee from and against any third party claim arising from or related to your use of the API.
- (d) Notwithstanding any provision hereof, for all purposes of the Terms of Service, you and HotUKDeals shall be and act independently and not as partner, joint venturer, agent, employee or employer of the other.
- (e) The Terms of Service and the relationship between you and HotUKDeals shall be governed by the laws of England and the parties submit to the exclusive jurisdiction of the Courts of England and Wales.
- (f) HotUKDeals failure to exercise or enforce any right or provision of the Terms of service shall not constitute a waiver of such right or provision.