JSON api, iPhone app, New Features

Posted: Sun Nov 23, 2008 5:00 pm

Time for announcing some changes and additions to isoHunt.com, both visible and behind the scenes.

First, a treat for web programmers: we are releasing a new JSON interface to our search results, so you can create innovative new apps, widgets, mashups and frontends using our data. Think desktop widgets, Facebook apps, and iGoogle gadgets. Simple API docs follow this post in this comment. For users, what matters is the apps made using this, and here are 2 great examples.

1. iPhone search with uTorrent webui integration from Team Louish
This app searches isoHunt.com using our JSON interface, and displays results formatted for iPhones or similarly small sized screens, like Blackberry or other smartphones. If you installed uTorrent's WebUI and the iPhone variation, you can save its IP and port as a cookie on the web app, and you can click (or rather, finger) the blue circular icon next to any search result to send the torrent to your uTorrent for download. For iPhone/smartphone and uTorrent users, this is unbeatable. This lets you search for torrents wherever you are, and remotely start downloads on your uTorrent client at home quickly. You can see a sample search for ubuntu on the app here, or see link above for screenshots of the app in action on an iPhone.

For the uTorrent integration, you are perhaps wary of privacy issue in sharing your uTorrent webui's IP/port with a website. You should be. But in this case, looking at their HTML source, your webui's IP and port are stored as a cookie in your phone's browser, and the links for sending torrents to your uTorrent are generated client-side by Javascript. None of these touches any server, just your browser direct to your uTorrent webui. The search requests of course have to go to Team Louish's server which in turn hit our JSON api.

2. Vuze search template
This file adds isoHunt search results to Vuze's meta search. I you have Vuze (previously named Azureus) installed, this file would open in Vuze. I appreciate various user made templates before, but most of them didn't parse our search results quite right. This template uses our JSON interface and includes convenient, direct torrent download links in Vuze search. I've tried talking to the Vuze guys before on including isoHunt as a default search, but they have shown more interest in including search engines with poorer and more outdated results than they have shown us. Maybe you'll have better luck than me.

You can also find Vuze search templates for Torrentbox and Podtropolis here. Refer to this thread for discussion specific to the Vuze search templates.

For isoHunt site updates, we've added direct voting on your download history:

After registering and downloading .torrent files while logged in to isoHunt, you always had the option to save your download history for reference later. To further encourage community involvement in moderating torrents in our search results, we have added direct Feedback voting (+1 / -1) in your download history. You can see your download history as seen in sample in above screenshot, on the first page after logging in to isoHunt. If you are already logged in, click the Settings & History link at top right on isoHunt to go back to it.

You may also notice the "RSS feeds of your download history" link in the above screenshot, which we added a few weeks back. This gives you a private feed of your download history. One use of this is subscribe to your personal feed in your BitTorrent client. That way, whenever and wherever you click .torrent files on isoHunt while logged in, your BT client would pick up the latest from the feed and start downloading. Another way to remote download torrents from isoHunt, especially if you don't use uTorrent. Or perhaps you want to show your friends what you are downloading, by importing your RSS into your blog or Facebook wall. Your private feed is secure as long as you don't share its URL, or import it on where you don't want prying eyes from seeing them. Social networks may have enough privacy control to make this useful for you.

And to improve our references to indexed sites per torrent:

Previously, only 1 indexed site is linked on our torrent details pages, on a first indexed first shown basis. This is still the case, but under it, on mouse over the indexed link, you'll see all other sites from where we indexed the same .torrent file. The "find comments elsewhere" link after it would Google the torrent's unique info_hash for any further references to it, if we missed any.

By checking lists of sites where torrents originated, you have more safeguard against spam. For example, a ubuntu torrent, listed from torrent.ubuntu.com as seen in above screenshot, pretty much guarantees you are not getting a spam or fake torrent that's not what its filenames say it is. All the more reasons and ways you can use isoHunt as your first stop to search for torrents from anywhere, and you'll find all references to research further online. Props to Patcito who helped code most of these updates.

Posted: Sun Nov 23, 2008 5:43 pm

Calls to our JSON api have URL format like this:

Quote:

http://isohunt.com/js/json.php?ihq=ubuntu&start=21&rows=20&sort=seeds

Where parameters:

ihq
Takes url encoded value as requested search query.

start
Optional. Starting row number in paging through results set. First page have start=1, not 0. Defaults to 1.

rows
Optional. Results to return, starting from parameter "start". Defaults to 100.

sort
Optional. Defaults to composite ranking (over all factors such as age, query relevance, seed/leechers counts and votes). Parameter takes only values of "seeds", "age" or "size", where seeds sorting is combination of seeds+leechers. Sort order defaults to descending.

order
Optional, can be either "asc" or "desc". Defaults to descending, in conjunction with sort parameter.

~~noSL~~
Deprecated. All torrents are returned, whether they have seeds/leechers or not.

Above same JSON call would search for "ubuntu", returning 2nd page of results, with 20 results per page. Sorts by seeds and leechers, and include torrents with S/L stats only.

rows have upper limit of 100, and start+rows have maximum possible limit of 1000.

NOTE:
In using our search API, you are free to do with it as you wish on condition that if your app is available publicly to users, you must link to torrent details pages on isoHunt.com, whether you link to the .torrent files or not. We reserve the right to ban you from using our API if you don't follow this simple rule. Refer to Louish's iPhone app for a good example of including links to our torrent details pages. Our torrent details pages have URLs like this: http://isohunt.com/torrent_details/28289948/ubuntu?tab=summary

While we don't require developer tokens or place hard limits on api calls usage, excessive calls will also result in bans. If you think your app will consistently sustain multiple calls per second to our api, email admin at this site's domain first.

You are free to promote your app using our API, by replying under this post or post under this forum. If your app is really good, we'll likely want to spotlight it on isoHunt's frontpage. Multiple posts to promote your app on our forum or comments is not allowed however, and will be treated as spam.

Changelog

May 11, 2009 : Fixed wrong results sorting in default composite sorting method
Feb. 20, 2010: Fixed critical bugs, including incorrect sorting and missing/inconsistent results. Also added various data elements in results, including original_link and excerpts
Mar. 20, 2010: total_results: value set to 0 if empty
May 6, 2010: New "sort" parameter options (age, size), new parameter "order" in conjunction. Updated and added various data fields in returned json data.
Aug. 28, 2010: Deprecated noSL param

Posted: Tue Nov 25, 2008 12:51 pm

Hello. I can see that download history is a very impressive feature - Something I may just have to use myself one day.

Two questions concerning security:

-Is a user's download history kept by default?

-Are you storing any information that links usernames to IP addresses?

I think you can see what I'm getting at, and although I respect isohunt's policy on people's privacy to date (awesome job, actually Very Happy

), this is somewhat concerning. Maybe if there was a one-way information flow of Username to RSS feed (i.e. hash from login/password combo, store in $sesison, and then use said hash to reference an RSS user history), and it were clearly one-way, then it would be acceptable.

I'm just curious what you currently have means for us users. Shocked

Thanks

Posted: Tue Nov 25, 2008 1:05 pm

@jetdog: you can enable/disable the download history manager on http://isohunt.com/member.php and I think it's disabled by default.

@IH: thanks for the props and helping me too Smile

Posted: Tue Nov 25, 2008 2:23 pm

jetdog wrote:

Hello. I can see that download history is a very impressive feature - Something I may just have to use myself one day.

Two questions concerning security:

-Is a user's download history kept by default?

-Are you storing any information that links usernames to IP addresses?

I think you can see what I'm getting at, and although I respect isohunt's policy on people's privacy to date (awesome job, actually Very Happy

), this is somewhat concerning. Maybe if there was a one-way information flow of Username to RSS feed (i.e. hash from login/password combo, store in $sesison, and then use said hash to reference an RSS user history), and it were clearly one-way, then it would be acceptable.

I'm just curious what you currently have means for us users. Shocked

Thanks

It is kept by default for new users, but you can turn it off on the Settings & History page everytime you login. Beside the option, there's also link to delete all past histories whenever you want.

Obtaining your history RSS is one way, the URL is hashed and salted to your account. That's why I said be careful to share that URL on only where/to who you trust.

Posted: Tue Nov 25, 2008 3:15 pm

Oooohh! nice changes Very Happy

Posted: Tue Nov 25, 2008 3:46 pm

Great stuff...big ups patcito Smile

Posted: Sun Nov 30, 2008 3:46 pm

IH wrote:

It is kept by default for new users, but you can turn it off on the Settings & History page everytime you login. Beside the option, there's also link to delete all past histories whenever you want.

Obtaining your history RSS is one way, the URL is hashed and salted to your account. That's why I said be careful to share that URL on only where/to who you trust.

Sweet deal thanks! Hehe you're always on the look out Wink

Posted: Sat Dec 06, 2008 12:38 pm

Awsome, so now i won't forget to comment on what I downloaded. Great new feature! Cool

Posted: Tue Dec 09, 2008 5:05 pm

Do you provide an option for a jasoncallback parameter to be passed to work correctly with crossdomain calls?

Posted: Sun Dec 14, 2008 9:21 pm

The JSON API is really a fantastic change, and I'll be integrating it soon. One suggestion: it would be great if the returned JSON also returned the total number of results (a "total" field or something along those lines) -- makes paging considerably easier, and it's something most JSON APIs support.

Any chance you could add this?

Really a great, great new feature. Hopefully I'll drive you a lot of traffic.

Posted: Tue Dec 16, 2008 4:08 pm

Excellent addition on the total_results field but I'm not sure if I understand exactly what it is- it reports a different number on each page you look at, or even how many items are on the page, and all the numbers are far below what isoHunt itself reports for the total results of a search. It doesn't seem to be the number of pages either. Could you clarify the semantics for this?

Posted: Tue Dec 16, 2008 6:36 pm

You were looking before I've tested it much, it was bugged Wink

total_results is new variable in returned JSON results, which tells you the total results per search.

Posted: Tue Dec 16, 2008 9:47 pm

Ahh. I only knew about it because of a bug in my app which made it stop working when the result fields changed Razz

. Thanks for clarifying.

Posted: Sat Dec 20, 2008 7:12 pm

Thanks for your responsiveness on this. Looks good functionality-wise to me. Great addition!

IH wrote:

You were looking before I've tested it much, it was bugged Wink

total_results is new variable in returned JSON results, which tells you the total results per search.